libtraceevent(3)
================

NAME
----
tep_load_btf, tep_btf_print_args -
Load BTF file and use it to pretty print function arguments.

SYNOPSIS
--------
[verse]
--
*#include <event-parse.h>*

int *tep_load_btf*(struct tep_handle pass:[*]_tep_, void pass:[*]_raw_data_, size_t _data_size_);
int *tep_btf_print_args*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, void pass:[*]_args_,
		       int _nmem_, int _size_, const char pass:[*]_func_);
--

DESCRIPTION
-----------
If the Linux kernel has BTF configured, then a binary file will exist
in the path of */sys/kernel/btf/vmlinux*. If this file is read into memory
and passed to *tep_load_btf()* function, then it will be used to parse
the arguments of a given function, if that function data is found within
the BTF file.

The *tep_load_btf()* takes the _tep_ handle and will load the _raw_data_
into it.  The _data_size_ should be set to the size of the content in _raw_data_.

The *tep_btf_print_args()* takes a _tep_ handle, a trace_seq _s_ pointer
(that was initialized by *trace_seq_init(3)*), an _args_ array that holds either
4 byte or 8 byte values, the _nmem_ that is the number of values in the _args_
parameter, a _size_ that is either 4 or 8 to denote the size of each value in _args_,
and a _func_ string that is the name of the function to find the BTF information
to use for parsing. If BTF is not loaded or the _func_ name is not found it
will just print a hex value of all the _args_ into the _s_ descriptor.

RETURN VALUE
------------
*tep_load_btf()* function returns 0 on success.  It returns -1 on failure and
the _raw_data_ will need to be freed by the caller.

*tep_btf_print_args()* returns 0 on success and -1 on failure, which happens
if the _size_ is not valid or the BTF file that was loaded is corrupted.

EXAMPLE
-------
[source,c]
--
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/mman.h>
#include <event-parse.h>

int print_args(const char *func, unsigned long *args, int nr)
{
	struct tep_handle *tep = tep_alloc();
	struct trace_seq s;
	struct stat st;
	void *buf;
	int fd;
	int ret;

	if (!tep)
		return -1;

	fd = open("/sys/kernel/btf/vmlinux", O_RDONLY);
	if (fd < 0)
		return -1;

	if (fstat(fd, &st) < 0) {
		close(fd);
		return -1;
	}

	buf = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
	if (buf == MAP_FAILED) {
		close(fd);
		return -1;
	}

	ret = tep_load_btf(tep, buf, st.st_size);
	munmap(buf, st.st_size);
	close(fd);

	if (ret < 0)
		return -1;

	trace_seq_init(&s);
	trace_seq_printf(&s, "%s(", func);

	tep_btf_print_args(tep, &s, args, nr, sizeof(long), func);

	trace_seq_puts(&s, ")\n");
	trace_seq_do_printf(&s);

	tep_free(tep);
	return 0;
}

int main(int argc, char **argv)
{
	unsigned long args[] = {0x7ffe7d33f3d0, 0, 0, 0, 0, 0};

	print_args("getname_flags", args, 6);
	return 0;
}
...
The above may output:

  getname_flags(filename=0x7ffe7d33f3d0, flags=0)

If BTF is loaded and the function was found, or it may show:

  getname_flags(7ffe7d33f3d0, 0, 0, 0, 0, 0)

If it was not.
...
--
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)

AUTHOR
------
[verse]
--
*Steven Rostedt* <rostedt@goodmis.org>, author 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/
