1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_snapshot_snap, tracefs_snapshot_clear, tracefs_snapshot_free - 7API to create, clear and read snapshots 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <tracefs.h>* 14 15int *tracefs_snapshot_snap*(struct tracefs_instance pass:[*]instance); 16int *tracefs_snapshot_clear*(struct tracefs_instance pass:[*]instance); 17int *tracefs_snapshot_free*(struct tracefs_instance pass:[*]instance); 18-- 19 20DESCRIPTION 21----------- 22The Linux kernel tracing provides a "snapshot" feature. The kernel has two 23ring buffers. One that is written to by the tracing system and another one that 24is the "snapshot" buffer. When a snapshot happens, the two buffers are swapped, and 25the current snapshot buffer becomes the one being written to, and the buffer 26that was being written to becomes the saved snapshot. 27 28Note, the snapshot buffer is allocated the first time it is taken, so it is best 29to take a snapshot at the start before one is needed so that it is allocated 30and a snapshot is ready, then the snapshot will happen immediately. 31 32The *tracefs_snapshot_snap()* will allocate (if not already allocated) the snapshot 33buffer and then take a "snapshot" (swap the main buffer that's being written to with 34the allocated snapshot buffer). It will do this to the given _instance_ buffer or 35the top instance if _instance_ is NULL. 36 37The *tracefs_snapshot_clear()* will erase the content of the snapshot buffer for 38the given _instance_ or the top level instance if _instance_ is NULL. 39 40The *tracefs_snapshot_free()* will free the allocated snapshot for the given _instance_ 41or the top level instance if _instance_ is NULL. That is, if another call to 42*tracefs_snapshot_snap()* is done after this, then it will need to allocate 43the snapshot buffer again before it can take a snapshot. This function should 44be used to free up the kernel memory used by hte snapshot buffer when no longer in use. 45 46 47RETURN VALUE 48------------ 49The *tracefs_snapshot_snap()*, *tracefs_snapshot_clear()* and the *tracefs_snapshot_free()* 50all return 0 on success and -1 on failure. 51 52EXAMPLE 53------- 54[source,c] 55-- 56#include <stdlib.h> 57#include <stdio.h> 58#include <tracefs.h> 59 60static int callback(struct tep_event *event, struct tep_record *record, int cpu, void *data) 61{ 62 static struct trace_seq seq; 63 struct tep_handle *tep = event->tep; 64 65 if (!seq.buffer) 66 trace_seq_init(&seq); 67 68 trace_seq_reset(&seq); 69 70 tep_print_event(tep, &seq, record, "[%03d] %s-%d %6.1000d\t%s: %s\n", 71 TEP_PRINT_CPU, 72 TEP_PRINT_COMM, 73 TEP_PRINT_PID, 74 TEP_PRINT_TIME, 75 TEP_PRINT_NAME, 76 TEP_PRINT_INFO); 77 trace_seq_do_printf(&seq); 78 return 0; 79} 80 81int main (int argc, char **argv) 82{ 83 struct tracefs_instance *instance; 84 struct tep_handle *tep; 85 char *line = NULL; 86 size_t len = 0; 87 int ret; 88 89 instance = tracefs_instance_create("my_snapshots"); 90 if (!instance) { 91 perror("creating instance"); 92 exit(-1); 93 } 94 95 tep = tracefs_local_events(NULL); 96 if (!tep) { 97 perror("reading event formats"); 98 goto out; 99 } 100 101 /* Make sure the snapshot buffer is allocated */ 102 ret = tracefs_snapshot_snap(instance); 103 if (ret < 0) 104 goto out; 105 106 ret = tracefs_event_enable(instance, "sched", NULL); 107 if (ret < 0) { 108 perror("enabling event"); 109 goto out; 110 } 111 112 for (;;) { 113 printf("Hit enter without text to take snapshot!\n"); 114 printf("Enter any text to display the snapshot\n"); 115 printf("Enter 'quit' to exit\n"); 116 getline(&line, &len, stdin); 117 ret = tracefs_snapshot_snap(instance); 118 if (ret < 0) { 119 perror("taking snapshot"); 120 goto out; 121 } 122 if (!line) 123 break; 124 if (strlen(line) < 2) 125 continue; 126 if (strncmp(line, "quit", 4) == 0) 127 break; 128 tracefs_iterate_snapshot_events(tep, instance, NULL, 0, callback, NULL); 129 } 130 131 free(line); 132 133 tracefs_instance_clear(instance); 134 135 out: 136 tracefs_snapshot_free(instance); 137 tracefs_event_disable(instance, "sched", NULL); 138 tracefs_instance_destroy(instance); 139 tracefs_instance_free(instance); 140 141 exit(0); 142} 143-- 144FILES 145----- 146[verse] 147-- 148*tracefs.h* 149 Header file to include in order to have access to the library APIs. 150*-ltracefs* 151 Linker switch to add when building a program that uses the library. 152-- 153 154SEE ALSO 155-------- 156*tracefs_iterate_snapshot_events*(3) 157*libtracefs*(3), 158*libtraceevent*(3), 159*trace-cmd*(1) 160 161AUTHOR 162------ 163[verse] 164-- 165*Steven Rostedt* <rostedt@goodmis.org> 166-- 167REPORTING BUGS 168-------------- 169Report bugs to <linux-trace-devel@vger.kernel.org> 170 171LICENSE 172------- 173libtracefs is Free Software licensed under the GNU LGPL 2.1 174 175RESOURCES 176--------- 177https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 178 179COPYING 180------- 181Copyright \(C) 2023 Google, LLC. Free use of this software is granted under 182the terms of the GNU Public License (GPL). 183