HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |EXAMPLE |FILES |SEE ALSO |AUTHOR |REPORTING BUGS |LICENSE |RESOURCES |COPYING |NOTES |COLOPHON | |
LIBTRACEFS(3) libtracefs ManualLIBTRACEFS(3)tracefs_instance_file_open, tracefs_instance_file_write, tracefs_instance_file_write_number, tracefs_instance_file_append, tracefs_instance_file_clear, tracefs_instance_file_read, tracefs_instance_file_read_number - Work with files in tracing instances.
#include <tracefs.h> inttracefs_instance_file_open(struct tracefs_instance *instance, const char *file, intmode); inttracefs_instance_file_write(struct tracefs_instance *instance, const char *file, const char *str); inttracefs_instance_file_write_number(struct tracefs_instance *instance, const char *file, size_tval); inttracefs_instance_file_append(struct tracefs_instance *instance, const char *file, const char *str); inttracefs_instance_file_clear(struct tracefs_instance *instance, const char *file); char *tracefs_instance_file_read(struct tracefs_instance *instance, const char *file, int *psize); inttracefs_instance_file_read_number(struct tracefs_instance *instance, const char *file, long long int *res);
This set of APIs can be used to work with trace files in all trace instances. Each of these APIs take aninstance argument, that can be NULL to act on the top level instance. Otherwise, it acts on an instance created withtracefs_insance_create(3) Thetracefs_instance_file_open()function opens tracefile from giveninstance and returns a file descriptor to it. The file accessmode can be specified, seeopen(3) for more details. If -1 is passed asmode, default O_RDWR is used. Thetracefs_instance_file_write()function writes a stringstr in afile from the giveninstance, without the terminating NULL character. When opening the file, this function tries to truncates the size of the file to zero, which clears all previously existing settings. Thetracefs_instance_file_write_number()function convertsval into a string and then writes it to the given file. This is a helper function that does the number conversion to string and then callstracefs_instance_file_write(). Thetracefs_instance_file_append()function writes a stringstr in afile from the giveninstance, without the terminating NULL character. This function is similar totracefs_instance_file_write(), but the existing content of the is not cleared. Thus the new settings are appended to the existing ones (if any). Thetracefs_instance_file_clear()function tries to truncates the size of the file to zero, which clears all previously existing settings. If the file has content that does not get cleared in this way, this will not have any effect. Thetracefs_instance_file_read()function reads the content of afile from the giveninstance. Thetracefs_instance_file_read_number()function reads the content of afile from the giveninstance and converts it to a long long integer, which is stored inres.
Thetracefs_instance_file_open()function returns a file descriptor to the opened file. It must be closed withclose(3). In case of an error, -1 is returned. Thetracefs_instance_file_write()function returns the number of written bytes, or -1 in case of an error. Thetracefs_instance_file_write_number()function returns 0 on success and -1 on error. Thetracefs_instance_file_append()function returns the number of written bytes, or -1 in case of an error. Thetracefs_instance_file_clear()function returns 0 on success, or -1 in case of an error. Thetracefs_instance_file_read()function returns a pointer to a NULL terminated string, read from the file, or NULL in case of an error. The returned string must be freed with free(). Thetracefs_instance_file_read_number()function returns 0 if a valid integer is read from the file and stored inres or -1 in case of an error.
#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); }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.
libtracefs(3),libtraceevent(3),trace-cmd(1)
Steven Rostedt<rostedt@goodmis.org[1]>Tzvetomir Stoyanov<tz.stoyanov@gmail.com[2]>
Report bugs to <linux-trace-devel@vger.kernel.org[3]>
libtracefs is Free Software licensed under the GNU LGPL 2.1
https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Copyright (C) 2020 VMware, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).
1. rostedt@goodmis.org mailto:rostedt@goodmis.org 2. tz.stoyanov@gmail.com mailto:tz.stoyanov@gmail.com 3. linux-trace-devel@vger.kernel.org mailto:linux-trace-devel@vger.kernel.org
This page is part of thelibtracefs (Linux kernel trace file system library) project. Information about the project can be found at ⟨https://www.trace-cmd.org/⟩. If you have a bug report for this manual page, see ⟨https://www.trace-cmd.org/⟩. This page was obtained from the project's upstream Git repository ⟨https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-06-02.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orglibtracefs 1.8.1 01/02/2025LIBTRACEFS(3)Pages that refer to this page:tracefs_event_get_file(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |