'\" t .\" Title: libtracefs .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 07/25/2024 .\" Manual: libtracefs Manual .\" Source: libtracefs 1.8.1 .\" Language: English .\" .TH "LIBTRACEFS" "3" "07/25/2024" "libtracefs 1\&.8\&.1" "libtracefs Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" tracefs_snapshot_snap, tracefs_snapshot_clear, tracefs_snapshot_free \- API to create, clear and read snapshots .SH "SYNOPSIS" .sp .nf \fB#include \fR int \fBtracefs_snapshot_snap\fR(struct tracefs_instance *instance); int \fBtracefs_snapshot_clear\fR(struct tracefs_instance *instance); int \fBtracefs_snapshot_free\fR(struct tracefs_instance *instance); .fi .SH "DESCRIPTION" .sp The Linux kernel tracing provides a "snapshot" feature\&. The kernel has two ring buffers\&. One that is written to by the tracing system and another one that is the "snapshot" buffer\&. When a snapshot happens, the two buffers are swapped, and the current snapshot buffer becomes the one being written to, and the buffer that was being written to becomes the saved snapshot\&. .sp Note, the snapshot buffer is allocated the first time it is taken, so it is best to take a snapshot at the start before one is needed so that it is allocated and a snapshot is ready, then the snapshot will happen immediately\&. .sp The \fBtracefs_snapshot_snap()\fR will allocate (if not already allocated) the snapshot buffer and then take a "snapshot" (swap the main buffer that\(cqs being written to with the allocated snapshot buffer)\&. It will do this to the given \fIinstance\fR buffer or the top instance if \fIinstance\fR is NULL\&. .sp The \fBtracefs_snapshot_clear()\fR will erase the content of the snapshot buffer for the given \fIinstance\fR or the top level instance if \fIinstance\fR is NULL\&. .sp The \fBtracefs_snapshot_free()\fR will free the allocated snapshot for the given \fIinstance\fR or the top level instance if \fIinstance\fR is NULL\&. That is, if another call to \fBtracefs_snapshot_snap()\fR is done after this, then it will need to allocate the snapshot buffer again before it can take a snapshot\&. This function should be used to free up the kernel memory used by hte snapshot buffer when no longer in use\&. .SH "RETURN VALUE" .sp The \fBtracefs_snapshot_snap()\fR, \fBtracefs_snapshot_clear()\fR and the \fBtracefs_snapshot_free()\fR all return 0 on success and \-1 on failure\&. .SH "EXAMPLE" .sp .if n \{\ .RS 4 .\} .nf #include #include #include static int callback(struct tep_event *event, struct tep_record *record, int cpu, void *data) { static struct trace_seq seq; struct tep_handle *tep = event\->tep; if (!seq\&.buffer) trace_seq_init(&seq); trace_seq_reset(&seq); tep_print_event(tep, &seq, record, "[%03d] %s\-%d %6\&.1000d\et%s: %s\en", TEP_PRINT_CPU, TEP_PRINT_COMM, TEP_PRINT_PID, TEP_PRINT_TIME, TEP_PRINT_NAME, TEP_PRINT_INFO); trace_seq_do_printf(&seq); return 0; } int main (int argc, char **argv) { struct tracefs_instance *instance; struct tep_handle *tep; char *line = NULL; size_t len = 0; int ret; instance = tracefs_instance_create("my_snapshots"); if (!instance) { perror("creating instance"); exit(\-1); } tep = tracefs_local_events(NULL); if (!tep) { perror("reading event formats"); goto out; } /* Make sure the snapshot buffer is allocated */ ret = tracefs_snapshot_snap(instance); if (ret < 0) goto out; ret = tracefs_event_enable(instance, "sched", NULL); if (ret < 0) { perror("enabling event"); goto out; } for (;;) { printf("Hit enter without text to take snapshot!\en"); printf("Enter any text to display the snapshot\en"); printf("Enter \*(Aqquit\*(Aq to exit\en"); getline(&line, &len, stdin); ret = tracefs_snapshot_snap(instance); if (ret < 0) { perror("taking snapshot"); goto out; } if (!line) break; if (strlen(line) < 2) continue; if (strncmp(line, "quit", 4) == 0) break; tracefs_iterate_snapshot_events(tep, instance, NULL, 0, callback, NULL); } free(line); tracefs_instance_clear(instance); out: tracefs_snapshot_free(instance); tracefs_event_disable(instance, "sched", NULL); tracefs_instance_destroy(instance); tracefs_instance_free(instance); exit(0); } .fi .if n \{\ .RE .\} .SH "FILES" .sp .if n \{\ .RS 4 .\} .nf \fBtracefs\&.h\fR Header file to include in order to have access to the library APIs\&. \fB\-ltracefs\fR Linker switch to add when building a program that uses the library\&. .fi .if n \{\ .RE .\} .SH "SEE ALSO" .sp \fBtracefs_iterate_snapshot_events\fR(3) \fBlibtracefs\fR(3), \fBlibtraceevent\fR(3), \fBtrace\-cmd\fR(1) .SH "AUTHOR" .sp .if n \{\ .RS 4 .\} .nf \fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2> .fi .if n \{\ .RE .\} .SH "REPORTING BUGS" .sp Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[2]\d\s+2> .SH "LICENSE" .sp libtracefs is Free Software licensed under the GNU LGPL 2\&.1 .SH "RESOURCES" .sp \m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtracefs\&.git/\fR\m[] .SH "COPYING" .sp Copyright (C) 2023 Google, LLC\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&. .SH "NOTES" .IP " 1." 4 rostedt@goodmis.org .RS 4 \%mailto:rostedt@goodmis.org .RE .IP " 2." 4 linux-trace-devel@vger.kernel.org .RS 4 \%mailto:linux-trace-devel@vger.kernel.org .RE