1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_tracing_dir, tracefs_debug_dir, tracefs_set_tracing_dir, 7tracefs_tracing_dir_is_mounted - Find and set locations of trace directory and files. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_); 16void *tracefs_put_tracing_file*(char pass:[*]_name_); 17const char pass:[*]*tracefs_tracing_dir*(void); 18const char pass:[*]*tracefs_debug_dir*(void); 19int *tracefs_set_tracing_dir*(char pass:[*]_tracing_dir_) 20int *tracefs_tracing_dir_is_mounted*(bool _mount_, const char pass:[**]_path_); 21-- 22 23DESCRIPTION 24----------- 25This set of APIs can be used to find the full path of the trace file 26system mount point and trace files in it. 27 28The *tracefs_set_tracing_dir()* function sets a custom location of the 29system's tracing directory mount point. Usually, the library auto detects 30it using the information from the /proc/mounts file. Use this API only if the 31mount point is not standard and cannot be detected by the library. The _tracing_dir_ 32argument can be NULL, in that case the custom location is deleted and the library 33auto detection logic is used. 34 35The *tracefs_get_tracing_file()* function returns the full path of the 36file with given _name_ in the trace file system. The function works 37only with files in the tracefs main directory, it is not trace instance 38aware. It is recommended to use *tracefs_instance_get_file()* and 39*tracefs_instance_get_dir()* instead. The returned string must be freed 40with *tracefs_put_tracing_file()*. 41 42The *tracefs_put_tracing_file()* function frees trace file name, 43returned by *tracefs_get_tracing_file()*. 44 45The *tracefs_tracing_dir()* function returns the full path to the 46trace file system. In the first function call, the mount point of the 47tracing file system is located, cached and returned. It will mount it, 48if it is not mounted. On any subsequent call the cached path is returned. 49The return string must _not_ be freed. 50 51The *tracefs_debug_dir()* is similar to *tracefs_tracing_dir()* except 52that it will return where the debugfs file system is mounted. If it 53is not mounted it will try to mount it. The return string must _not_ 54be freed. 55 56*tracefs_tracing_dir_is_mounted()* returns 1 if the tracing directory is 57already mounted and 0 if it is not. If _mount_ is true, it will try to 58mount it if it is not, and returns 0 if it succesfully mounted it and -1 59if it did not. If _path_ is set, it will be assigned to the path where it 60mounted it. _path_ is internal and should not be freed. 61 62RETURN VALUE 63------------ 64The *tracefs_set_tracing_dir()* function returns 0 on success, -1 otherwise. 65 66The *tracefs_get_tracing_file()* function returns a string or NULL in case 67of an error. The returned string must be freed with *tracefs_put_tracing_file()*. 68 69The *tracefs_tracing_dir()* function returns a constant string or NULL 70in case of an error. The returned string must _not_ be freed. 71 72The *tracefs_debug_dir()* function returns a constant string or NULL 73in case of an error. The returned string must _not_ be freed. 74 75The *tracefs_tracing_dir_is_mounted()* returns 1 if the tracing directory 76is already mounted, 0 if it is not, and -1 on error. 77 78EXAMPLE 79------- 80[source,c] 81-- 82#include <tracefs.h> 83... 84char *trace_on = tracefs_get_tracing_file("tracing_on"); 85 if (trace_on) { 86 ... 87 tracefs_put_tracing_file(trace_on); 88 } 89... 90const char *trace_dir = tracefs_tracing_dir(); 91 92-- 93FILES 94----- 95[verse] 96-- 97*tracefs.h* 98 Header file to include in order to have access to the library APIs. 99*-ltracefs* 100 Linker switch to add when building a program that uses the library. 101-- 102 103SEE ALSO 104-------- 105*libtracefs*(3), 106*libtraceevent*(3), 107*trace-cmd*(1) 108 109AUTHOR 110------ 111[verse] 112-- 113*Steven Rostedt* <[email protected]> 114*Tzvetomir Stoyanov* <[email protected]> 115-- 116REPORTING BUGS 117-------------- 118Report bugs to <[email protected]> 119 120LICENSE 121------- 122libtracefs is Free Software licensed under the GNU LGPL 2.1 123 124RESOURCES 125--------- 126https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 127 128COPYING 129------- 130Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 131the terms of the GNU Public License (GPL). 132