tracefs_instance_file_open(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | FILES | SEE ALSO | AUTHOR | REPORTING BUGS | LICENSE | RESOURCES | COPYING | NOTES | COLOPHON

LIBTRACEFS(3)               libtracefs Manual              LIBTRACEFS(3)

NAME         top

       tracefs_instance_file_open, tracefs_instance_file_write,
       tracefs_instance_file_append, tracefs_instance_file_clear,
       tracefs_instance_file_read, tracefs_instance_file_read_number -
       Work with files in tracing instances.

SYNOPSIS         top

       #include <tracefs.h>

       int tracefs_instance_file_open(struct tracefs_instance *instance, const char *file, int mode);
       int tracefs_instance_file_write(struct tracefs_instance *instance, const char *file, const char *str);
       int tracefs_instance_file_append(struct tracefs_instance *instance, const char *file, const char *str);
       int tracefs_instance_file_clear(struct tracefs_instance *instance, const char *file);
       char *tracefs_instance_file_read(struct tracefs_instance *instance, const char *file, int *psize);
       int tracefs_instance_file_read_number(struct tracefs_instance *instance, const char *file, long long int *res);

DESCRIPTION         top

       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_instance_file_open() function opens trace file from
       given instance and returns a file descriptor to it. The file
       access mode can be specified, see open(3) for more details. If -1
       is passed as mode, default O_RDWR is used.

       The tracefs_instance_file_write() function writes a string str in
       a file from the given instance, 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.

       The tracefs_instance_file_append() function writes a string str
       in a file from the given instance, without the terminating NULL
       character. This function is similar to
       tracefs_instance_file_write(), but the existing content of the is
       not cleared. Thus the new settings are appended to the existing
       ones (if any).

       The tracefs_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.

       The tracefs_instance_file_read() function reads the content of a
       file from the given instance.

       The tracefs_instance_file_read_number() function reads the
       content of a file from the given instance and converts it to a
       long long integer, which is stored in res.

RETURN VALUE         top

       The tracefs_instance_file_open() function returns a file
       descriptor to the opened file. It must be closed with close(3).
       In case of an error, -1 is returned.

       The tracefs_instance_file_write() function returns the number of
       written bytes, or -1 in case of an error.

       The tracefs_instance_file_append() function returns the number of
       written bytes, or -1 in case of an error.

       The tracefs_instance_file_clear() function returns 0 on success,
       or -1 in case of an error.

       The tracefs_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().

       The tracefs_instance_file_read_number() function returns 0 if a
       valid integer is read from the file and stored in res or -1 in
       case of an error.

EXAMPLE         top

           #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         top

           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         top

       libtracefs(3), libtraceevent(3), trace-cmd(1)

AUTHOR         top

           Steven Rostedt <rostedt@goodmis.org[1]>
           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>

REPORTING BUGS         top

       Report bugs to <linux-trace-devel@vger.kernel.org[3]>

LICENSE         top

       libtracefs is Free Software licensed under the GNU LGPL 2.1

RESOURCES         top

       https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 

COPYING         top

       Copyright (C) 2020 VMware, Inc. Free use of this software is
       granted under the terms of the GNU Public License (GPL).

NOTES         top

        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

COLOPHON         top

       This page is part of the libtracefs (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
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-05-17.)  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 is not part of the original
       manual page), send a mail to man-pages@man7.org

libtracefs 1.7.0               12/22/2023                  LIBTRACEFS(3)

Pages that refer to this page: tracefs_event_get_file(3)