151 lines
5.0 KiB
Plaintext
151 lines
5.0 KiB
Plaintext
libtracefs(3)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_alloc, tracefs_instance_free,
|
|
tracefs_instance_is_new, tracefs_instances - Manage trace instances.
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
--
|
|
*#include <tracefs.h>*
|
|
|
|
struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_);
|
|
int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_);
|
|
struct tracefs_instance pass:[*]*tracefs_instance_alloc*(const char pass:[*]_tracing_dir_, const char pass:[*]_name_);
|
|
void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_);
|
|
bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_);
|
|
char pass:[**]*tracefs_instances*(const char pass:[*]_regex_);
|
|
|
|
--
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
This set of functions can be used to manage trace instances. A trace
|
|
instance is a sub buffer used by the Linux tracing system. Given a unique
|
|
name, the events enabled in an instance do not affect the main tracing
|
|
system, nor other instances, as events enabled in the main tracing system
|
|
or other instances do not affect the given instance.
|
|
|
|
The *tracefs_instance_create()* function allocates and initializes a new
|
|
tracefs_instance structure and returns it. If the instance with _name_ does
|
|
not yet exist in the system, it will be created. The _name_ could be NULL,
|
|
then the new tracefs_instance structure is initialized for the top instance.
|
|
Note that the top instance cannot be created in the system, if it does not
|
|
exist.
|
|
|
|
The *tracefs_instance_destroy()* removes the instance from the system, but
|
|
does not free the structure. *tracefs_instance_free()* must still be called
|
|
on _instance_.
|
|
|
|
The tracefs_instance_alloc()* function allocates a new tracefs_instance structure
|
|
for existing trace instance. If the instance does not exist in the system, the function
|
|
fails. The _tracing_dir_ parameter points to the system trace directory. It can be
|
|
NULL, then default system trace directory is used. This parameter is useful to allocate
|
|
instances to trace directories, copied from another machine. The _name_ is the name of
|
|
the instance, or NULL for the top instance in the given _tracing_dir_.
|
|
|
|
The *tracefs_instance_free()* function frees the tracefs_instance structure,
|
|
without removing the trace instance from the system.
|
|
|
|
The *tracefs_instance_is_new()* function checks if the given _instance_ is
|
|
newly created by *tracefs_instance_create()*, or it has been in the system
|
|
before that.
|
|
|
|
The *tracefs_instances*() function returns a list of instances that exist in
|
|
the system that match the regular expression _regex_. If _regex_ is NULL, then
|
|
it will match all instances that exist. The returned list must be freed with
|
|
*tracefs_list_free*(3). Note, if no instances are found an empty list is returned
|
|
and that too needs to be free with *tracefs_list_free*(3).
|
|
|
|
RETURN VALUE
|
|
------------
|
|
The *tracefs_instance_create()* and *tracefs_instance_alloc()* functions return a pointer to
|
|
a newly allocated tracefs_instance structure. It must be freed with *tracefs_instance_free()*.
|
|
|
|
The *tracefs_instance_destroy()* function returns 0 if it succeeds to remove
|
|
the instance, otherwise it returns -1 if the instance does not exist or it
|
|
fails to remove it.
|
|
|
|
The *tracefs_instance_is_new()* function returns true if the
|
|
*tracefs_instance_create()* that allocated _instance_ also created the
|
|
trace instance in the system, or false if the trace instance already
|
|
existed in the system when _instance_ was allocated by
|
|
*tracefs_instance_create()* or *tracefs_instance_alloc()*.
|
|
|
|
The *tracefs_instances()* returns a list of instance names that exist on the system.
|
|
The list must be freed with *tracefs_list_free*(3). An empty list is returned if
|
|
no instance exists that matches _regex_, and this needs to be freed with
|
|
*tracefs_list_free*(3) as well. NULL is returned on error.
|
|
|
|
EXAMPLE
|
|
-------
|
|
[source,c]
|
|
--
|
|
#include <tracefs.h>
|
|
|
|
struct tracefs_instance *inst = tracefs_instance_create("foo");
|
|
if (!inst) {
|
|
/* Error creating a new trace instance */
|
|
...
|
|
}
|
|
|
|
...
|
|
|
|
if (tracefs_instance_is_new(inst))
|
|
tracefs_instance_destroy(inst);
|
|
tracefs_instance_free(inst);
|
|
...
|
|
|
|
struct tracefs_instance *inst = tracefs_instance_alloc(NULL, "bar");
|
|
if (!inst) {
|
|
/* Error allocating 'bar' trace instance */
|
|
...
|
|
}
|
|
|
|
...
|
|
|
|
tracefs_instance_free(inst);
|
|
--
|
|
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* <rostedt@goodmis.org>
|
|
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
|
|
--
|
|
REPORTING BUGS
|
|
--------------
|
|
Report bugs to <linux-trace-devel@vger.kernel.org>
|
|
|
|
LICENSE
|
|
-------
|
|
libtracefs is Free Software licensed under the GNU LGPL 2.1
|
|
|
|
RESOURCES
|
|
---------
|
|
https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
|
|
|
|
COPYING
|
|
-------
|
|
Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
|
|
the terms of the GNU Public License (GPL).
|