tools lib traceevent: Remove libtraceevent

# SPDX-License-Identifier: GPL-2.0-only

TRACEEVENT-CFLAGS

libtraceevent-dynamic-list

libtraceevent.so.*

libtraceevent-y += event-parse.o

libtraceevent-y += event-plugin.o

libtraceevent-y += trace-seq.o

libtraceevent-y += parse-filter.o

libtraceevent-y += parse-utils.o

libtraceevent-y += kbuffer-parse.o

libtraceevent-y += tep_strerror.o

libtraceevent-y += event-parse-api.o

include ../../../scripts/Makefile.include

include ../../../scripts/utilities.mak

# This Makefile and manpage XSL files were taken from tools/perf/Documentation

# and modified for libtraceevent.

MAN3_TXT= \

	$(wildcard libtraceevent-*.txt) \

	libtraceevent.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/libtraceevent-doc

pdfdir?=$(prefix)/share/doc/libtraceevent-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="libtraceevent" -a manmanual="libtraceevent 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 libtraceevent-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 libtraceevent-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

#

# Please note that there is a minor bug in asciidoc.

# The version after 6.0.3 _will_ include the patch found here:

#   http://marc.theaimsgroup.com/?l=libtraceevent&m=111558757202243&w=2

#

# Until that version is released you may have to apply the patch

# yourself - yes, all 6 characters of it!

#

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

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 $(DOC_MAN3) $(DESTDIR)$(man3dir);

install-man: check-man-tools man do-install-man

uninstall: uninstall-man

uninstall-man:

	$(call QUIET_UNINST, Documentation-man) \

		$(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3))

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 $@+ $@

## linktep: macro

#

# Usage: linktep:command[manpage-section]

#

# Note, {0} is the manpage section, while {target} is the command.

#

# Show TEP link as: <command>(<section>); if section is defined, else just show

# the command.

[macros]

(?su)[\\]?(?P<name>linktep):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=

[attributes]

asterisk=*

plus=+

caret=^

startsb=[

endsb=]

tilde=~

ifdef::backend-docbook[]

[linktep-inlinemacro]

{0%{target}}

{0#<citerefentry>}

{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}

{0#</citerefentry>}

endif::backend-docbook[]

ifdef::backend-docbook[]

ifndef::tep-asciidoc-no-roff[]

# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.

# v1.72 breaks with this because it replaces dots not in roff requests.

[listingblock]

<example><title>{title}</title>

<literallayout>

ifdef::doctype-manpage[]


.ft C


endif::doctype-manpage[]

|

ifdef::doctype-manpage[]


.ft


endif::doctype-manpage[]

</literallayout>

{title#}</example>

endif::tep-asciidoc-no-roff[]

ifdef::tep-asciidoc-no-roff[]

ifdef::doctype-manpage[]

# The following two small workarounds insert a simple paragraph after screen

[listingblock]

<example><title>{title}</title>

<literallayout>

|

</literallayout><simpara></simpara>

{title#}</example>

[verseblock]

<formalpara{id? id="{id}"}><title>{title}</title><para>

{title%}<literallayout{id? id="{id}"}>

{title#}<literallayout>

|

</literallayout>

{title#}</para></formalpara>

{title%}<simpara></simpara>

endif::doctype-manpage[]

endif::tep-asciidoc-no-roff[]

endif::backend-docbook[]

ifdef::doctype-manpage[]

ifdef::backend-docbook[]

[header]

template::[header-declarations]

<refentry>

<refmeta>

<refentrytitle>{mantitle}</refentrytitle>

<manvolnum>{manvolnum}</manvolnum>

<refmiscinfo class="source">libtraceevent</refmiscinfo>

<refmiscinfo class="version">{libtraceevent_version}</refmiscinfo>

<refmiscinfo class="manual">libtraceevent Manual</refmiscinfo>

</refmeta>

<refnamediv>

  <refname>{manname1}</refname>

  <refname>{manname2}</refname>

  <refname>{manname3}</refname>

  <refname>{manname4}</refname>

  <refname>{manname5}</refname>

  <refname>{manname6}</refname>

  <refname>{manname7}</refname>

  <refname>{manname8}</refname>

  <refname>{manname9}</refname>

  <refname>{manname10}</refname>

  <refname>{manname11}</refname>

  <refname>{manname12}</refname>

  <refname>{manname13}</refname>

  <refname>{manname14}</refname>

  <refname>{manname15}</refname>

  <refname>{manname16}</refname>

  <refname>{manname17}</refname>

  <refname>{manname18}</refname>

  <refname>{manname19}</refname>

  <refname>{manname20}</refname>

  <refname>{manname21}</refname>

  <refname>{manname22}</refname>

  <refname>{manname23}</refname>

  <refname>{manname24}</refname>

  <refname>{manname25}</refname>

  <refname>{manname26}</refname>

  <refname>{manname27}</refname>

  <refname>{manname28}</refname>

  <refname>{manname29}</refname>

  <refname>{manname30}</refname>

  <refpurpose>{manpurpose}</refpurpose>

</refnamediv>

endif::backend-docbook[]

endif::doctype-manpage[]

ifdef::backend-xhtml11[]

[linktep-inlinemacro]

<a href="{target}.html">{target}{0?({0})}</a>

endif::backend-xhtml11[]

libtraceevent(3)

================

NAME

----

tep_register_comm, tep_override_comm, tep_pid_is_registered,

tep_data_comm_from_pid, tep_data_pid_from_comm, tep_cmdline_pid -

Manage pid to process name mappings.

SYNOPSIS

--------

[verse]

--

*#include <event-parse.h>*

int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);

int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);

bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_);

const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_);

struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_);

int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_);

--

DESCRIPTION

-----------

These functions can be used to handle the mapping between pid and process name.

The library builds a cache of these mappings, which is used to display the name

of the process, instead of its pid. This information can be retrieved from

tracefs/saved_cmdlines file.

The _tep_register_comm()_ function registers a _pid_ / process name mapping.

If a command with the same _pid_ is already registered, an error is returned.

The _pid_ argument is the process ID, the _comm_ argument is the process name,

_tep_ is the event context. The _comm_ is duplicated internally.

The _tep_override_comm()_ function registers a _pid_ / process name mapping.

If a process with the same pid is already registered, the process name string is

udapted with the new one. The _pid_ argument is the process ID, the _comm_

argument is the process name, _tep_ is the event context. The _comm_ is

duplicated internally.

The _tep_is_pid_registered()_ function checks if a pid has a process name

mapping registered. The _pid_ argument is the process ID, _tep_ is the event

context.

The _tep_data_comm_from_pid()_ function returns the process name for a given

pid. The _pid_ argument is the process ID, _tep_ is the event context.

The returned string should not be freed, but will be freed when the _tep_

handler is closed.

The _tep_data_pid_from_comm()_ function returns a pid for a given process name.

The _comm_ argument is the process name, _tep_ is the event context.

The argument _next_ is the cmdline structure to search for the next pid.

As there may be more than one pid for a given process, the result of this call

can be passed back into a recurring call in the _next_ parameter, to search for

the next pid. If _next_ is NULL, it will return the first pid associated with

the _comm_. The function performs a linear search, so it may be slow.

The _tep_cmdline_pid()_ function returns the pid associated with a given

_cmdline_. The _tep_ argument is the event context.

RETURN VALUE

------------

_tep_register_comm()_ function returns 0 on success. In case of an error -1 is

returned and errno is set to indicate the cause of the problem: ENOMEM, if there

is not enough memory to duplicate the _comm_ or EEXIST if a mapping for this

_pid_ is already registered.

_tep_override_comm()_ function returns 0 on success. In case of an error -1 is

returned and errno is set to indicate the cause of the problem: ENOMEM, if there

is not enough memory to duplicate the _comm_.

_tep_is_pid_registered()_ function returns true if the _pid_ has a process name

mapped to it, false otherwise.

_tep_data_comm_from_pid()_ function returns the process name as string, or the

string "<...>" if there is no mapping for the given pid.

_tep_data_pid_from_comm()_ function returns a pointer to a struct cmdline, that

holds a pid for a given process, or NULL if none is found. This result can be

passed back into a recurring call as the _next_ parameter of the function.

_tep_cmdline_pid()_ functions returns the pid for the give cmdline. If _cmdline_

 is NULL, then -1 is returned.

EXAMPLE

-------

The following example registers pid for command "ls", in context of event _tep_

and performs various searches for pid / process name mappings:

[source,c]

--

#include <event-parse.h>

...

int ret;

int ls_pid = 1021;

struct tep_handle *tep = tep_alloc();

...

	ret = tep_register_comm(tep, "ls", ls_pid);

	if (ret != 0 && errno == EEXIST)

		ret = tep_override_comm(tep, "ls", ls_pid);

	if (ret != 0) {

		/* Failed to register pid / command mapping */

	}

...

	if (tep_is_pid_registered(tep, ls_pid) == 0) {

		/* Command mapping for ls_pid is not registered */

	}

...

	const char *comm = tep_data_comm_from_pid(tep, ls_pid);

	if (comm) {

		/* Found process name for ls_pid */

	}

...

	int pid;

	struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL);

	while (cmd) {

		pid = tep_cmdline_pid(tep, cmd);

		/* Found pid for process "ls" */

		cmd = tep_data_pid_from_comm(tep, "ls", cmd);

	}

--

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*.

*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.

--

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/linux/kernel/git/torvalds/linux.git