libtracefs man pages
v2 cover libtracefs man pages
Initial implementation of libtracefs man pages.
v2 changes:
- Removed tracefs_find_tracing_dir() API
- Renamed tracefs_get_tracing_dir() to tracefs_tracing_dir()
- Removed any references to "#include <event-parse.h>"
- Rewrote some descriptions, as suggested by Steven.
Tzvetomir Stoyanov (VMware) (8):
libtracefs: Initial support for man pages
libtracefs man pages: APIs for locating trace directory and files. libtracefs man pages: APIs for working with trace systems and events. libtracefs man pages: APIs for managing trace instances. libtracefs man pages: APIs for working with files in trace instances. libtracefs man pages: helper APIs for working with trace instances. libtracefs man pages: APIs for initializing a tep handler with trace
events from the local system.
libtracefs man pages: helper APIs for working with trace file system.
Documentation/Makefile | 211 ++++++++++++++++++ Documentation/asciidoc.conf | 120 ++++++++++ Documentation/libtracefs-events-tep.txt | 131 +++++++++++ Documentation/libtracefs-events.txt | 143 ++++++++++++ Documentation/libtracefs-files.txt | 97 ++++++++ Documentation/libtracefs-instances-files.txt | 160 +++++++++++++ Documentation/libtracefs-instances-manage.txt | 111 +++++++++ Documentation/libtracefs-instances-utils.txt | 112 ++++++++++ Documentation/libtracefs-utils.txt | 103 +++++++++ Documentation/libtracefs.txt | 84 +++++++ Documentation/manpage-1.72.xsl | 14 ++ Documentation/manpage-base.xsl | 35 +++ Documentation/manpage-bold-literal.xsl | 17 ++ Documentation/manpage-normal.xsl | 13 ++ Documentation/manpage-suppress-sp.xsl | 21 ++ 15 files changed, 1372 insertions(+) create mode 100644 Documentation/Makefile create mode 100644 Documentation/asciidoc.conf create mode 100644 Documentation/libtracefs-events-tep.txt create mode 100644 Documentation/libtracefs-events.txt create mode 100644 Documentation/libtracefs-files.txt create mode 100644 Documentation/libtracefs-instances-files.txt create mode 100644 Documentation/libtracefs-instances-manage.txt create mode 100644 Documentation/libtracefs-instances-utils.txt create mode 100644 Documentation/libtracefs-utils.txt create mode 100644 Documentation/libtracefs.txt create mode 100644 Documentation/manpage-1.72.xsl create mode 100644 Documentation/manpage-base.xsl create mode 100644 Documentation/manpage-bold-literal.xsl create mode 100644 Documentation/manpage-normal.xsl create mode 100644 Documentation/manpage-suppress-sp.xsl
Signature · 1 line
2.28.0
PATCH v2 1/8 libtracefs: Initial support for man pages
Basic infrastructure for libtracefs man pages and the first man page:
man libtracefs
with list of all library APIs.
--- Documentation/Makefile | 211 +++++++++++++++++++++++++ Documentation/asciidoc.conf | 120 ++++++++++++++ Documentation/libtracefs.txt | 84 ++++++++++ Documentation/manpage-1.72.xsl | 14 ++ Documentation/manpage-base.xsl | 35 ++++ Documentation/manpage-bold-literal.xsl | 17 ++ Documentation/manpage-normal.xsl | 13 ++ Documentation/manpage-suppress-sp.xsl | 21 +++ 8 files changed, 515 insertions(+) create mode 100644 Documentation/Makefile create mode 100644 Documentation/asciidoc.conf create mode 100644 Documentation/libtracefs.txt create mode 100644 Documentation/manpage-1.72.xsl create mode 100644 Documentation/manpage-base.xsl create mode 100644 Documentation/manpage-bold-literal.xsl create mode 100644 Documentation/manpage-normal.xsl create mode 100644 Documentation/manpage-suppress-sp.xsl
Documentation/Makefile new file +211 -0
@@ -0,0 +1,211 @@ +# SPDX-License-Identifier: LGPL-2.1 + +include $(src)/scripts/utils.mk + + +# This Makefile and manpage XSL files were taken from libtraceevent +# and modified for libtracefs. + +MAN3_TXT= \ + $(wildcard libtracefs-*.txt) \ + libtracefs.txt + +MAN_TXT = $(MAN3_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN3=$(patsubst %.txt,%.3,$(MAN3_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/libtracefs-doc +pdfdir?=$(prefix)/share/doc/libtracefs-doc +mandir?=$(prefix)/share/man +man3dir=$(mandir)/man3 + +ASCIIDOC=asciidoc +ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf +ASCIIDOC_HTML = xhtml11 +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_EXTRA = -a compat-mode +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -a mansource="libtracefs" -a manmanual="libtracefs Manual" +ASCIIDOC_HTML = xhtml5 +endif + +XMLTO=xmlto + +_tmp_tool_path := $(call get-executable,$(ASCIIDOC)) +ifeq ($(_tmp_tool_path),) + missing_tools = $(ASCIIDOC) +endif + +ifndef USE_ASCIIDOCTOR +_tmp_tool_path := $(call get-executable,$(XMLTO)) +ifeq ($(_tmp_tool_path),) + missing_tools += $(XMLTO) +endif +endif + +# +# For asciidoc ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# + +ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a libtracefs-asciidoc-no-roff +MANPAGE_XSL = manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a libtracefs-asciidoc-no-roff + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +DESTDIR ?= +DESTDIR_SQ = '$(subst ','\'',$(DESTDIR))' + +export DESTDIR DESTDIR_SQ + +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifneq ($(V),1) + QUIET_ASCIIDOC = @echo ' ASCIIDOC '$@; + QUIET_XMLTO = @echo ' XMLTO '$@; + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) \ + echo ' SUBDIR ' $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + +all: html man + +man: man3 +man3: $(DOC_MAN3) + +html: $(MAN_HTML) + +$(MAN_HTML) $(DOC_MAN3): asciidoc.conf + +install: install-man install-html + +check-man-tools: +ifdef missing_tools + $(error "You need to install $(missing_tools) for man pages") +endif + +do-install-man: man + $(call QUIET_INSTALL, Documentation-man) \ + $(INSTALL) -d -m 755 $(DESTDIR)$(man3dir); \ + $(INSTALL) -m 644 $(OUTPUT)*.3 $(DESTDIR)$(man3dir); + +install-man: check-man-tools man do-install-man + +do-install-html: html + $(call QUIET_INSTALL, Documentation-html) \ + $(INSTALL) -d -m 755 $(DESTDIR)$(htmldir); \ + $(INSTALL) -m 644 $(OUTPUT)*.html $(DESTDIR)$(htmldir); + +install-html: check-man-tools html do-install-html + +uninstall: uninstall-man uninstall-html + +uninstall-man: + $(call QUIET_UNINST, Documentation-man) \ + $(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3)) + +uninstall-html: + $(call QUIET_UNINST, Documentation-html) \ + $(Q)$(RM) $(addprefix $(DESTDIR)$(htmldir)/,$(MAN_HTML)) + +ifdef missing_tools + DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed) +else + DO_INSTALL_MAN = do-install-man +endif + +CLEAN_FILES = \ + $(MAN_XML) $(addsuffix +,$(MAN_XML)) \ + $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \ + $(DOC_MAN3) *.3 + +clean: + $(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES) + +ifdef USE_ASCIIDOCTOR +$(OUTPUT)%.3 : $(OUTPUT)%.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage \ + $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ +endif + +$(OUTPUT)%.3 : $(OUTPUT)%.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +$(OUTPUT)%.xml : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage \ + $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ + +$(MAN_HTML): $(OUTPUT)%.html : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \ + $(ASCIIDOC_EXTRA) -aperf_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@
Documentation/asciidoc.conf new file +120 -0
120 lines not on this page · raw message
Documentation/libtracefs.txt new file +84 -0
85 lines not on this page · raw message
Documentation/manpage-1.72.xsl new file +14 -0
@@ -0,0 +1,14 @@ +<!-- manpage-1.72.xsl: + special settings for manpages rendered from asciidoc+docbook + handles peculiarities in docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the special values for the roff control characters + needed for docbook-xsl 1.72.0 --> +<xsl:param name="git.docbook.backslash">▓</xsl:param> +<xsl:param name="git.docbook.dot" >⌂</xsl:param> + +</xsl:stylesheet>
Documentation/manpage-base.xsl new file +35 -0
@@ -0,0 +1,35 @@ +<!-- manpage-base.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- these params silence some output from xmlto --> +<xsl:param name="man.output.quietly" select="1"/> +<xsl:param name="refentry.meta.get.quietly" select="1"/> + +<!-- convert asciidoc callouts to man page format; + git.docbook.backslash and git.docbook.dot params + must be supplied by another XSL file or other means --> +<xsl:template match="co"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB(', + substring-after(@id,'-'),')', + $git.docbook.backslash,'fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB', + substring-after(@arearefs,'-'), + '. ',$git.docbook.backslash,'fR')"/> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>br </xsl:text> +</xsl:template> + +</xsl:stylesheet>
Documentation/manpage-bold-literal.xsl new file +17 -0
@@ -0,0 +1,17 @@ +<!-- manpage-bold-literal.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- render literal text as bold (instead of plain or monospace); + this makes literal text easier to distinguish in manpages + viewed on a tty --> +<xsl:template match="literal"> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fB</xsl:text> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fR</xsl:text> +</xsl:template> + +</xsl:stylesheet>
Documentation/manpage-normal.xsl new file +13 -0
@@ -0,0 +1,13 @@ +<!-- manpage-normal.xsl: + special settings for manpages rendered from asciidoc+docbook + handles anything we want to keep away from docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the normal values for the roff control characters --> +<xsl:param name="git.docbook.backslash">\</xsl:param> +<xsl:param name="git.docbook.dot" >.</xsl:param> + +</xsl:stylesheet>
Documentation/manpage-suppress-sp.xsl new file +21 -0
@@ -0,0 +1,21 @@ +<!-- manpage-suppress-sp.xsl: + special settings for manpages rendered from asciidoc+docbook + handles erroneous, inline .sp in manpage output of some + versions of docbook-xsl --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- attempt to work around spurious .sp at the tail of the line + that some versions of docbook stylesheets seem to add --> +<xsl:template match="simpara"> + <xsl:variable name="content"> + <xsl:apply-templates/> + </xsl:variable> + <xsl:value-of select="normalize-space($content)"/> + <xsl:if test="not(ancestor::authorblurb) and + not(ancestor::personblurb)"> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + +</xsl:stylesheet>
Signature · 1 line
2.28.0
PATCH v2 2/8 libtracefs man pages: APIs for locating trace directory and files.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_get_tracing_file()tracefs_put_tracing_file()tracefs_get_tracing_dir()tracefs_find_tracing_dir()
--- Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 Documentation/libtracefs-files.txt
Documentation/libtracefs-files.txt new file +97 -0
@@ -0,0 +1,97 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_get_tracing_file, tracefs_put_tracing_file, tracefs_tracing_dir - +Find locations of trace directory and files. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +char pass:[*]*tracefs_get_tracing_file*(const char pass:[*]_name_); +void *tracefs_put_tracing_file*(char pass:[*]_name_); +const char pass:[*]*tracefs_tracing_dir*(void); +-- + +DESCRIPTION +----------- +This set of APIs can be used to find the full path of the trace file +system mount point and trace files in it. + +The _tracefs_get_tracing_file()_ function returns the full path of the +file with given _name_ in the trace file system. The function works +only with files in the trasefs main directory, it is not trace instance +aware. It is recommended to use _tracefs_instance_get_file()_ and +_tracefs_instance_get_dir()_ instead. The returned string must be freed +with _tracefs_put_tracing_file()_. + +The _tracefs_put_tracing_file()_ function frees trace file name, +returned by _tracefs_get_tracing_file()_. + +The _tracefs_tracing_dir()_ function returns the full path to the +trace file system. In the first function call, the mount point of the +tracing file system is located, cached and returned. It will mount it, +if it is not mounted. On any subsequent call the cached path is returned. +The return string must _not_ be freed. + +RETURN VALUE +------------ +The _tracefs_get_tracing_file()_ function returns a string or NULL in case +of an error. The returned string must be freed with _tracefs_put_tracing_file()_. + +The _tracefs_tracing_dir()_ function returns a constant string or NULL +in case of an error. The returned string must _not_ be freed. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> +... +char *trace_on = tracefs_get_tracing_file("tracing_on"); + if (trace_on) { + ... + tracefs_put_tracing_file(trace_on); + } +... +const char *trace_dir = tracefs_tracing_dir(); + +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
Re: [PATCH v2 2/8] libtracefs man pages: APIs for locating trace directory and files.
Quoted 5 lines · On Mon, 21 Dec 2020 08:02:46 +0200 "Tzvetomir Stoyanov (VMware)"…
Documented APIs:
tracefs_get_tracing_file()tracefs_put_tracing_file()tracefs_get_tracing_dir()tracefs_find_tracing_dir()
The commit log was not updated. I'll fix this.
-- Steve
Quoted 8 lines
Signed-off-by Tzvetomir Stoyanov (VMware) <[email protected]>--- Documentation/libtracefs-files.txt | 97 ++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 Documentation/libtracefs-files.txtDocumentation/libtracefs-files.txt +0
-0
PATCH v2 3/8 libtracefs man pages: APIs for working with trace systems and events.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_event_systems()tracefs_system_events()tracefs_iterate_raw_events()
--- Documentation/libtracefs-events.txt | 143 ++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 Documentation/libtracefs-events.txt
Documentation/libtracefs-events.txt new file +143 -0
@@ -0,0 +1,143 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_event_systems, tracefs_system_events, tracefs_iterate_raw_events - +Work with trace systems and events. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_); +char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_); +int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_); + +-- + +DESCRIPTION +----------- +Trace systems and events related APIs. + +The _tracefs_event_systems()_ function returns array of strings with the +names of all registered trace systems, located in the given _tracing_dir_ +directory. This could be NULL or the location of the tracefs mount point +for the trace systems of the local machine, or it may be a path to a copy +of the tracefs directory from another machine. The last entry in the array +is a NULL pointer. The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_system_events()_ function returns array of strings with the +names of all registered trace events for given trace system specified by +_system_, located in the given _tracing_dir_ directory. This could be NULL +or the location of the tracefs mount point for the trace systems of the +local machine, or it may be a path to a copy of the tracefs directory +from another machine. The last entry in the array as a NULL pointer. +The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_interate_raw_events()_ function will read the tracefs raw +data buffers and call the specified _callback_ function for every event it +encounters. An initialized _tep_ handler is required (See +_tracefs_local_events_(3)). If _instance_ is NULL, then the toplevel +tracefs buffer is used, otherwise the buffer for the corresponding +_instance_ is read. To filter only on a subset of CPUs, _cpus_ and +_cpu_size_ may be set to only call _callback_ with events that occurred on +the CPUs specified, otherwise if _cpus_ is NULL then the _callback_ +function will be called for all events, and _cpu_size_ is ignored. The +_callback_ function will be called with the following parameters: A +pointer to a struct tep_event that corresponds to the type of event the +record is; The record representing the event; The CPU that the event +occurred on; and a pointer to user specified _context_. If the _callback_ +returns non-zero, the iteration stops. + + +RETURN VALUE +------------ +The _tracefs_event_systems()_ and __tracefs_system_events()_ functions return +an array of strings. The last element in that array is a NULL pointer. The array +must be freed with _tracefs_list_free()_ API. In case of an error, NULL is returned. + +The _tracefs_iterate_raw_events()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +char **systems = tracefs_event_systems(NULL); + + if (systems) { + int i = 0; + /* Got registered trace systems from the top trace instance */ + while (systems[i]) { + char **events = tracefs_system_events(NULL, systems[i]); + if (events) { + /* Got registered events in system[i] from the top trace instance */ + int j = 0; + + while (events[j]) { + /* Got event[j] in system[i] from the top trace instance */ + j++; + } + tracefs_list_free(events); + } + i++; + } + tracefs_list_free(systems); + } +.... +static int records_walk(struct tep_event *tep, struct tep_record *record, int cpu, void *context) +{ + /* Got recorded event on cpu */ + return 0; +} +... +struct tep_event *tep = tracefs_local_events(NULL); + + if (!tep) { + /* Failed to initialise tep handler with local events */ + ... + } + if (tracefs_iterate_raw_events(tep, NULL, NULL, 0, records_walk, NULL) < 0) { + /* Error walking through the recorded raw events */ + } + tep_free(tep); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
Re: [PATCH v2 3/8] libtracefs man pages: APIs for working with trace systems and events.
Quoted 28 lines · On Mon, 21 Dec 2020 08:02:47 +0200 "Tzvetomir Stoyanov (VMware)"…
Documentation/libtracefs-events.txt new file +28
-0+char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_); +char pass:[*]pass:[*]*tracefs_system_events*(const char pass:[*]_tracing_dir_, const char pass:[*]_system_); +int *tracefs_iterate_raw_events*(struct tep_handle pass:[*]_tep_, struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_cpus_, int _cpu_size_, int (pass:[*]_callback_)(struct tep_event pass:[*], struct tep_record pass:[*], int, void pass:[*]), void pass:[*]_callback_context_); + +-- + +DESCRIPTION +----------- +Trace systems and events related APIs. + +The _tracefs_event_systems()_ function returns array of strings with the +names of all registered trace systems, located in the given _tracing_dir_ +directory. This could be NULL or the location of the tracefs mount point +for the trace systems of the local machine, or it may be a path to a copy +of the tracefs directory from another machine. The last entry in the array +is a NULL pointer. The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_system_events()_ function returns array of strings with the +names of all registered trace events for given trace system specified by +_system_, located in the given _tracing_dir_ directory. This could be NULL +or the location of the tracefs mount point for the trace systems of the +local machine, or it may be a path to a copy of the tracefs directory +from another machine. The last entry in the array as a NULL pointer. +The array must be freed with _tracefs_list_free()_ API. + +The _tracefs_interate_raw_events()_ function will read the tracefs raw +data buffers and call the specified _callback_ function for every event it +encounters. An initialized _tep_ handler is required (See
Documentation/libtracefs-events.txt line 52
Quoted 10 lines
Documentation/libtracefs-events.txt new file +10
-0+_tracefs_local_events_(3)). If _instance_ is NULL, then the toplevel +tracefs buffer is used, otherwise the buffer for the corresponding +_instance_ is read. To filter only on a subset of CPUs, _cpus_ and +_cpu_size_ may be set to only call _callback_ with events that occurred on +the CPUs specified, otherwise if _cpus_ is NULL then the _callback_ +function will be called for all events, and _cpu_size_ is ignored. The +_callback_ function will be called with the following parameters: A +pointer to a struct tep_event that corresponds to the type of event the +record is; The record representing the event; The CPU that the event +occurred on; and a pointer to user specified _context_. If the _callback_
I changed "_context_" to "_callback_context_" as it should match the name used above in the function prototype.
-- Steve
Quoted 1 line
+returns non-zero, the iteration stops.
PATCH v2 4/8 libtracefs man pages: APIs for managing trace instances.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_instance_create()tracefs_instance_destroy()tracefs_instance_free()tracefs_instance_is_new()
--- Documentation/libtracefs-instances-manage.txt | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 Documentation/libtracefs-instances-manage.txt
Documentation/libtracefs-instances-manage.txt new file +111 -0
@@ -0,0 +1,111 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_instance_create, tracefs_instance_destroy, tracefs_instance_free, +tracefs_instance_is_new - Manage trace instances. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +struct tracefs_instance pass:[*]*tracefs_instance_create*(const char pass:[*]_name_); +int *tracefs_instance_destroy*(struct tracefs_instance pass:[*]_instance_); +void *tracefs_instance_free*(struct tracefs_instance pass:[*]_instance_); +bool *tracefs_instance_is_new*(struct tracefs_instance pass:[*]_instance_); + +-- + +DESCRIPTION +----------- +This set of functions can be used to manage trace instances. A trace +instance is a sub buffer used by the Linux tracing system. Given a unique +name, the events enabled in an instance do not affect the main tracing +system, nor other instances, as events enabled in the main tracing system +or other instances do not affect the given instance. + +The _tracefs_instance_create()_ function allocates and initializes a new +tracefs_instance structure and returns it. If the instance does not yet +exist in the system, it will be created. + +The _tracefs_instance_destroy()_ frees the _instance_ structure, and will +also remove the trace instance from the system. + +The _tracefs_instance_free()_ function frees the tracefs_instance structure, +without removing the trace instance from the system. + +The _tracefs_instance_is_new()_ function checks if the given _instance_ is +newly created by _tracefs_instance_create()_, or it has been in the system +before that. + +RETURN VALUE +------------ +The _tracefs_instance_create()_ function returns a pointer to a newly allocated +tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or +_tracefs_instance_free()_. + +The _tracefs_instance_destroy()_ function returns -1 in case of an error, +or 0 otherwise. + +The _tracefs_instance_is_new()_ function returns true if the +_tracefs_instance_create() that allocated _instance_ also created the +trace instance in the system, or false if the trace instance already +existed in the system when _instance_ was allocated by +_tracefs_instance_create()_. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +struct tracefs_instance *inst = tracefs_instance_create("foo"); + if (!inst) { + /* Error creating a new trace instance */ + ... + } + + ... + + if (tracefs_instance_is_new(inst)) + tracefs_instance_destroy(inst); + else + tracefs_instance_free(inst); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
Re: [PATCH v2 4/8] libtracefs man pages: APIs for managing trace instances.
Documentation/libtracefs-instances-manage.txt line 54
Quoted 11 lines · On Mon, 21 Dec 2020 08:02:48 +0200 "Tzvetomir Stoyanov (VMware)"…
Documentation/libtracefs-instances-manage.txt new file +11
-0+RETURN VALUE +------------ +The _tracefs_instance_create()_ function returns a pointer to a newly allocated +tracefs_instance structure. It must be freed with _tracefs_instance_destroy()_ or +_tracefs_instance_free()_. + +The _tracefs_instance_destroy()_ function returns -1 in case of an error, +or 0 otherwise. + +The _tracefs_instance_is_new()_ function returns true if the +_tracefs_instance_create() that allocated _instance_ also created the
Missing underscore after "_tracefs_instance_create()", which caused a run-away underlining. I fixed it.
-- Steve
Quoted 4 lines
Documentation/libtracefs-instances-manage.txt new file +4
-0+trace instance in the system, or false if the trace instance already +existed in the system when _instance_ was allocated by +_tracefs_instance_create()_. +
PATCH v2 5/8 libtracefs man pages: APIs for working with files in trace instances.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_file_exists()tracefs_dir_exists()tracefs_instance_get_file()tracefs_instance_get_dir()tracefs_instance_file_write()tracefs_instance_file_read()
--- Documentation/libtracefs-instances-files.txt | 160 +++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 Documentation/libtracefs-instances-files.txt
Documentation/libtracefs-instances-files.txt new file +160 -0
@@ -0,0 +1,160 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_file_exists, tracefs_dir_exists, tracefs_instance_get_file, +tracefs_instance_get_dir, tracefs_instance_file_write, +tracefs_instance_file_read - Work with files in tracing instances. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +bool *tracefs_file_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); +bool *tracefs_dir_exists*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_name_); +char pass:[*]*tracefs_instance_get_file*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_); +char pass:[*]*tracefs_instance_get_dir*(struct tracefs_instance pass:[*]_instance_); +int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_); +char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, char pass:[*]_file_, int pass:[*]_psize_); + +-- + +DESCRIPTION +----------- +This set of APIs can be used to work with trace files in all trace instances. +Each of these APIs take an _instance_ argument, that can be NULL to act +on the top level instance. Otherwise, it acts on an instance created with +*tracefs_insance_create*(3) + +The _tracefs_file_exists()_ function checks if a file with _name_ exists in _instance_. + +The _tracefs_dir_exists()_ function checks if a directory with _name_ exists in _instance_. + +The _tracefs_instance_get_file()_ function returns the full path of the file +with given _name_ in _instance_. Note, it does not check if the file exists in +the instance. + +The _tracefs_instance_get_dir()_ function returns the full path of the directory +with given _name_ in _instance_. Note, it does not check if the directory exists +in the instance. + +The _tracefs_instance_file_write()_ function writes a string _str_ in a _file_ from +the given _instance_, without the terminating NULL character. + +The _tracefs_instance_file_read()_ function reads the content of a _file_ from +the given _instance_. + +RETURN VALUE +------------ +The _tracefs_file_exists()_ and _tracefs_dir_exists()_ functions return true if the +file / directory exist in the given instance or false if it does not exist. + +The _tracefs_instance_get_file()_ and _tracefs_instance_get_dir()_ functions return +a string or NULL in case of an error. The returned string must be freed with +_tracefs_put_tracing_file()_. + +The _tracefs_instance_file_write()_ function returns the number of written bytes, +or -1 in case of an error. + +The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminated +string, read from the file, or NULL in case of an error. The returned string must +be freed with free(). + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +struct tracefs_instance *inst = tracefs_instance_create("foo"); + if (!inst) { + /* Error creating a new trace instance */ + ... + } + + if (tracefs_file_exists(inst,"trace_clock")) { + /* The instance foo supports trace clock */ + char *path, *clock; + int size; + + path = = tracefs_instance_get_file(inst, "trace_clock") + if (!path) { + /* Error getting the path to trace_clock file in instance foo */ + ... + } + ... + tracefs_put_tracing_file(path); + + clock = tracefs_instance_file_read(inst, "trace_clock", &size); + if (!clock) { + /* Failed to read trace_clock file in instance foo */ + ... + } + ... + free(clock); + + if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) { + /* Failed to set gloabl trace clock in instance foo */ + ... + } + } else { + /* The instance foo does not support trace clock */ + } + + if (tracefs_dir_exists(inst,"options")) { + /* The instance foo supports trace options */ + char *path = tracefs_instance_get_file(inst, "options"); + if (!path) { + /* Error getting the path to options directory in instance foo */ + ... + } + + tracefs_put_tracing_file(path); + } else { + /* The instance foo does not support trace options */ + } + + ... + + if (tracefs_instance_is_new(inst)) + tracefs_instance_destroy(inst); + else + tracefs_instance_free(inst); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
PATCH v2 6/8 libtracefs man pages: helper APIs for working with trace instances.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_instance_get_name()tracefs_instances_walk()tracefs_instance_exists()
--- Documentation/libtracefs-instances-utils.txt | 112 +++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 Documentation/libtracefs-instances-utils.txt
Documentation/libtracefs-instances-utils.txt new file +112 -0
@@ -0,0 +1,112 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_instance_get_name, tracefs_instances_walk, tracefs_instance_exists - +Helper functions for working with tracing instances. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +const char pass:[*]*tracefs_instance_get_name*(struct tracefs_instance pass:[*]_instance_); +int *tracefs_instances_walk*(int (pass:[*]_callback_)(const char pass:[*], void pass:[*]), void pass:[*]_context)_; +bool *tracefs_instance_exists*(const char pass:[*]_name_); + +-- + +DESCRIPTION +----------- +Helper functions for working with trace instances. + +The _tracefs_instance_get_name()_ function returns the name of the given _instance_. +Note that the top instance has no name, the function returns NULL for it. + +The _tracefs_instances_walk()_ function walks through all configured tracing +instances in the system and calls _callback_ for each one of them. The _context_ +argument is passed to the _callback_, together with the instance name. If the +_callback_ returns non-zero, the iteration stops. Note, the _callback_ is not +called for the top top instance. + +The _tracefs_instance_exists()_ function checks if an instance with the given +_name_ exists in the system. + +RETURN VALUE +------------ +The _tracefs_instance_get_name()_ returns a string or NULL in case of the top +instance. The returned string must _not_ be freed. + +The _tracefs_instances_walk()_ function returns 0, if all instances were iterated, 1 +if the iteration was stopped by the _callback_, or -1 in case of an error. + +The _tracefs_instance_exists()_ returns true if an instance with the given name +exists in the system or false otherwise. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +struct tracefs_instance *inst; +.... +char *name = tracefs_instance_get_name(inst); + + if(name) { + /* Got name of the instance */ + } + +... +static int instance_walk(char *name, void *context) +{ + /* Got instance with name */ + return 0; +} +... + if (tracefs_instances_walk(instance_walk, NULL) < 0) { + /* Error walking through the instances */ + } +... + if (tracefs_instance_exists("foo")) { + /* There is instance with name foo in the system */ + } else { + /* There is no instance with name foo in the system */ + } +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
PATCH v2 7/8 libtracefs man pages: APIs for initializing a tep handler with trace events from the local system.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_local_events()tracefs_local_events_system()tracefs_fill_local_events()
--- Documentation/libtracefs-events-tep.txt | 131 ++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 Documentation/libtracefs-events-tep.txt
Documentation/libtracefs-events-tep.txt new file +131 -0
@@ -0,0 +1,131 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_local_events, tracefs_local_events_system, tracefs_fill_local_events - +Initialize a tep handler with trace events from the local system. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* +*#include <event-parse.h>* + +struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_); +struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_); +int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_); + +-- + +DESCRIPTION +----------- +Functions for initializing a tep handler with trace events from the local system. + +The _tracefs_local_events()_ function allocates a new _tep_ handler and +initializes it with events from all trace systems, located in the given +_tracing_dir_ directory. This could be NULL or tracefs mount point, for +trace events in top instance, or full path to a trace instance, for trace +events in that instance. + +The _tracefs_local_events_system()_ function allocates a new _tep_ handler +and initializes it with events from specified trace systems _sys_names_, +located in the given _tracing_dir_ directory. This could be NULL or tracefs +mount point, for trace events in top instance, or full path to a trace instance, +for trace events in that instance. The _sys_names_ argument is an array of +trace system names, that will be used for _tep_ handler initialization. +The last element in that array must be a NULL pointer. + +The _tracefs_fill_local_events()_ function initializes already allocated _tep_ +handler with events from all trace systems, located in the given _tracing_dir_ +directory. This could be NULL or tracefs mount point, for trace events in +the top instance, or full path to a trace instance, for trace events in that +instance. The _tep_ argument must be a pointer to already allocated tep +handler, that is going to be initialized. The _parsing_failures_ argument +could be NULL or a pointer to an integer, where the number of failures while +parsing the event files are returned. + +RETURN VALUE +------------ +The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions +return pointer to allocated and initialized _tep_ handler, or NULL in +case of an error. The returned _tep_ handler must be freed with _tep_free()_. + +The _tracefs_fill_local_events()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> +#include <event-parse.h> + +struct tep_event *tep; +... + tep = tracefs_local_events(NULL); + if (!tep) { + /* Failed to initialise tep handler with local events from top instance */ + ... + } +... + tep_free(tep); +... + const char *systems[] = {"ftrace", "irq", NULL}; + tep = tracefs_local_events_system(NULL, systems); + if (!tep) { + /* Failed to initialise tep handler with local events from + * ftrace and irq systems in top instance. + */ + ... + } +... + tep_free(tep); +... + int parsing_failures; + tep = tep_alloc(); + if (!tep) { + /* Failed to allocate a tep handler */ + ... + } + if (tracefs_fill_local_events(NULL, tep, &parsing_failures) < 0) { + /* Failed to initialise tep handler with local events from top instance */ + } +... + tep_free(tep); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
Steven Rostedt
AppliedRe: [PATCH v2 7/8] libtracefs man pages: APIs for initializing a tep handler with trace events from the local system.
I've applied everything up to this patch, but this patch will need to be updated more than just a tweak, so I'm not pulling it in.
Quoted 21 lines · On Mon, 21 Dec 2020 08:02:51 +0200 "Tzvetomir Stoyanov (VMware)"…
Documented APIs:
tracefs_local_events()tracefs_local_events_system()tracefs_fill_local_events()Signed-off-by Tzvetomir Stoyanov (VMware) <[email protected]>--- Documentation/libtracefs-events-tep.txt | 131 ++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 Documentation/libtracefs-events-tep.txtDocumentation/libtracefs-events-tep.txt new file +4
-0@@ -0,0 +1,131 @@ +libtracefs(3) +============= + +NAME
Documentation/libtracefs-events-tep.txt line 14
Quoted 10 lines
Documentation/libtracefs-events-tep.txt new file +10
-0+---- +tracefs_local_events, tracefs_local_events_system, tracefs_fill_local_events - +Initialize a tep handler with trace events from the local system. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* +*#include <event-parse.h>*
No need for the "event-parse.h"
Quoted 6 lines
Documentation/libtracefs-events-tep.txt new file +6
-0+ +struct tep_handle pass:[*]*tracefs_local_events*(const char pass:[*]_tracing_dir_); +struct tep_handle pass:[*]*tracefs_local_events_system*(const char pass:[*]_tracing_dir_, const char pass:[*] const pass:[*]_sys_names_); +int *tracefs_fill_local_events*(const char pass:[*]_tracing_dir_, struct tep_handle pass:[*]_tep_, int pass:[*]_parsing_failures_); + +--
Documentation/libtracefs-events-tep.txt line 30
Quoted 10 lines
Documentation/libtracefs-events-tep.txt new file +10
-0+ +DESCRIPTION +----------- +Functions for initializing a tep handler with trace events from the local system. + +The _tracefs_local_events()_ function allocates a new _tep_ handler and +initializes it with events from all trace systems, located in the given +_tracing_dir_ directory. This could be NULL or tracefs mount point, for +trace events in top instance, or full path to a trace instance, for trace +events in that instance.
The definition of _tracing_dir_ needs to be updated to what the other patches were. They shouldn't mention the full path to a trace instance.
Quoted 7 lines
Documentation/libtracefs-events-tep.txt new file +7
-0+ +The _tracefs_local_events_system()_ function allocates a new _tep_ handler +and initializes it with events from specified trace systems _sys_names_, +located in the given _tracing_dir_ directory. This could be NULL or tracefs +mount point, for trace events in top instance, or full path to a trace instance, +for trace events in that instance. The _sys_names_ argument is an array of +trace system names, that will be used for _tep_ handler initialization.
Documentation/libtracefs-events-tep.txt line 47
Quoted 10 lines
Documentation/libtracefs-events-tep.txt new file +10
-0+The last element in that array must be a NULL pointer. + +The _tracefs_fill_local_events()_ function initializes already allocated _tep_ +handler with events from all trace systems, located in the given _tracing_dir_ +directory. This could be NULL or tracefs mount point, for trace events in +the top instance, or full path to a trace instance, for trace events in that +instance. The _tep_ argument must be a pointer to already allocated tep +handler, that is going to be initialized. The _parsing_failures_ argument +could be NULL or a pointer to an integer, where the number of failures while +parsing the event files are returned.
Same with the above two.
Documentation/libtracefs-events-tep.txt line 53
Quoted 6 lines
Documentation/libtracefs-events-tep.txt new file +6
-0+ +RETURN VALUE +------------ +The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions +return pointer to allocated and initialized _tep_ handler, or NULL in +case of an error. The returned _tep_ handler must be freed with _tep_free()_.
"must be freed with _tep_free(3)_"
As there is a man page for that one.
Thanks!
-- Steve
Quoted 79 lines
Documentation/libtracefs-events-tep.txt new file +78
-0+ +The _tracefs_fill_local_events()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> +#include <event-parse.h> + +struct tep_event *tep; +... + tep = tracefs_local_events(NULL); + if (!tep) { + /* Failed to initialise tep handler with local events from top instance */ + ... + } +... + tep_free(tep); +... + const char *systems[] = {"ftrace", "irq", NULL}; + tep = tracefs_local_events_system(NULL, systems); + if (!tep) { + /* Failed to initialise tep handler with local events from + * ftrace and irq systems in top instance. + */ + ... + } +... + tep_free(tep); +... + int parsing_failures; + tep = tep_alloc(); + if (!tep) { + /* Failed to allocate a tep handler */ + ... + } + if (tracefs_fill_local_events(NULL, tep, &parsing_failures) < 0) { + /* Failed to initialise tep handler with local events from top instance */ + } +... + tep_free(tep); +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
PATCH v2 8/8 libtracefs man pages: helper APIs for working with trace file system.
In reply to Tzvetomir Stoyanov (VMware)Documented APIs:tracefs_tracers()tracefs_get_clock()tracefs_list_free()
--- Documentation/libtracefs-utils.txt | 103 +++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Documentation/libtracefs-utils.txt
Documentation/libtracefs-utils.txt new file +103 -0
@@ -0,0 +1,103 @@ +libtracefs(3) +============= + +NAME +---- +tracefs_tracers, tracefs_get_clock, tracefs_list_free - +Helper functions for working with trace file system. + +SYNOPSIS +-------- +[verse] +-- +*#include <tracefs.h>* + +char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); +char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_); +void *tracefs_list_free*(char pass:[*]pass:[*]_list_); +-- + +DESCRIPTION +----------- +Various useful functions for working with trace file system. + +The _tracefs_tracers()_ function returns array of strings with the +names of supported tracer plugins, located in the given _tracing_dir_ directory. +This could be NULL or tracefs mount point, for trace systems in top instance, +or full path to a trace instance, for trace systems in that instance. +The last entry in the array as a NULL pointer. The array must +be freed with _tracefs_list_free()_ API. + +The _tracefs_get_clock()_ function returns name of the current trace clock, +used in the given _instance_. If _instance_ is NULL, the clock of the main +trace instance is returned. The returned string must be freed with free(). + +The _tracefs_list_free()_ function frees an array of strings, returned by +_tracefs_event_systems()_, _tracefs_system_events()_ and _tracefs_tracers()_ +APIs. + +RETURN VALUE +------------ +The _tracefs_tracers()_ returns array of strings. The last element in that +array is a NULL pointer. The array must be freed with _tracefs_list_free()_ API. +In case of an error, NULL is returned. + +The _tracefs_get_clock()_ returns string, that must be freed with free(), or NULL +in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include <tracefs.h> + +char **tracers = tracefs_tracers(NULL); + + if (tracers) { + /* Got tracer plugins from the top trace instance */ + ... + tracefs_list_free(tracers); + } +.... +char *clock = tracefs_get_clock(NULL); + + if (clock) { + /* Got current trace clock of the top trace instance */ + ... + free(clock); + } +-- +FILES +----- +[verse] +-- +*tracefs.h* + Header file to include in order to have access to the library APIs. +*-ltracefs* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <[email protected]> +*Tzvetomir Stoyanov* <[email protected]> +-- +REPORTING BUGS +-------------- +Report bugs to <[email protected]> + +LICENSE +------- +libtracefs is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
Signature · 1 line
2.28.0
Re: [PATCH v2 8/8] libtracefs man pages: helper APIs for working with trace file system.
Documentation/libtracefs-utils.txt line 29
Quoted 10 lines · On Mon, 21 Dec 2020 08:02:52 +0200 "Tzvetomir Stoyanov (VMware)"…
Documentation/libtracefs-utils.txt new file +10
-0+DESCRIPTION +----------- +Various useful functions for working with trace file system. + +The _tracefs_tracers()_ function returns array of strings with the +names of supported tracer plugins, located in the given _tracing_dir_ directory. +This could be NULL or tracefs mount point, for trace systems in top instance, +or full path to a trace instance, for trace systems in that instance. +The last entry in the array as a NULL pointer. The array must +be freed with _tracefs_list_free()_ API.
The description above needs to be updated as well.
-- Steve
Quoted 9 lines
Documentation/libtracefs-utils.txt new file +9
-0+ +The _tracefs_get_clock()_ function returns name of the current trace clock, +used in the given _instance_. If _instance_ is NULL, the clock of the main +trace instance is returned. The returned string must be freed with free(). + +The _tracefs_list_free()_ function frees an array of strings, returned by +_tracefs_event_systems()_, _tracefs_system_events()_ and _tracefs_tracers()_ +APIs. +