'\" t
.\"     Title: libtracefs
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      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_hist_start, tracefs_hist_destroy, tracefs_hist_pause, tracefs_hist_continue, tracefs_hist_reset \- Pause, continue, or clear an existing histogram
.SH "SYNOPSIS"
.sp
.nf
\fB#include <tracefs\&.h>\fR

int \fBtracefs_hist_start\fR(struct tracefs_instance *\fIinstance\fR, struct tracefs_hist *\fIhist\fR);
int \fBtracefs_hist_destroy\fR(struct tracefs_instance *\fIinstance\fR, struct tracefs_hist *\fIhist\fR);
int \fBtracefs_hist_pause\fR(struct tracefs_instance *\fIinstance\fR, struct tracefs_hist *\fIhist\fR);
int \fBtracefs_hist_continue\fR(struct tracefs_instance *\fIinstance\fR, struct tracefs_hist *\fIhist\fR);
int \fBtracefs_hist_reset\fR(struct tracefs_instance *\fIinstance\fR, struct tracefs_hist *\fIhist\fR);
.fi
.SH "DESCRIPTION"
.sp
\fBtracefs_hist_start()\fR is called to actually start the histogram \fIhist\fR\&. The \fIinstance\fR is the instance to start the histogram in, NULL if it should start at the top level\&.
.sp
\fBtracefs_hist_pause()\fR is called to pause the histogram \fIhist\fR\&. The \fIinstance\fR is the instance to pause the histogram in, NULL if it is in the top level\&.
.sp
\fBtracefs_hist_continue()\fR is called to continue a paused histogram \fIhist\fR\&. The \fIinstance\fR is the instance to continue the histogram, NULL if it is in the top level\&.
.sp
\fBtracefs_hist_reset()\fR is called to clear / reset the histogram \fIhist\fR\&. The \fIinstance\fR is the instance to clear the histogram, NULL if it is in the top level\&.
.sp
\fBtracefs_hist_destroy()\fR is called to delete the histogram where it will no longer exist\&. The \fIinstance\fR is the instance to delete the histogram from, NULL if it is in the top level\&.
.SH "RETURN VALUE"
.sp
All the return zero on success or \-1 on error\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include <stdlib\&.h>
#include <tracefs\&.h>

enum commands {
        START,
        PAUSE,
        CONT,
        RESET,
        DELETE,
        SHOW,
};

int main (int argc, char **argv, char **env)
{
        struct tracefs_instance *instance;
        struct tracefs_hist *hist;
        struct tep_handle *tep;
        enum commands cmd;
        char *cmd_str;
        int ret;

        if (argc < 2) {
                fprintf(stderr, "usage: %s command\en", argv[0]);
                exit(\-1);
        }

        cmd_str = argv[1];

        if (!strcmp(cmd_str, "start"))
                cmd = START;
        else if (!strcmp(cmd_str, "pause"))
                cmd = PAUSE;
        else if (!strcmp(cmd_str, "cont"))
                cmd = CONT;
        else if (!strcmp(cmd_str, "reset"))
                cmd = RESET;
        else if (!strcmp(cmd_str, "delete"))
                cmd = DELETE;
        else if (!strcmp(cmd_str, "show"))
                cmd = SHOW;
        else {
                fprintf(stderr, "Unknown command %s\en", cmd_str);
                exit(\-1);
        }

        tep = tracefs_local_events(NULL);
        if (!tep) {
                perror("Reading tracefs");
                exit(\-1);
        }

        instance = tracefs_instance_create("hist_test");
        if (!instance) {
                fprintf(stderr, "Failed instance create\en");
                exit(\-1);
        }

        hist = tracefs_hist_alloc_2d(tep, "kmem", "kmalloc",
                                     "call_site",TRACEFS_HIST_KEY_SYM,
                                     "bytes_req", 0);
        if (!hist) {
                fprintf(stderr, "Failed hist create\en");
                exit(\-1);
        }

        ret = tracefs_hist_add_value(hist, "bytes_alloc");
        ret |= tracefs_hist_add_sort_key(hist, "bytes_req");
        ret |= tracefs_hist_add_sort_key(hist, "bytes_alloc");

        ret |= tracefs_hist_sort_key_direction(hist, "bytes_alloc",
                                               TRACEFS_HIST_SORT_DESCENDING);
        if (ret) {
                fprintf(stderr, "Failed modifying histogram\en");
                exit(\-1);
        }

        tracefs_error_clear(instance);

        switch (cmd) {
        case START:
                ret = tracefs_hist_start(instance, hist);
                if (ret) {
                        char *err = tracefs_error_last(instance);
                        if (err)
                                fprintf(stderr, "\en%s\en", err);
                }
                break;
        case PAUSE:
                ret = tracefs_hist_pause(instance, hist);
                break;
        case CONT:
                ret = tracefs_hist_continue(instance, hist);
                break;
        case RESET:
                ret = tracefs_hist_reset(instance, hist);
                break;
        case DELETE:
                ret = tracefs_hist_destroy(instance, hist);
                break;
        case SHOW: {
                char *content;
                content = tracefs_event_file_read(instance, "kmem", "kmalloc",
                                                  "hist", NULL);
                ret = content ? 0 : \-1;
                if (content) {
                        printf("%s\en", content);
                        free(content);
                }
                break;
        }
        }
        if (ret)
                fprintf(stderr, "Failed: command\en");
        exit(ret);
}
.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
\fBlibtracefs\fR(3), \fBlibtraceevent\fR(3), \fBtrace\-cmd\fR(1), \fBtracefs_hist_alloc\fR(3), \fBtracefs_hist_alloc_2d\fR(3), \fBtracefs_hist_alloc_nd\fR(3), \fBtracefs_hist_free\fR(3), \fBtracefs_hist_add_key\fR(3), \fBtracefs_hist_add_value\fR(3), \fBtracefs_hist_add_name\fR(3), \fBtracefs_hist_start\fR(3), \fBtracefs_hist_destory\fR(3), \fBtracefs_hist_add_sort_key\fR(3), \fBtracefs_hist_sort_key_direction\fR(3)
.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>
\fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2>
\fBsameeruddin shaik\fR <\m[blue]\fBsameeruddin\&.shaik8@gmail\&.com\fR\m[]\&\s-2\u[3]\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[4]\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) 2020 VMware, Inc\&. 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
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE
.IP " 3." 4
sameeruddin.shaik8@gmail.com
.RS 4
\%mailto:sameeruddin.shaik8@gmail.com
.RE
.IP " 4." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE