1libtraceevent(3) 2================ 3 4NAME 5---- 6tep_alloc, tep_free,tep_ref, tep_unref,tep_get_ref, tep_kbuffer - Create, destroy, manage 7references of trace event parser context. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <event-parse.h>* 14 15struct tep_handle pass:[*]*tep_alloc*(void); 16void *tep_free*(struct tep_handle pass:[*]_tep_); 17void *tep_ref*(struct tep_handle pass:[*]_tep_); 18void *tep_unref*(struct tep_handle pass:[*]_tep_); 19int *tep_get_ref*(struct tep_handle pass:[*]_tep_); 20struct kbuffer pass:[*]*tep_kbuffer*(struct tep_handle pass:[*]_tep_); 21-- 22 23DESCRIPTION 24----------- 25These are the main functions to create and destroy tep_handle - the main 26structure, representing the trace event parser context. This context is used as 27the input parameter of most library APIs. 28 29The *tep_alloc()* function allocates and initializes the tep context. 30 31The *tep_free()* function will decrement the reference of the _tep_ handler. 32When there is no more references, then it will free the handler, as well 33as clean up all its resources that it had used. The argument _tep_ is 34the pointer to the trace event parser context. 35 36The *tep_ref()* function adds a reference to the _tep_ handler. 37 38The *tep_unref()* function removes a reference from the _tep_ handler. When 39the last reference is removed, the _tep_ is destroyed, and all resources that 40it had used are cleaned up. 41 42The *tep_ref_get()* functions gets the current references of the _tep_ handler. 43 44The *tep_kbuffer()* function allocates a kbuffer descriptor that can be used to 45parse raw data that is represented by the _tep_ handle descriptor. It must be freed 46with *kbuf_free(3)*. 47 48RETURN VALUE 49------------ 50*tep_alloc()* returns a pointer to a newly created tep_handle structure. 51NULL is returned in case there is not enough free memory to allocate it. 52 53*tep_ref_get()* returns the current references of _tep_. 54If _tep_ is NULL, 0 is returned. 55 56*tep_kbuffer()* returns a kbuffer descriptor that can parse the raw data that 57represents the tep handle. Must be freed with *kbuf_free(3)*. 58 59EXAMPLE 60------- 61[source,c] 62-- 63#include <event-parse.h> 64 65... 66struct tep_handle *tep = tep_alloc(); 67... 68int ref = tep_get_ref(tep); 69tep_ref(tep); 70if ( (ref+1) != tep_get_ref(tep)) { 71 /* Something wrong happened, the counter is not incremented by 1 */ 72} 73tep_unref(tep); 74... 75tep_free(tep); 76... 77-- 78FILES 79----- 80[verse] 81-- 82*event-parse.h* 83 Header file to include in order to have access to the library APIs. 84*-ltraceevent* 85 Linker switch to add when building a program that uses the library. 86-- 87 88SEE ALSO 89-------- 90*libtraceevent*(3), *trace-cmd*(1) 91 92AUTHOR 93------ 94[verse] 95-- 96*Steven Rostedt* <[email protected]>, author of *libtraceevent*. 97*Tzvetomir Stoyanov* <[email protected]>, author of this man page. 98-- 99REPORTING BUGS 100-------------- 101Report bugs to <[email protected]> 102 103LICENSE 104------- 105libtraceevent is Free Software licensed under the GNU LGPL 2.1 106 107RESOURCES 108--------- 109https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ 110