libtracefs man pages
v3 cover libtracefs man pages
Initial implementation of libtracefs man pages.
v3 changes:
- Removed accpeted patches from the set.
- Fixed description of the tracing_dir parameter, to be the same in all man pages.
- Removed "<event-parse.h>" includes.
v2 changes:
- Removed tracefs_find_tracing_dir() API
- Renamed tracefs_get_tracing_dir() to tracefs_tracing_dir()
- Removed any references to "#include <event-parse.h>"
- Rewrote some descriptions, as suggested by Steven.
Tzvetomir Stoyanov (VMware) (2):
libtracefs man pages: APIs for initializing a tep handler with trace
events from the local system.
libtracefs man pages: helper APIs for working with trace file system.
Documentation/libtracefs-events-tep.txt | 130 ++++++++++++++++++++++++ Documentation/libtracefs-utils.txt | 103 +++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 Documentation/libtracefs-events-tep.txt create mode 100644 Documentation/libtracefs-utils.txt
Signature · 1 line
2.28.0
PATCH v3 1/2 libtracefs man pages: APIs for initializing a tep handler with trace events from the local system.
Documented APIs:tracefs_local_events()tracefs_local_events_system()tracefs_fill_local_events()
--- Documentation/libtracefs-events-tep.txt | 130 ++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 Documentation/libtracefs-events-tep.txt
Documentation/libtracefs-events-tep.txt new file +130 -0
@@ -0,0 +1,130 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_local_events, tracefs_local_events_system, tracefs_fill_local_events - +Initialize a tep handler with trace events from the local system. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_); +struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_); +int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_); + +-- + +DESCRIPTION +----------- +Functions for initializing a tep handler with trace events from the local system. + +The _tracefs_local_events()_ function allocates a new _tep_ handler and +initializes it with events from all trace systems, located in the given +_tracing_dir_ directory. This could be NULL or the location of the tracefs +mount point for the trace systems of the local machine, or it may be a path +to a copy of the tracefs directory from another machine. + +The _tracefs_local_events_system()_ function allocates a new _tep_ handler +and initializes it with events from specified trace systems _sys_names_, +located in the given _tracing_dir_ directory. This could be NULL or the +location of the tracefs mount point for the trace systems of the local +machine, or it may be a path to a copy of the tracefs directory from another +machine. The _sys_names_ argument is an array of trace system names, that +will be used for _tep_ handler initialization. The last element in that +array must be a NULL pointer. + +The _tracefs_fill_local_events()_ function initializes already allocated _tep_ +handler with events from all trace systems, located in the given _tracing_dir_ +directory. This could be NULL or the location of the tracefs mount point +for the trace systems of the local machine, or it may be a path to a copy +of the tracefs directory from another machine. The _tep_ argument must be +a pointer to already allocated tep handler, that is going to be initialized. +The _parsing_failures_ argument could be NULL or a pointer to an integer, +where the number of failures while parsing the event files are returned. + +RETURN VALUE +------------ +The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions +return pointer to allocated and initialized _tep_ handler, or NULL in +case of an error. The returned _tep_ handler must be freed with _tep_free(3)_. + +The _tracefs_fill_local_events()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +struct tep_event *tep; +... + tep = tracefs_local_events(NULL); + if (!tep) { + /* Failed to initialise tep handler with local events from top instance */ + ... + } +... + tep_free(tep); +... + const char *systems[] = {"ftrace", "irq", NULL}; + tep = tracefs_local_events_system(NULL, systems); + if (!tep) { + /* Failed to initialise tep handler with local events from + * ftrace and irq systems in top instance. + */ + ... + } +... + tep_free(tep); +... + int parsing_failures; + tep = tep_alloc(); + if (!tep) { + /* Failed to allocate a tep handler */ + ... + } + if (tracefs_fill_local_events(NULL, tep, &parsing_failures) < 0) { + /* Failed to initialise tep handler with local events from top instance */ + } +... + tep_free(tep); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
PATCH v3 2/2 libtracefs man pages: helper APIs for working with trace file system.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_tracers()tracefs_get_clock()tracefs_list_free()
--- Documentation/libtracefs-utils.txt | 103 +++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Documentation/libtracefs-utils.txt
Documentation/libtracefs-utils.txt new file +103 -0
@@ -0,0 +1,103 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_tracers, tracefs_get_clock, tracefs_list_free - +Helper functions for working with trace file system. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); +char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_); +void *tracefs_list_free*(char pass:[*]pass:[*]_list_); +-- + +DESCRIPTION +----------- +Various useful functions for working with trace file system. + +The _tracefs_tracers()_ function returns array of strings with the +names of supported tracer plugins, located in the given _tracing_dir_ +directory. This could be NULL or the location of the tracefs mount point +for the trace systems of the local machine, or it may be a path to a copy +of the tracefs directory from another machine. The last entry in the array +as a NULL pointer. The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_get_clock()_ function returns name of the current trace clock, +used in the given _instance_. If _instance_ is NULL, the clock of the main +trace instance is returned. The returned string must be freed with free(). + +The _tracefs_list_free()_ function frees an array of strings, returned by +_tracefs_event_systems()_, _tracefs_system_events()_ and _tracefs_tracers()_ +APIs. + +RETURN VALUE +------------ +The _tracefs_tracers()_ returns array of strings. The last element in that +array is a NULL pointer. The array must be freed with _tracefs_list_free()_ API. +In case of an error, NULL is returned. + +The _tracefs_get_clock()_ returns string, that must be freed with free(), or NULL +in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +char **tracers = tracefs_tracers(NULL); + + if (tracers) { + /* Got tracer plugins from the top trace instance */ + ... + tracefs_list_free(tracers); + } +.... +char *clock = tracefs_get_clock(NULL); + + if (clock) { + /* Got current trace clock of the top trace instance */ + ... + free(clock); + } +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0