'\" t
.\"     Title: libtraceevent
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/23/2021
.\"    Manual: libtraceevent Manual
.\"    Source: libtraceevent 1.3.0
.\"  Language: English
.\"
.TH "LIBTRACEEVENT" "3" "05/23/2021" "libtraceevent 1\&.3\&.0" "libtraceevent Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
tep_register_comm, tep_override_comm, tep_pid_is_registered, tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid \- Manage pid to process name mappings\&.
.SH "SYNOPSIS"
.sp
.nf
\fB#include <event\-parse\&.h>\fR

int \fBtep_register_comm\fR(struct tep_handle *\fItep\fR, const char *\fIcomm\fR, int \fIpid\fR);
int \fBtep_override_comm\fR(struct tep_handle *\fItep\fR, const char *\fIcomm\fR, int \fIpid\fR);
bool \fBtep_is_pid_registered\fR(struct tep_handle *\fItep\fR, int \fIpid\fR);
const char *\fBtep_data_comm_from_pid\fR(struct tep_handle *\fIpevent\fR, int \fIpid\fR);
struct cmdline *\fBtep_data_pid_from_comm\fR(struct tep_handle *\fIpevent\fR, const char *\fIcomm\fR, struct cmdline *\fInext\fR);
int \fBtep_cmdline_pid\fR(struct tep_handle *\fIpevent\fR, struct cmdline *\fIcmdline\fR);
.fi
.SH "DESCRIPTION"
.sp
These functions can be used to handle the mapping between pid and process name\&. The library builds a cache of these mappings, which is used to display the name of the process, instead of its pid\&. This information can be retrieved from tracefs/saved_cmdlines file\&.
.sp
The \fItep_register_comm()\fR function registers a \fIpid\fR / process name mapping\&. If a command with the same \fIpid\fR is already registered, an error is returned\&. The \fIpid\fR argument is the process ID, the \fIcomm\fR argument is the process name, \fItep\fR is the event context\&. The \fIcomm\fR is duplicated internally\&.
.sp
The \fItep_override_comm()\fR function registers a \fIpid\fR / process name mapping\&. If a process with the same pid is already registered, the process name string is udapted with the new one\&. The \fIpid\fR argument is the process ID, the \fIcomm\fR argument is the process name, \fItep\fR is the event context\&. The \fIcomm\fR is duplicated internally\&.
.sp
The \fItep_is_pid_registered()\fR function checks if a pid has a process name mapping registered\&. The \fIpid\fR argument is the process ID, \fItep\fR is the event context\&.
.sp
The \fItep_data_comm_from_pid()\fR function returns the process name for a given pid\&. The \fIpid\fR argument is the process ID, \fItep\fR is the event context\&. The returned string should not be freed, but will be freed when the \fItep\fR handler is closed\&.
.sp
The \fItep_data_pid_from_comm()\fR function returns a pid for a given process name\&. The \fIcomm\fR argument is the process name, \fItep\fR is the event context\&. The argument \fInext\fR is the cmdline structure to search for the next pid\&. As there may be more than one pid for a given process, the result of this call can be passed back into a recurring call in the \fInext\fR parameter, to search for the next pid\&. If \fInext\fR is NULL, it will return the first pid associated with the \fIcomm\fR\&. The function performs a linear search, so it may be slow\&.
.sp
The \fItep_cmdline_pid()\fR function returns the pid associated with a given \fIcmdline\fR\&. The \fItep\fR argument is the event context\&.
.SH "RETURN VALUE"
.sp
\fItep_register_comm()\fR function returns 0 on success\&. In case of an error \-1 is returned and errno is set to indicate the cause of the problem: ENOMEM, if there is not enough memory to duplicate the \fIcomm\fR or EEXIST if a mapping for this \fIpid\fR is already registered\&.
.sp
\fItep_override_comm()\fR function returns 0 on success\&. In case of an error \-1 is returned and errno is set to indicate the cause of the problem: ENOMEM, if there is not enough memory to duplicate the \fIcomm\fR\&.
.sp
\fItep_is_pid_registered()\fR function returns true if the \fIpid\fR has a process name mapped to it, false otherwise\&.
.sp
\fItep_data_comm_from_pid()\fR function returns the process name as string, or the string "<\&...>" if there is no mapping for the given pid\&.
.sp
\fItep_data_pid_from_comm()\fR function returns a pointer to a struct cmdline, that holds a pid for a given process, or NULL if none is found\&. This result can be passed back into a recurring call as the \fInext\fR parameter of the function\&.
.sp
\fItep_cmdline_pid()\fR functions returns the pid for the give cmdline\&. If \fIcmdline\fR is NULL, then \-1 is returned\&.
.SH "EXAMPLE"
.sp
The following example registers pid for command "ls", in context of event \fItep\fR and performs various searches for pid / process name mappings:
.sp
.if n \{\
.RS 4
.\}
.nf
#include <event\-parse\&.h>
\&.\&.\&.
int ret;
int ls_pid = 1021;
struct tep_handle *tep = tep_alloc();
\&.\&.\&.
        ret = tep_register_comm(tep, "ls", ls_pid);
        if (ret != 0 && errno == EEXIST)
                ret = tep_override_comm(tep, "ls", ls_pid);
        if (ret != 0) {
                /* Failed to register pid / command mapping */
        }
\&.\&.\&.
        if (tep_is_pid_registered(tep, ls_pid) == 0) {
                /* Command mapping for ls_pid is not registered */
        }
\&.\&.\&.
        const char *comm = tep_data_comm_from_pid(tep, ls_pid);
        if (comm) {
                /* Found process name for ls_pid */
        }
\&.\&.\&.
        int pid;
        struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL);
        while (cmd) {
                pid = tep_cmdline_pid(tep, cmd);
                /* Found pid for process "ls" */
                cmd = tep_data_pid_from_comm(tep, "ls", cmd);
        }
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBevent\-parse\&.h\fR
        Header file to include in order to have access to the library APIs\&.
\fB\-ltraceevent\fR
        Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fIlibtraceevent(3)\fR, \fItrace\-cmd(1)\fR
.SH "AUTHOR"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2>, author of \fBlibtraceevent\fR\&.
\fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2>, author of this man page\&.
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[3]\d\s+2>
.SH "LICENSE"
.sp
libtraceevent is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtraceevent\&.git/\fR\m[]
.SH "NOTES"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE
.IP " 2." 4
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE
.IP " 3." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE