Documentation/libtracefs-instances-files.txt

libtracefs(3)
=============

NAME
----
tracefs_file_exists, tracefs_dir_exists,
tracefs_instance_get_file, tracefs_instance_get_dir - Work with files directories in tracing instances.

SYNOPSIS
--------
[verse]
--
*#include <tracefs.h>*

bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_);
char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_);

--

DESCRIPTION
-----------
This set of APIs can be used to work with trace files in all trace instances.
Each of these APIs take an _instance_ argument, that can be NULL to act
on the top level instance. Otherwise, it acts on an instance created with
*tracefs_insance_create*(3)

The *tracefs_file_exists()* function checks if a file with _name_ exists in _instance_.

The *tracefs_dir_exists()* function checks if a directory with _name_ exists in _instance_.

The *tracefs_instance_get_file()* function returns the full path of the file
with given _name_ in _instance_. Note, it does not check if the file exists in
the instance.

The *tracefs_instance_get_dir()* function  returns the full path of the directory
with given _name_ in _instance_. Note, it does not check if the directory exists
in the instance.

RETURN VALUE
------------
The *tracefs_file_exists()* and *tracefs_dir_exists()* functions return true if the
file / directory exist in the given instance or false if it does not exist.

The *tracefs_instance_get_file()* and *tracefs_instance_get_dir()* functions return
a string or NULL in case of an error. The returned string must be freed with
*tracefs_put_tracing_file()*.

EXAMPLE
-------
[source,c]
--
#include <tracefs.h>

struct tracefs_instance *inst = tracefs_instance_create("foo");
	if (!inst) {
		/* Error creating a new trace instance */
		...
	}

	if (tracefs_file_exists(inst,"trace_clock")) {
		/* The instance foo supports trace clock */
		char *path, *clock;
		int size;

		path =  = tracefs_instance_get_file(inst, "trace_clock")
		if (!path) {
			/* Error getting the path to trace_clock file in instance foo */
			...
		}
		...
		tracefs_put_tracing_file(path);

		clock = tracefs_instance_file_read(inst, "trace_clock", &size);
		if (!clock) {
			/* Failed to read trace_clock file in instance foo */
			...
		}
		...
		free(clock);

		if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) {
			/* Failed to set gloabl trace clock in instance foo */
			...
		}
	} else {
		/* The instance foo does not support trace clock */
	}

	if (tracefs_dir_exists(inst,"options")) {
		/* The instance foo supports trace options */
		char *path = tracefs_instance_get_file(inst, "options");
		if (!path) {
			/* Error getting the path to options directory in instance foo */
			...
		}

		tracefs_put_tracing_file(path);
	} else {
		/* The instance foo does not support trace options */
	}

	...

	if (tracefs_instance_is_new(inst))
		tracefs_instance_destroy(inst);
	else
		tracefs_instance_free(inst);
	...

	long long int res;
	if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) {
		if (res == 0) {
			/* tracing is disabled in the top instance */
		} else if (res == 1) {
			/* tracing is enabled in the top instance */
		} else {
			/* Unknown tracing state of the top instance */
		}
	} else {
		/* Failed to read integer from tracing_on file */
	}

	...

	int fd;
	fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
	if (fd >= 0) {
		/* Got file descriptor to the tracing_on file from the top instance for writing */
		...
		close(fd);
	}
--
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).