From patchwork Fri Nov 9 13:31:47 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759701 Return-Path: Received: from mail-cys01nam02on0045.outbound.protection.outlook.com ([104.47.37.45]:45184 "EHLO NAM02-CY1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727794AbeKIXM3 (ORCPT ); Fri, 9 Nov 2018 18:12:29 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 01/11] tools/lib/traceevent: Fix libtraceevent/Documentation Makefile Date: Fri, 9 Nov 2018 13:31:47 +0000 Message-ID: <20181109133135.25804-2-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 1216 As libtraceevent/Documentation Makefile and all XLS files were taken from tools/perf/Documentation, and modified for libtraceevent, this patch adds a note on the top of the Makefile to state it. It also fixes the "clean" rule, to clean up compiled man pages. Signed-off-by: Tzvetomir Stoyanov --- tools/lib/traceevent/Documentation/Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/lib/traceevent/Documentation/Makefile b/tools/lib/traceevent/Documentation/Makefile index b975080a6705..8a4693571cef 100644 --- a/tools/lib/traceevent/Documentation/Makefile +++ b/tools/lib/traceevent/Documentation/Makefile @@ -1,6 +1,9 @@ include ../../../scripts/Makefile.include include ../../../scripts/utilities.mak +# This Makefile and manpage XSL files were taken from tools/perf/Documentation +# and modified for libtraceevent. + MAN3_TXT= \ $(wildcard libtraceevent-*.txt) \ libtraceevent.txt @@ -174,7 +177,7 @@ endif CLEAN_FILES = \ $(MAN_XML) $(addsuffix +,$(MAN_XML)) \ $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \ - $(DOC_MAN3) + $(DOC_MAN3) *.3 clean: $(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES) From patchwork Fri Nov 9 13:31:49 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759703 Return-Path: Received: from mail-eopbgr810052.outbound.protection.outlook.com ([40.107.81.52]:16416 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727784AbeKIXM3 (ORCPT ); Fri, 9 Nov 2018 18:12:29 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 02/11] tools/lib/traceevent: Add support for man pages with multiple names Date: Fri, 9 Nov 2018 13:31:49 +0000 Message-ID: <20181109133135.25804-3-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2190 This patch adds support for man pages with multiple names, used to combine the description of several APIs into one page. Signed-off-by: Tzvetomir Stoyanov --- .../traceevent/Documentation/asciidoc.conf | 35 +++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/tools/lib/traceevent/Documentation/asciidoc.conf b/tools/lib/traceevent/Documentation/asciidoc.conf index 1b03c63fb73a..07595717f06e 100644 --- a/tools/lib/traceevent/Documentation/asciidoc.conf +++ b/tools/lib/traceevent/Documentation/asciidoc.conf @@ -74,12 +74,41 @@ template::[header-declarations] {mantitle} {manvolnum} -trace-cmd +libtraceevent {libtraceevent_version} -trace-cmd Manual +libtraceevent Manual - {manname} + {manname1} + {manname2} + {manname3} + {manname4} + {manname5} + {manname6} + {manname7} + {manname8} + {manname9} + {manname10} + {manname11} + {manname12} + {manname13} + {manname14} + {manname15} + {manname16} + {manname17} + {manname18} + {manname19} + {manname20} + {manname21} + {manname22} + {manname23} + {manname24} + {manname25} + {manname26} + {manname27} + {manname28} + {manname29} + {manname30} {manpurpose} endif::backend-docbook[] From patchwork Fri Nov 9 13:31:50 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759705 Return-Path: Received: from mail-eopbgr810079.outbound.protection.outlook.com ([40.107.81.79]:10688 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727784AbeKIXMg (ORCPT ); Fri, 9 Nov 2018 18:12:36 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 03/11] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs Date: Fri, 9 Nov 2018 13:31:50 +0000 Message-ID: <20181109133135.25804-4-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 15488 This patch adds 4 new man pages for: tep_register_comm,tep_pid_is_registered,tep_data_comm_from_pid, tep_data_pid_from_comm,tep_cmdline_pid,tep_alloc,tep_free,tep_get_long_size, tep_set_long_size,tep_set_flag, as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-commands.txt | 130 ++++++++++++++++++ .../Documentation/libtraceevent-handle.txt | 101 ++++++++++++++ .../Documentation/libtraceevent-long_size.txt | 79 +++++++++++ .../Documentation/libtraceevent-set_flag.txt | 94 +++++++++++++ tools/lib/traceevent/event-parse-api.c | 9 +- 5 files changed, 410 insertions(+), 3 deletions(-) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-commands.txt b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt new file mode 100644 index 000000000000..f27151dd3101 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt @@ -0,0 +1,130 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_comm,tep_pid_is_registered,tep_data_comm_from_pid,tep_data_pid_from_comm,tep_cmdline_pid - handle pid to process name mappings + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); +int *tep_pid_is_registered*(struct tep_handle pass:[*]_tep_, int _pid_); +const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_); +struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_); +int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_); +-- + +DESCRIPTION +----------- +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. It is also saved in trace.dat file. + +The _tep_register_comm()_ function registers a pid / process name mapping. +The _pid_ argument is the process ID, the _comm_ argument is the process name, +_tep_ is the event context. The _comm_ is copied internally. + +The _tep_pid_is_registered()_ function checks if a pid has a process name mapping +registered. The _pid_ argument is the process ID, _tep_ is the event context. + +The _tep_data_comm_from_pid()_ function returns the process name for a given pid. +The _pid_ argument is the process ID, _tep_ is the event context. The returned +string should not be freed, but will be freed when the _tep_ handler is closed. + +The _tep_data_pid_from_comm()_ function returns a pid for a given process name. +The _comm_ argument is the process name, _tep_ is the event context. +The argument _next_ 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 _next_ parameter, to search for +the next pid. If _next_ is NULL, it will return the first pid associated with +the _comm_. The function performs a linear search, so it may be slow. + +The _tep_cmdline_pid()_ function returns the pid associated with a given _cmdline_. +The _tep_ argument is the event context. + +RETURN VALUE +------------ +_tep_register_comm()_ function returns 0 on success, or -1 in case of an error. + +_tep_pid_is_registered()_ function returns 1 if the _pid_ has a process name +mapped to it, 0 otherwise. + +_tep_data_comm_from_pid()_ function returns the process name as string, or the +string "<...>" if there is no mapping for the given pid. + +_tep_data_pid_from_comm()_ 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 _next_ parameter of the function. + +_tep_cmdline_pid()_ functions returns the pid for the give cmdline. If _cmdline_ + is NULL, then -1 is returned. + +EXAMPLE +------- +The following example registers pid for command "ls", in context of event _tep_ +and performs various searches for pid / process name mappings: +[source,c] +-- +#include +... +int ls_pid = 1021; +struct tep_handle *tep = tep_alloc(); +... + if (tep_register_comm(tep, "ls", ls_pid) != 0) { + /* Failed to register pid / command mapping */ + } +.... + if (tep_pid_is_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); + } +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-handle.txt b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt new file mode 100644 index 000000000000..4fda29c2e607 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt @@ -0,0 +1,101 @@ +libtraceevent(3) +================ + +NAME +---- +tep_alloc,tep_free,tep_ref,tep_unref,tep_ref_get - Create, destroy manage +references of trace event parser context. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_handle pass:[*]*tep_alloc*(void); +void *tep_free*(struct tep_handle pass:[*]_tep_); +void *tep_ref*(struct tep_handle pass:[*]_tep_); +void *tep_unref*(struct tep_handle pass:[*]_tep_); +int *tep_ref_get*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +These are the main functions to create and destroy tep_handle - the main +structure, representing the trace event parser context. This context is used as +the input parameter of most library APIs. + +The _tep_alloc()_ function allocates and initializes the tep context. + +The _tep_free()_ function will decrement the reference of the _tep_ handler. +When there is no more references, then it will free the handler, as well +as clean up all its resources that it had used. The argument _tep_ is +the pointer to the trace event parser context. + +The _tep_ref()_ function adds a reference to the _tep_ handler. + +The _tep_unref()_ function removes a reference from the _tep_ handler. When +the last reference is removed, the _tep_ is destroyed, and all resources that +it had used are cleaned up. + +The _tep_ref_get()_ functions gets the current references of the _tep_ handler. + +RETURN VALUE +------------ +_tep_alloc()_ returns a pointer to a newly created tep_handle structure. +NULL is returned in case there is not enough free memory to allocate it. + +_tep_ref_get()_ returns the current references of _tep_. +If _tep_ is NULL, 0 is returned. + +EXAMPLE +------- +[source,c] +-- +#include + +... +struct tep_handle *tep = tep_alloc(); +... +int ref = tep_ref_get(tep); +tep_ref(tep); +if ( (ref+1) != tep_ref_get(tep)) { + /* Something wrong happened, the counter is not incremented by 1 */ +} +tep_unref(tep); +... +tep_free(tep); +... +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt new file mode 100644 index 000000000000..ce7fb063a8da --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt @@ -0,0 +1,79 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_long_size,tep_set_long_size - Get / set the size of a long integer on +the machine, where the trace is generated, in bytes + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_); +void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_); +-- + +DESCRIPTION +----------- +The _tep_get_long_size()_ function returns the size of a long integer on the machine, +where the trace is generated. The _tep_ argument is trace event parser context. + +The _tep_set_long_size()_ function sets the size of a long integer on the machine, +where the trace is generated. The _tep_ argument is trace event parser context. +The _long_size_ is the size of a long integer, in bytes. +This information is saved in the trace.dat file. + +RETURN VALUE +------------ +The _tep_get_long_size()_ function returns the size of a long integer on the machine, +where the trace is generated, in bytes. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +tep_set_long_size(tep, 4); +... +int long_size = tep_get_long_size(tep); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt new file mode 100644 index 000000000000..e5393610cfca --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt @@ -0,0 +1,94 @@ +libtraceevent(3) +================ + +NAME +---- +tep_set_flag - Set a flag or combination of flags of trace event parser context + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_flag* { + _TEP_NSEC_OUTPUT_, + _TEP_DISABLE_SYS_PLUGINS_, + _TEP_DISABLE_PLUGINS_ +}; +void *tep_set_flag*(struct tep_handle pass:[*]_tep_, int _flag_); +-- + +DESCRIPTION +----------- +[verse] +-- +The _tep_set_flag()_ function sets _flag_ or any combination of flags to _tep_ context. +Flags are defined in *enum tep_flag*: + _TEP_NSEC_OUTPUT_ - print event's timestamp in nano seconds, instead of micro seconds. + _TEP_DISABLE_SYS_PLUGINS_ - disable plugins, located in system's plugin directory. + This directory is defined at library compile time, and usually + depends on library installation prefix: (install_preffix)/lib/traceevent/plugins + _TEP_DISABLE_PLUGINS_ - disable all library plugins: + - in system's plugin directory + - in directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_ + - in user's home directory, _~/.traceevent/plugins_ + +Note: plugin related flags must me set before calling _tep_load_plugins()_ API. +-- + +RETURN VALUE +------------ +_tep_set_flag()_ functions has no return value. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +/* Set printing of timestamps in nano seconds and disable system plugins */ +tep_set_flag(tep, TEP_NSEC_OUTPUT | TEP_DISABLE_SYS_PLUGINS); +... +/* Disable all library plugins */ +tep_set_flag(tep, TEP_DISABLE_PLUGINS); +... +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*trace-seq.h* + Header file to include in order to have access to trace sequences related APIs. + Trace sequences are used to allow a function to call several other functions + to create a string of data to use. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c index 52188921cfe3..c0fb86e29aac 100644 --- a/tools/lib/traceevent/event-parse-api.c +++ b/tools/lib/traceevent/event-parse-api.c @@ -140,10 +140,12 @@ void tep_set_cpus(struct tep_handle *pevent, int cpus) } /** - * tep_get_long_size - get the size of a long integer on the current machine + * tep_get_long_size - get the size of a long integer on the machine, + * where the trace is generated * @pevent: a handle to the tep_handle * - * This returns the size of a long integer on the current machine + * This returns the size of a long integer on the machine, + * where the trace is generated * If @pevent is NULL, 0 is returned. */ int tep_get_long_size(struct tep_handle *pevent) @@ -154,7 +156,8 @@ int tep_get_long_size(struct tep_handle *pevent) } /** - * tep_set_long_size - set the size of a long integer on the current machine + * tep_set_long_size - set the size of a long integer on the machine, + * where the trace is generated * @pevent: a handle to the tep_handle * @size: size, in bytes, of a long integer * From patchwork Fri Nov 9 13:31:51 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759717 Return-Path: Received: from mail-eopbgr810050.outbound.protection.outlook.com ([40.107.81.50]:60028 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727784AbeKIXNR (ORCPT ); Fri, 9 Nov 2018 18:13:17 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 05/11] tools/lib/traceevent: Man page for tep_get_header_page_size() Date: Fri, 9 Nov 2018 13:31:51 +0000 Message-ID: <20181109133135.25804-5-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3092 Create a man page for tep_get_header_page_size(), as part of the libtraceevent API. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-header_size.txt | 73 +++++++++++++++++++ tools/lib/traceevent/event-parse-api.c | 4 +- 2 files changed, 75 insertions(+), 2 deletions(-) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt new file mode 100644 index 000000000000..8edf49d2a709 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt @@ -0,0 +1,73 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_header_page_size - Get the size of a long integer, in kernel context. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_); + +-- +DESCRIPTION +----------- +The _tep_get_header_page_size()_ function returns the size of a long integer, +in kernel context. The _tep_ argument is trace event parser context. +This information is retrieved from /sys/kernel/debug/tracing/events/header_page, + "commit" field. + +RETURN VALUE +------------ +The _tep_get_header_page_size()_ function returns the size of a long integer, +in bytes + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + int lsize = tep_get_header_page_size(tep); + printf ("The size of a long in kernel context is %d bytes", lsize); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c index c0bbd7864f53..9137862261a5 100644 --- a/tools/lib/traceevent/event-parse-api.c +++ b/tools/lib/traceevent/event-parse-api.c @@ -100,10 +100,10 @@ tep_data2host8(struct tep_handle *pevent, unsigned long long data) } /** - * tep_get_header_page_size - get size of the header page + * tep_get_header_page_size - get the size of a long integer, in kernel context * @pevent: a handle to the tep_handle * - * This returns size of the header page + * This returns the size of a long integer, in kernel context * If @pevent is NULL, 0 is returned. */ int tep_get_header_page_size(struct tep_handle *pevent) From patchwork Fri Nov 9 13:31:52 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759713 Return-Path: Received: from mail-eopbgr810079.outbound.protection.outlook.com ([40.107.81.79]:10688 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727843AbeKIXMi (ORCPT ); Fri, 9 Nov 2018 18:12:38 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 06/11] tools/lib/traceevent: Man page for tep_get_cpus() and tep_set_cpus() Date: Fri, 9 Nov 2018 13:31:52 +0000 Message-ID: <20181109133135.25804-6-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2456 Create man pages for tep_get_cpus() and tep_set_cpus() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-cpus.txt | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file mode 100644 index 000000000000..81d9b4c83bee --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_cpus,tep_set_cpus - Get / set the number of CPUs, which have tracing +data recorded. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_cpus*(struct tep_handle pass:[*]_tep_); +void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_); +-- + +DESCRIPTION +----------- +The _tep_get_cpus()_ function gets the number of CPUs, which have tracing +data recorded in the _tep_ context. The _tep_ argument is trace event parser +context. + +The _tep_set_cpus()_ function sets the number of CPUs, which have tracing +data recorded. The _tep_ argument is trace event parser context. The _cpu_ +argument is the number of CPUs with tracing data. + +RETURN VALUE +------------ +The _tep_get_cpus()_ functions returns the number of CPUs, which have tracing +data recorded. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_cpus(tep, 5); +... + printf("We have tracing data for %d CPUs", tep_get_cpus(tep)); +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Nov 9 13:31:53 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759707 Return-Path: Received: from mail-eopbgr810079.outbound.protection.outlook.com ([40.107.81.79]:10688 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727800AbeKIXMj (ORCPT ); Fri, 9 Nov 2018 18:12:39 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 07/11] tools/lib/traceevent: Man page for tep_is_file_bigendian() and tep_set_file_bigendian() Date: Fri, 9 Nov 2018 13:31:53 +0000 Message-ID: <20181109133135.25804-7-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2876 Create man pages for tep_is_file_bigendian() and tep_set_file_bigendian() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-file_endian.txt | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt new file mode 100644 index 000000000000..5b8e01235eda --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt @@ -0,0 +1,89 @@ +libtraceevent(3) +================ + +NAME +---- +tep_is_file_bigendian,tep_set_file_bigendian - Get / set the endianess of the +raw data, being accessed by the tep handler. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_endian* { + TEP_LITTLE_ENDIAN = 0, + TEP_BIG_ENDIAN +}; + +int *tep_is_file_bigendian*(struct tep_handle pass:[*]_tep_); +void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_); + +-- +DESCRIPTION +----------- +The _tep_is_file_bigendian()_ function returns the endianess of the raw data, +being accessed by the tep handler. The _tep_ argument is trace event parser context. + +The _tep_set_file_bigendian()_ set the endianess of raw data, the being accessed +by the tep handler. The _tep_ argument is trace event parser context. +[verse] +-- +The _endian_ argument is the endianess: + _TEP_LITTLE_ENDIAN_ - the raw data is in little endian format, + _TEP_BIG_ENDIAN_ - the raw data is in big endian format. +-- +RETURN VALUE +------------ +The _tep_is_file_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_file_bigendian(tep, TEP_LITTLE_ENDIAN); +... + if (TEP_BIG_ENDIAN == tep_is_file_bigendian(tep)) { + /* The raw data is in big endian */ + } else { + /* The raw data is in little endian */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Nov 9 13:31:55 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759709 Return-Path: Received: from mail-eopbgr810079.outbound.protection.outlook.com ([40.107.81.79]:10688 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727667AbeKIXMk (ORCPT ); Fri, 9 Nov 2018 18:12:40 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 08/11] tools/lib/traceevent: Man page for tep_is_host_bigendian() and tep_set_host_bigendian() Date: Fri, 9 Nov 2018 13:31:55 +0000 Message-ID: <20181109133135.25804-8-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2865 Create man pages for tep_is_host_bigendian() and tep_set_host_bigendian() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-host_endian.txt | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file mode 100644 index 000000000000..250eb430c06a --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt @@ -0,0 +1,90 @@ +libtraceevent(3) +================ + +NAME +---- +tep_is_host_bigendian,tep_set_host_bigendian,tep_host_bigendian - Get / set the endianess of +the machine running the current code. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_endian* { + TEP_LITTLE_ENDIAN = 0, + TEP_BIG_ENDIAN +}; + +int *tep_is_host_bigendian*(struct tep_handle pass:[*]_tep_); +void *tep_set_host_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_); +int tep_host_bigendian(void); +-- + +DESCRIPTION +----------- +The _tep_is_host_bigendian()_ function returns the endianess of the the machine +running the current code. The _tep_ argument is trace event parser context. + +The _tep_set_host_bigendian()_ set the endianess of the machine running the code. +The _tep_ argument is trace event parser context. The _endian_ argument is the endianess: +[verse] +-- + _TEP_LITTLE_ENDIAN_ - the machine is little endian, + _TEP_BIG_ENDIAN_ - the machine is big endian. +-- + +RETURN VALUE +------------ +The _tep_is_host_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_host_bigendian(tep, TEP_LITTLE_ENDIAN); +... + if (TEP_BIG_ENDIAN == tep_is_host_bigendian(tep)) { + /* The local host is big endian */ + } else { + /* The local host is little endian */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Nov 9 13:31:56 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759711 Return-Path: Received: from mail-eopbgr810079.outbound.protection.outlook.com ([40.107.81.79]:10688 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727800AbeKIXMl (ORCPT ); Fri, 9 Nov 2018 18:12:41 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 09/11] tools/lib/traceevent: Man page for tep_is_latency_format() and tep_set_latency_format() Date: Fri, 9 Nov 2018 13:31:56 +0000 Message-ID: <20181109133135.25804-9-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3716 Create man pages for tep_is_latency_format() and tep_set_latency_format() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-latency_format.txt | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file mode 100644 index 000000000000..4b0d7d3f6ae9 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt @@ -0,0 +1,100 @@ +libtraceevent(3) +================ + +NAME +---- +tep_set_latency_format,tep_is_latency_format - Get / set "latency output" format. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_); +int *tep_is_latency_format*(struct tep_handle pass:[*]_tep_); + +-- + +DESCRIPTION +----------- +"Latency output" format prints information about interrupts being disabled, +soft irq being disabled, the "need_resched" flag being set and preempt count. +This information is recorded with every event, but by default is not printed. + +The _tep_set_latency_format()_ function enables the "latency output" printing. +The _tep_ argument is trace event parser context. The _lat_ argument can be zero, +for "latency output" disabled, or non zero for "latency output" enabled. +Information is displayed with 6 characters. When a field is zero, or N/A, a pass:['.'] +is printed. Example: +[verse] +-- + -0 0d.h1. 106467.859747: function: ktime_get <-- tick_check_idle +-- +The 0d.h1. denotes this information. The first character is never a pass:['.'] +and represents what CPU the trace was recorded on (CPU 0). The pass:['d'] denotes +that interrupts were disabled. The pass:['h'] means that this was called inside +an interrupt handler. The pass:['1'] is the preemption disabled (preempt_count) +was set to one. The two pass:['.']s are "need_resched" flag and kernel lock +counter. If the "need_resched" flag is set, then that character would be a pass:['N']. + +The _tep_is_latency_format()_ function returns if "latency output" is enabled. + +This "Latency output" setting affects output of _tep_print_event_task()_ +and _tep_print_event_time()_ APIs. + +RETURN VALUE +------------ + +The _tep_is_latency_format()_ function returns non zero if "latency output" +is enabled, or zero if it is disabled. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + tep_set_latency_format(tep, 1); +... + if (tep_is_latency_format(tep)) { + /* latency output format is enabled */ + } else { + /* latency output format is disabled */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_, tep_print_event_task(3), tep_print_event_time(3) + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git From patchwork Fri Nov 9 13:31:57 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759719 Return-Path: Received: from mail-eopbgr810079.outbound.protection.outlook.com ([40.107.81.79]:10688 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727667AbeKIXNV (ORCPT ); Fri, 9 Nov 2018 18:13:21 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 10/11] tools/lib/traceevent: Man page for tep_get_page_size() and tep_set_page_size() Date: Fri, 9 Nov 2018 13:31:57 +0000 Message-ID: <20181109133135.25804-10-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 4206 Create man pages for tep_get_page_size() and tep_set_page_size() as part of the libtraceevent APIs. It also alignes description of the functions (in the C code) with the man pages. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-page_size.txt | 80 +++++++++++++++++++ tools/lib/traceevent/event-parse-api.c | 12 ++- 2 files changed, 88 insertions(+), 4 deletions(-) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt new file mode 100644 index 000000000000..015664b96197 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt @@ -0,0 +1,80 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_page_size,tep_set_page_size - Get / set the size of a memory page on the +machine, where the trace is generated + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_page_size*(struct tep_handle pass:[*]_tep_); +void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_); +-- + +DESCRIPTION +----------- +The _tep_get_page_size()_ function returns the size of a memory page on +the machine, where the trace is generated. The _tep_ argument is trace +event parser context. + +The _tep_set_page_size()_ function stores in the _tep_ context the size of a +memory page on the machine, where the trace is generated. +The _tep_ argument is trace event parser context. +The _page_size_ argument is the size of a memory page, in bytes. + +RETURN VALUE +------------ +The _tep_get_page_size()_ function returns size of the memory page, in bytes. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + int page_size = 4096; + tep_set_page_size(tep, page_size); + if ( 4096 != tep_get_page_size(tep)) { + /* Something wrong happened, page size is not set as expected */ + } +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c index 9137862261a5..39e0fca2d9a2 100644 --- a/tools/lib/traceevent/event-parse-api.c +++ b/tools/lib/traceevent/event-parse-api.c @@ -170,10 +170,12 @@ void tep_set_long_size(struct tep_handle *pevent, int long_size) } /** - * tep_get_page_size - get the size of a memory page on the current machine + * tep_get_page_size - get the size of a memory page on the machine, + * where the trace is generated * @pevent: a handle to the tep_handle * - * This returns the size of a memory page on the current machine + * This returns the size of a memory page on the machine, + * where the trace is generated * If @pevent is NULL, 0 is returned. */ int tep_get_page_size(struct tep_handle *pevent) @@ -184,11 +186,13 @@ int tep_get_page_size(struct tep_handle *pevent) } /** - * tep_set_page_size - set the size of a memory page on the current machine + * tep_set_page_size - set the size of a memory page on the machine, + * where the trace is generated * @pevent: a handle to the tep_handle * @_page_size: size of a memory page, in bytes * - * This sets the size of a memory page on the current machine + * This sets the size of a memory page on the machine, + * where the trace is generated */ void tep_set_page_size(struct tep_handle *pevent, int _page_size) { From patchwork Fri Nov 9 13:31:59 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759715 Return-Path: Received: from mail-eopbgr810083.outbound.protection.outlook.com ([40.107.81.83]:28000 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1727800AbeKIXNM (ORCPT ); Fri, 9 Nov 2018 18:13:12 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH v2 11/11] tools/lib/traceevent: Man page for tep_strerror() Date: Fri, 9 Nov 2018 13:31:59 +0000 Message-ID: <20181109133135.25804-11-tstoyanov@vmware.com> References: <20181109133135.25804-1-tstoyanov@vmware.com> In-Reply-To: <20181109133135.25804-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2600 Create man page for tep_strerror() as part of libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-strerror.txt | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt new file mode 100644 index 000000000000..fde1bd71b679 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +tep_strerror - Returns a string describing regular errno and tep error number. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_); + +-- +DESCRIPTION +----------- +The _tep_strerror()_ function converts tep error number into a human readable string. +The _tep_ argument is trace event parser context. The _errnum_ is a regular errno, +defined in errno.h, or a tep error number. The string, describing this error number +is copied in the _buf_ argument. The _buflen_ argument is the size of the _buf_. + +RETURN VALUE +------------ +The _tep_strerror()_ function returns 0, if a valid _errnum_ is passed and the +string is copied into _buf_. If _errnum_ is not a valid error number, -1 is returned +and _buf_ is not modified. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char buf[32]; +char *pool = calloc(1, 128); +if (tep == NULL) { + tep_strerror(tep, TEP_ERRNO__MEM_ALLOC_FAILED, buf, 32); + printf ("The pool is not initialized, %s", buf); +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git