diff options
Diffstat (limited to 'Documentation/libtraceevent-parse-files.txt')
| -rw-r--r-- | Documentation/libtraceevent-parse-files.txt | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/Documentation/libtraceevent-parse-files.txt b/Documentation/libtraceevent-parse-files.txt new file mode 100644 index 0000000..bb2facb --- /dev/null +++ b/Documentation/libtraceevent-parse-files.txt @@ -0,0 +1,149 @@ +libtraceevent(3) +================ + +NAME +---- +tep_parse_saved_cmdlines, tep_parse_printk_formats, tep_parse_kallsyms +- Parsing functions to load mappings + +SYNOPSIS +-------- +[verse] +-- +*#include <event-parse.h>* + +int *tep_parse_saved_cmdlines*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_); +int *tep_parse_printk_formats*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_); +int *tep_parse_kallsyms*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_); +-- + +DESCRIPTION +----------- +*tep_parse_saved_cmdlines()* is a helper function to parse content in the tracefs +file system of the "saved_cmdlines" file (stored in a string buffer passed in by _buf_) +and loads the mapping of the process IDs (pid) to the comm names in the +_tep_ handler. The events store the pid and this is used to be able to show the +process names associated to those process ids. It parses the string _buf_ that +holds the content of saved_cmdlines and ends with a nul character ('\0'). + +*tep_parse_printk_formats()* is a helper function to parse content in the tracefs +file system of the "printk_formats" file (stored in a string buffer passed in by _buf_) +and loads the mapping of addresses of strings that may be referenced by events. +Events only store the address of constant strings in the kernel, and the mapping +of their address to the string is exported to user space in the printk_formats +file. It parses the string _buf_ that holds the content of printk_formats and +ends with a nul character ('\0'). + +*tep_parse_kallsyms()* is a helper function to parse the Linux kernel /proc/kallsyms format +(stored in a string buffer passed in by _buf_) and load the functions into the +_tep_ handler such that function IP addresses can be mapped to their name when +parsing events with %pS in the print format field. It parses the string _buf_ that +holds the content of /proc/kallsyms and ends with a nul character ('\0'). + +RETURN VALUE +------------ +The *tep_parse_saved_cmdlines*() function returns 0 in case of success, or -1 +in case of an error. + +The *tep_parse_printk_formats*() function returns 0 in case of success, or -1 +in case of an error. + +The *tep_parse_kallsyms*() function returns 0 in case of success, or -1 +in case of an error. + +EXAMPLE +------- +[source,c] +-- +... +#include <event-parse.h> +#include <tracefs.h> +#include <stdlib.h> + +int load_cmdlines(struct tep_handle *tep) +{ + char *buf = NULL; + int r; + + buf = tracefs_instance_file_read(NULL, "saved_cmdlines", NULL); + if (!buf) + return -1; + r = tep_parse_saved_cmdlines(tep, buf); + free(buf); + return r; +} + +int load_print_strings(struct tep_handle *tep) +{ + char *buf = NULL; + int r; + + buf = tracefs_instance_file_read(NULL, "printk_formats", NULL); + if (!buf) + return -1; + r = tep_parse_printk_formats(tep, buf); + free(buf); + return r; +} + +int load_kallsyms(struct tep_handle *tep) +{ + char *line = NULL; + char *buf = NULL; + size_t sz = 0; + FILE *fp; + int len = 0; + int r; + + fp = fopen("/proc/kallsyms", "r"); + while ((r = getline(&line, &sz, fp)) >= 0) { + buf = realloc(buf, len + r + 1); + memcpy(buf + len, line, r); + len += r; + } + free(line); + fclose(fp); + if (!buf) + return -1; + buf[len] = 0; + + r = tep_parse_kallsyms(tep, buf); + free(buf); + return r; +} +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +*libtraceevent*(3), *trace-cmd*(1), *tep_register_comm*(3), *tep_register_function*(3), +*tep_register_print_string*(3) + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, coauthor of *libtraceevent*. +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtraceevent is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ |