diff options
Diffstat (limited to 'Documentation/libtraceevent-handle.txt')
| -rw-r--r-- | Documentation/libtraceevent-handle.txt | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/Documentation/libtraceevent-handle.txt b/Documentation/libtraceevent-handle.txt new file mode 100644 index 0000000..64528eb --- /dev/null +++ b/Documentation/libtraceevent-handle.txt @@ -0,0 +1,108 @@ +libtraceevent(3) +================ + +NAME +---- +tep_alloc, tep_free,tep_ref, tep_unref,tep_get_ref, tep_kbuffer - Create, destroy, manage +references of trace event parser context. + +SYNOPSIS +-------- +[verse] +-- +*#include <event-parse.h>* + +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_get_ref*(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. + +The *tep_kbuffer()* function allocates a kbuffer descriptor that can be used to +parse raw data that is represented by the _tep_ handle descriptor. It must be freed +with *kbuf_free(3)*. + +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. + +*tep_kbuffer()* returns a kbuffer descriptor that can parse the raw data that +represents the tep handle. Must be freed with *kbuf_free(3)*. + +EXAMPLE +------- +[source,c] +-- +#include <event-parse.h> + +... +struct tep_handle *tep = tep_alloc(); +... +int ref = tep_get_ref(tep); +tep_ref(tep); +if ( (ref+1) != tep_get_ref(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* <rostedt@goodmis.org>, author of *libtraceevent*. +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ |