0001 libtraceevent(3)
0002 ================
0003
0004 NAME
0005 ----
0006 tep_alloc, tep_free,tep_ref, tep_unref,tep_get_ref - Create, destroy, manage
0007 references of trace event parser context.
0008
0009 SYNOPSIS
0010 --------
0011 [verse]
0012 --
0013 *#include <event-parse.h>*
0014
0015 struct tep_handle pass:[*]*tep_alloc*(void);
0016 void *tep_free*(struct tep_handle pass:[*]_tep_);
0017 void *tep_ref*(struct tep_handle pass:[*]_tep_);
0018 void *tep_unref*(struct tep_handle pass:[*]_tep_);
0019 int *tep_get_ref*(struct tep_handle pass:[*]_tep_);
0020 --
0021
0022 DESCRIPTION
0023 -----------
0024 These are the main functions to create and destroy tep_handle - the main
0025 structure, representing the trace event parser context. This context is used as
0026 the input parameter of most library APIs.
0027
0028 The _tep_alloc()_ function allocates and initializes the tep context.
0029
0030 The _tep_free()_ function will decrement the reference of the _tep_ handler.
0031 When there is no more references, then it will free the handler, as well
0032 as clean up all its resources that it had used. The argument _tep_ is
0033 the pointer to the trace event parser context.
0034
0035 The _tep_ref()_ function adds a reference to the _tep_ handler.
0036
0037 The _tep_unref()_ function removes a reference from the _tep_ handler. When
0038 the last reference is removed, the _tep_ is destroyed, and all resources that
0039 it had used are cleaned up.
0040
0041 The _tep_ref_get()_ functions gets the current references of the _tep_ handler.
0042
0043 RETURN VALUE
0044 ------------
0045 _tep_alloc()_ returns a pointer to a newly created tep_handle structure.
0046 NULL is returned in case there is not enough free memory to allocate it.
0047
0048 _tep_ref_get()_ returns the current references of _tep_.
0049 If _tep_ is NULL, 0 is returned.
0050
0051 EXAMPLE
0052 -------
0053 [source,c]
0054 --
0055 #include <event-parse.h>
0056
0057 ...
0058 struct tep_handle *tep = tep_alloc();
0059 ...
0060 int ref = tep_get_ref(tep);
0061 tep_ref(tep);
0062 if ( (ref+1) != tep_get_ref(tep)) {
0063 /* Something wrong happened, the counter is not incremented by 1 */
0064 }
0065 tep_unref(tep);
0066 ...
0067 tep_free(tep);
0068 ...
0069 --
0070 FILES
0071 -----
0072 [verse]
0073 --
0074 *event-parse.h*
0075 Header file to include in order to have access to the library APIs.
0076 *-ltraceevent*
0077 Linker switch to add when building a program that uses the library.
0078 --
0079
0080 SEE ALSO
0081 --------
0082 _libtraceevent(3)_, _trace-cmd(1)_
0083
0084 AUTHOR
0085 ------
0086 [verse]
0087 --
0088 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
0089 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
0090 --
0091 REPORTING BUGS
0092 --------------
0093 Report bugs to <linux-trace-devel@vger.kernel.org>
0094
0095 LICENSE
0096 -------
0097 libtraceevent is Free Software licensed under the GNU LGPL 2.1
0098
0099 RESOURCES
0100 ---------
0101 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
