Man pages updates and fixes
cover Man pages updates and fixes
Unified the man pages style and updated the main man page.
Tzvetomir Stoyanov (VMware) (2):
libtracefs: Unify man pages style
libtracefs: Update main man page
Documentation/libtracefs-error.txt | 2 +- Documentation/libtracefs-events-tep.txt | 18 +-- Documentation/libtracefs-events.txt | 39 ++--- Documentation/libtracefs-files.txt | 20 +-- Documentation/libtracefs-filter.txt | 12 +- Documentation/libtracefs-function-filter.txt | 8 +- Documentation/libtracefs-hist-cont.txt | 20 +-- Documentation/libtracefs-hist.txt | 127 ++++++++-------- .../libtracefs-instances-affinity.txt | 14 +- .../libtracefs-instances-file-manip.txt | 26 ++-- Documentation/libtracefs-instances-files.txt | 14 +- Documentation/libtracefs-instances-manage.txt | 28 ++-- Documentation/libtracefs-instances-utils.txt | 16 +- Documentation/libtracefs-log.txt | 4 +- Documentation/libtracefs-marker.txt | 12 +- Documentation/libtracefs-marker_raw.txt | 12 +- Documentation/libtracefs-option-get.txt | 18 +-- Documentation/libtracefs-option-misc.txt | 10 +- Documentation/libtracefs-sql.txt | 8 +- Documentation/libtracefs-stream.txt | 14 +- Documentation/libtracefs-synth.txt | 84 +++++------ Documentation/libtracefs-synth2.txt | 55 +++---- Documentation/libtracefs-traceon.txt | 18 +-- Documentation/libtracefs-tracer.txt | 4 +- Documentation/libtracefs-utils.txt | 16 +- Documentation/libtracefs.txt | 140 +++++++++++++++++- 26 files changed, 441 insertions(+), 298 deletions(-)
Signature · 1 line
2.34.1
PATCH 1/2 libtracefs: Unify man pages style
Man pages of the library should have consistent view. There are some differences in functions and arguments visualisation across current man pages. Made the style of all pages consistent:
- all function names in bold
- all arguments are underlined.
Fixed also a few spelling mistakes.
--- Documentation/libtracefs-error.txt | 2 +- Documentation/libtracefs-events-tep.txt | 18 +-- Documentation/libtracefs-events.txt | 39 +++--- Documentation/libtracefs-files.txt | 20 +-- Documentation/libtracefs-filter.txt | 12 +- Documentation/libtracefs-function-filter.txt | 8 +- Documentation/libtracefs-hist-cont.txt | 20 +-- Documentation/libtracefs-hist.txt | 127 +++++++++--------- .../libtracefs-instances-affinity.txt | 14 +- .../libtracefs-instances-file-manip.txt | 26 ++-- Documentation/libtracefs-instances-files.txt | 14 +- Documentation/libtracefs-instances-manage.txt | 28 ++-- Documentation/libtracefs-instances-utils.txt | 16 +-- Documentation/libtracefs-log.txt | 4 +- Documentation/libtracefs-marker.txt | 12 +- Documentation/libtracefs-marker_raw.txt | 12 +- Documentation/libtracefs-option-get.txt | 18 +-- Documentation/libtracefs-option-misc.txt | 10 +- Documentation/libtracefs-sql.txt | 8 +- Documentation/libtracefs-stream.txt | 14 +- Documentation/libtracefs-synth.txt | 84 ++++++------ Documentation/libtracefs-synth2.txt | 55 ++++---- Documentation/libtracefs-traceon.txt | 18 +-- Documentation/libtracefs-tracer.txt | 4 +- Documentation/libtracefs-utils.txt | 16 +-- Documentation/libtracefs.txt | 2 +- 26 files changed, 304 insertions(+), 297 deletions(-)
Documentation/libtracefs-error.txt +1 -1
@@ -13,7 +13,7 @@ SYNOPSIS *#include <tracefs.h>* char pass:[*]*tracefs_error_last*(struct tracefs_instance pass:[*]_instance_); -char pass:[*]*tracefs_error_last*(struct tracefs_instance pass:[*]_instance_); +char pass:[*]*tracefs_error_all*(struct tracefs_instance pass:[*]_instance_); int *tracefs_error_clear*(struct tracefs_instance pass:[*]_instance_); --
Documentation/libtracefs-events-tep.txt +9 -9
@@ -23,13 +23,13 @@ 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 +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 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 _tracefs_local_events_system()_ function allocates a new _tep_ handler +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 the location of the tracefs mount point for the trace systems of the local
@@ -38,7 +38,7 @@ machine. 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_ +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 the location of the tracefs mount point for the trace systems of the local machine, or it may be a path to a copy
@@ -51,20 +51,20 @@ The above functions will also load the mappings between pids and the process command line names. In some cases the _tep_ handle is created with one of the above before tracing begins. As the mappings get updated during the trace, there may be a need to read the mappings again after the trace. -The _tracefs_load_cmdlines()_ does just that. The _tracing_dir_ is -the director of the mount point to load from, or NULL to use the +The *tracefs_load_cmdlines()* does just that. The _tracing_dir_ is +the directory of the mount point to load from, or NULL to use the mount point of the tracefs file system. RETURN VALUE ------------ -The _tracefs_local_events()_ and _tracefs_local_events_system()_ functions +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(3)_. +case of an error. The returned _tep_ handler must be freed with *tep_free(3)*. -The _tracefs_fill_local_events()_ function returns -1 in case of an error or +The *tracefs_fill_local_events()* function returns -1 in case of an error or 0 otherwise. -The _tracefs_load_cmdlines()_ function returns -1 in case of an error, or +The *tracefs_load_cmdlines()* function returns -1 in case of an error, or 0 otherwise. EXAMPLE
Documentation/libtracefs-events.txt +22 -17
@@ -14,9 +14,14 @@ SYNOPSIS 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_event_enable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_); -int *tracefs_event_disable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, const char pass:[*]_event_); -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_); +int *tracefs_event_enable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, + const char pass:[*]_event_); +int *tracefs_event_disable*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_system_, + const char pass:[*]_event_); +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_); --
@@ -24,22 +29,22 @@ DESCRIPTION ----------- Trace systems and events related APIs. -The _tracefs_event_systems()_ function returns array of strings with the +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. +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 +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 array must be freed with *tracefs_list_free()* API. -The _tracefs_event_enable()_ function enables a given event based on +The *tracefs_event_enable()* function enables a given event based on the _system_ and _event_ passed in for the given _instance_. If _instance_ is NULL, then the top level tracing directory is used. If _system_ and _event_ are both NULL, then all events are enabled for the _instance_.
@@ -48,17 +53,17 @@ If _system_ is NULL, then all systems are searched and any event within a system that matches _event_ is enabled. Both _system_ and _event_ may be regular expressions as defined by *regex*(3). -The _tracefs_event_disable()_ function disables the events that match +The *tracefs_event_disable()* function disables the events that match the _system_ and _event_ parameters for the given _instance_. What events -are disable follow the same rules as _tracefs_event_enable()_ for matching +are disable follow the same rules as *tracefs_event_enable()* for matching events. That is, if _instance_ is NULL, then the top level tracing directory is used. If both _system_ and _event_ are NULL then all events are disabled for the given _instance_, and so on. -The _tracefs_iterate_raw_events()_ function will read the tracefs raw +The *tracefs_iterate_raw_events()* function will read the tracefs raw data buffers and call the specified _callback_ function for every event it encounters. Events are iterated in sorted order: oldest first. An initialized -_tep_ handler is required (See _tracefs_local_events_(3)). If _instance_ is +_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
@@ -73,19 +78,19 @@ returns non-zero, the iteration stops. RETURN VALUE ------------ -The _tracefs_event_systems()_ and __tracefs_system_events()_ functions return +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. +must be freed with *tracefs_list_free()* API. In case of an error, NULL is returned. -Both _tracefs_event_enable()_ and _tracefs_event_disable()_ return 0 if they found +Both *tracefs_event_enable()* and *tracefs_event_disable()* return 0 if they found any matching events (Note it does not check the previous status of the event. If -_tracefs_event_enable()_ finds an event that is already enabled, and there are no +*tracefs_event_enable()* finds an event that is already enabled, and there are no other errors, then it will return 0). If an error occurs, even if other events were found, it will return -1 and errno will be set. If no errors occur, but no events are found that match the _system_ and _event_ parameters, then -1 is returned and errno is not set. -The _tracefs_iterate_raw_events()_ function returns -1 in case of an error or +The *tracefs_iterate_raw_events()* function returns -1 in case of an error or 0 otherwise. EXAMPLE
Documentation/libtracefs-files.txt +10 -10
@@ -22,17 +22,17 @@ 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 +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 tracefs 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()_. +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_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 +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.
@@ -40,10 +40,10 @@ 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_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 +The *tracefs_tracing_dir()* function returns a constant string or NULL in case of an error. The returned string must _not_ be freed. EXAMPLE
Documentation/libtracefs-filter.txt +6 -6
@@ -12,12 +12,12 @@ SYNOPSIS -- *#include <tracefs.h>* -int tracefs_filter_string_append(struct tep_event pass:[*]event, char pass:[**] filter, - struct tracefs_filter type, const char pass:[*]field, - enum tracefs_synth_compare compare, const char pass:[*]val); -int tracefs_filter_string_verify(struct tep_event pass:[*]event, const char pass:[*]filter, char pass:[**]err); -int tracefs_event_filter_apply(struct tracefs_instance pass:[*]instance, struct tep_event pass:[*]event, const char pass:[*]filter); -int tracefs_event_filter_clear(struct tracefs_instance pass:[*]instance, struct tep_event pass:[*]event); +int *tracefs_filter_string_append*(struct tep_event pass:[*]_event_, char pass:[**]_filter_, + struct tracefs_filter _type_, const char pass:[*]_field_, + enum tracefs_synth_compare _compare_, const char pass:[*]_val_); +int *tracefs_filter_string_verify*(struct tep_event pass:[*]_event_, const char pass:[*]_filter_, char pass:[**]_err_); +int *tracefs_event_filter_apply*(struct tracefs_instance pass:[*]_instance_, struct tep_event pass:[*]_event_, const char pass:[*]_filter_); +int *tracefs_event_filter_clear*(struct tracefs_instance pass:[*]_instance_, struct tep_event pass:[*]_event_); --
Documentation/libtracefs-function-filter.txt +4 -4
@@ -94,19 +94,19 @@ regular expression. RETURN VALUE ------------ -For _tracefs_function_filter_() and _tracefs_function_notrace()_ a +For *tracefs_function_filter()* and *tracefs_function_notrace()* a return of 0 means success. If the there is an error but the filtering was not started, then 1 is returned. If filtering was started but an error occurs, then -1 is returned. The state of the filtering may be in an unknown state. If *TRACEFS_FL_CONTINUE* was set, and 0 or -1 was returned, then another call -to tracefs_function_filter() must be done without *TRACEFS_FL_CONTINUE* set +to *tracefs_function_filter()* must be done without *TRACEFS_FL_CONTINUE* set in order to commit (and close) the filtering. -For _tracefs_filter_functions_(), a return of 0 means success, and the _list_ +For *tracefs_filter_functions()*, a return of 0 means success, and the _list_ parameter is filled with a list of function names that matched _filter_ and _module_. _list_ is a string array, where the last string pointer in the -array is NULL. The _list_ must be freed with _tracefs_list_free()_. +array is NULL. The _list_ must be freed with *tracefs_list_free()*. On failure, a negative is returned, and _list_ is ignored. ERRORS
Documentation/libtracefs-hist-cont.txt +10 -10
@@ -11,34 +11,34 @@ SYNOPSIS -- *#include <tracefs.h>* -int tracefs_hist_start(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist); -int tracefs_hist_destory(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist); -int tracefs_hist_pause(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist); -int tracefs_hist_continue(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist); -int tracefs_hist_reset(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist); +int *tracefs_hist_start*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); +int *tracefs_hist_destroy*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); +int *tracefs_hist_pause*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); +int *tracefs_hist_continue*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); +int *tracefs_hist_reset*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); -- DESCRIPTION ----------- -*tracefs_hist_start* is called to actually start the histogram _hist_. +*tracefs_hist_start()* is called to actually start the histogram _hist_. The _instance_ is the instance to start the histogram in, NULL if it should start at the top level. -*tracefs_hist_pause* is called to pause the histogram _hist_. +*tracefs_hist_pause()* is called to pause the histogram _hist_. The _instance_ is the instance to pause the histogram in, NULL if it is in the top level. -*tracefs_hist_continue* is called to continue a paused histogram _hist_. +*tracefs_hist_continue()* is called to continue a paused histogram _hist_. The _instance_ is the instance to continue the histogram, NULL if it is in the top level. -*tracefs_hist_reset* is called to clear / reset the histogram _hist_. +*tracefs_hist_reset()* is called to clear / reset the histogram _hist_. The _instance_ is the instance to clear the histogram, NULL if it is in the top level. -*tracefs_hist_destory* is called to delete the histogram where it will no longer +*tracefs_hist_destroy()* is called to delete the histogram where it will no longer exist. The _instance_ is the instance to delete the histogram from, NULL if it is in the top level.
Documentation/libtracefs-hist.txt +63 -64
212 lines not on this page · raw message
Documentation/libtracefs-instances-affinity.txt +7 -7
@@ -12,9 +12,9 @@ SYNOPSIS -- *#include <tracefs.h>* -int tracefs_instance_set_affinity(struct tracefs_instace pass:[*]_instance_, const char pass:[*]_cpu_str_); -int tracefs_instance_set_affinity_set(struct tracefs_instace pass:[*]_instance_, cpu_set_t pass:[*]_set_, size_t _set_size_); -int tracefs_instance_set_affinity_raw(struct tracefs_instace pass:[*]_instance_, const char pass:[*]_mask_); +int *tracefs_instance_set_affinity*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_cpu_str_); +int *tracefs_instance_set_affinity_set*(struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_set_, size_t _set_size_); +int *tracefs_instance_set_affinity_raw*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_mask_); --
@@ -24,9 +24,9 @@ These functions set the CPU affinity that limits what CPUs will have tracing ena for a given instance defined by the _instance_ parameter. If _instance_ is NULL, then the top level instance is affected. -The _tracefs_instance_set_affinity()_ function takes a string _cpu_str_ that is a +The *tracefs_instance_set_affinity()* function takes a string _cpu_str_ that is a list of CPUs to set the affinity for. If _cpu_str_ is NULL, then all the CPUs in -the system will be set. The format of _cpu_str_ is a comma deliminated string of +the system will be set. The format of _cpu_str_ is a comma delimited string of decimal numbers with no spaces. A range may be specified by a hyphen. For example: "1,4,6-8"
@@ -34,12 +34,12 @@ For example: "1,4,6-8" The numbers do not need to be in order except for ranges, where the second number must be equal to or greater than the first. -The _tracefs_instance_set_affinity_set()_ function takes a CPU set defined by +The *tracefs_instance_set_affinity_set()* function takes a CPU set defined by *CPU_SET(3)*. The size of the set defined by _set_size_ is the size in bytes of _set_. If _set_ is NULL then all the CPUs on the system will be set, and _set_size_ is ignored. -The _tracefs_instance_set_affinity_raw()_ function takes a string that holds +The *tracefs_instance_set_affinity_raw()* function takes a string that holds a hexidecimal bitmask, where each 32 bits is separated by a comma. For a machine with more that 32 CPUs, to set CPUS 1-10 and CPU 40:
Documentation/libtracefs-instances-file-manip.txt +13 -13
@@ -30,47 +30,47 @@ 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_instance_file_open()_ function opens trace _file_ from given _instance_ and returns +The *tracefs_instance_file_open()* function opens trace _file_ from given _instance_ and returns a file descriptor to it. The file access _mode_ can be specified, see *open*(3) for more details. If -1 is passed as _mode_, default O_RDWR is used. -The _tracefs_instance_file_write()_ function writes a string _str_ in a _file_ from +The *tracefs_instance_file_write()* function writes a string _str_ in a _file_ from the given _instance_, without the terminating NULL character. When opening the file, this function tries to truncates the size of the file to zero, which clears all previously existing settings. -The _tracefs_instance_file_append()_ function writes a string _str_ in a _file_ from +The *tracefs_instance_file_append()* function writes a string _str_ in a _file_ from the given _instance_, without the terminating NULL character. This function is similar to -_tracefs_instance_file_write()_, but the existing content of the is not cleared. Thus the +*tracefs_instance_file_write()*, but the existing content of the is not cleared. Thus the new settings are appended to the existing ones (if any). -The _tracefs_instance_file_clear()_ function tries to truncates the size of the file to zero, +The *tracefs_instance_file_clear()* function tries to truncates the size of the file to zero, which clears all previously existing settings. If the file has content that does not get cleared in this way, this will not have any effect. -The _tracefs_instance_file_read()_ function reads the content of a _file_ from +The *tracefs_instance_file_read()* function reads the content of a _file_ from the given _instance_. -The _tracefs_instance_file_read_number()_ function reads the content of a _file_ from +The *tracefs_instance_file_read_number()* function reads the content of a _file_ from the given _instance_ and converts it to a long long integer, which is stored in _res_. RETURN VALUE ------------ -The _tracefs_instance_file_open()_ function returns a file descriptor to the opened file. It must be +The *tracefs_instance_file_open()* function returns a file descriptor to the opened file. It must be closed with *close*(3). In case of an error, -1 is returned. -The _tracefs_instance_file_write()_ function returns the number of written bytes, +The *tracefs_instance_file_write()* function returns the number of written bytes, or -1 in case of an error. -The _tracefs_instance_file_append()_ function returns the number of written bytes, +The *tracefs_instance_file_append()* function returns the number of written bytes, or -1 in case of an error. -The _tracefs_instance_file_clear()_ function returns 0 on success, or -1 in case of an error. +The *tracefs_instance_file_clear()* function returns 0 on success, or -1 in case of an error. -The _tracefs_instance_file_read()_ function returns a pointer to a NULL terminated +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(). -The _tracefs_instance_file_read_number()_ function returns 0 if a valid integer is read from +The *tracefs_instance_file_read_number()* function returns 0 if a valid integer is read from the file and stored in _res_ or -1 in case of an error. EXAMPLE
Documentation/libtracefs-instances-files.txt +7 -7
@@ -26,26 +26,26 @@ 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_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_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 +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 +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. RETURN VALUE ------------ -The _tracefs_file_exists()_ and _tracefs_dir_exists()_ functions return true if the +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 +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()_. +*tracefs_put_tracing_file()*. EXAMPLE -------
Documentation/libtracefs-instances-manage.txt +14 -14
@@ -28,45 +28,45 @@ 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 +The *tracefs_instance_create()* function allocates and initializes a new tracefs_instance structure and returns it. If the instance with _name_ does not yet exist in the system, it will be created. The _name_ could be NULL, -then the new tracefs_instance structure is initialised for the top instance. +then the new tracefs_instance structure is initialized for the top instance. Note that the top instance cannot be created in the system, if it does not exist. -The _tracefs_instance_destroy()_ removes the instance from the system, but -does not free the structure. _tracefs_instance_free()__ must still be called +The *tracefs_instance_destroy()* removes the instance from the system, but +does not free the structure. *tracefs_instance_free()* must still be called on _instance_. -The _tracefs_instance_alloc()_ function allocates a new tracefs_instance structure +The tracefs_instance_alloc()* function allocates a new tracefs_instance structure for existing trace instance. If the instance does not exist in the system, the function fails. The _tracing_dir_ parameter points to the system trace directory. It can be NULL, then default system trace directory is used. This parameter is useful to allocate instances to trace directories, copied from another machine. The _name_ is the name of the instance, or NULL for the top instance in the given _tracing_dir_. -The _tracefs_instance_free()_ function frees the tracefs_instance structure, +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 +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()_ and _tracefs_instance_alloc()_ functions return a pointer to -a newly allocated tracefs_instance structure. It must be freed with _tracefs_instance_free()_. +The *tracefs_instance_create()* and *tracefs_instance_alloc()* functions return a pointer to +a newly allocated tracefs_instance structure. It must be freed with *tracefs_instance_free()*. -The _tracefs_instance_destroy()_ function returns 0 if it succeeds to remove +The *tracefs_instance_destroy()* function returns 0 if it succeeds to remove the instance, otherwise it returns -1 if the instance does not exist or it fails to remove it. -The _tracefs_instance_is_new()_ function returns true if the -_tracefs_instance_create()_ that allocated _instance_ also created the +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()_ or _tracefs_instance_alloc()_. +*tracefs_instance_create()* or *tracefs_instance_alloc()*. EXAMPLE -------
Documentation/libtracefs-instances-utils.txt +8 -8
@@ -24,33 +24,33 @@ DESCRIPTION ----------- Helper functions for working with trace instances. -The _tracefs_instance_get_name()_ function returns the name of the given _instance_. +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_instance_get_trace_dir()_ function returns the tracing directory, where +The *tracefs_instance_get_trace_dir()* function returns the tracing directory, where the given _instance_ is configured. -The _tracefs_instances_walk()_ function walks through all configured tracing +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 +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 +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_instance_get_trace_dir()_ returns a string or NULL in case of an error. +The *tracefs_instance_get_trace_dir()* returns a string or NULL in case of an error. The returned string must _not_ be freed. -The _tracefs_instances_walk()_ function returns 0, if all instances were iterated, 1 +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 +The *tracefs_instance_exists()* returns true if an instance with the given _name_ exists in the system or false otherwise. EXAMPLE
Documentation/libtracefs-log.txt +2 -2
@@ -16,8 +16,8 @@ int *tracefs_set_loglevel*(enum tep_loglevel _level_); DESCRIPTION ----------- -The _tracefs_set_loglevel()_ function sets the level of the library logs that will be printed on -the console. See _libtraceevent(3)_ for detailed desciription of the log levels. Setting the log +The *tracefs_set_loglevel()* function sets the level of the library logs that will be printed on +the console. See _libtraceevent(3)_ for detailed description of the log levels. Setting the log level to specific value means that logs from the previous levels will be printed too. For example _TEP_LOG_WARNING_ will print any logs with severity _TEP_LOG_WARNING_, _TEP_LOG_ERROR_ and _TEP_LOG_CRITICAL_. The default log level is _TEP_LOG_CRITICAL_. When a new level is set, it is
Documentation/libtracefs-marker.txt +6 -6
@@ -26,23 +26,23 @@ See Documentation/trace/ftrace.rst from the Linux kernel tree for more informati data from user space in the trace buffer. All these APIs have _instance_ as a first argument. If NULL is passed as _instance_, the top trace instance is used. -The _tracefs_print_init()_ function initializes the library for writing into the trace buffer of +The *tracefs_print_init()* function initializes the library for writing into the trace buffer of the selected _instance_. It is not mandatory to call this API before writing strings, any of the printf APIs will call it automatically, if the library is not yet initialized. But calling -_tracefs_print_init()_ in advance will speed up the writing. +*tracefs_print_init()* in advance will speed up the writing. -The _tracefs_printf()_ function writes a formatted string in the trace buffer of the selected +The *tracefs_printf()* function writes a formatted string in the trace buffer of the selected _instance_. The _fmt_ argument is a string in printf format, followed by variable arguments _..._. -The _tracefs_vprintf()_ function writes a formatted string in the trace buffer of the selected +The *tracefs_vprintf()* function writes a formatted string in the trace buffer of the selected _instance_. The _fmt_ argument is a string in printf format, followed by list _ap_ of arguments. -The _tracefs_print_close()_ function closes the resources, used by the library for writing in +The *tracefs_print_close()* function closes the resources, used by the library for writing in the trace buffer of the selected instance. RETURN VALUE ------------ -The _tracefs_print_init()_, _tracefs_printf()_, and _tracefs_vprintf()_ functions return 0 if +The *tracefs_print_init()*, *tracefs_printf()*, and *tracefs_vprintf()* functions return 0 if the operation is successful, or -1 in case of an error. EXAMPLE
Documentation/libtracefs-marker_raw.txt +6 -6
@@ -25,21 +25,21 @@ See Documentation/trace/ftrace.rst from the Linux kernel tree for more informati data from user space in the trace buffer. All these APIs have _instance_ as a first argument. If NULL is passed as _instance_, the top trace instance is used. -The _tracefs_binary_init()_ function initializes the library for writing into the trace buffer of +The *tracefs_binary_init()* function initializes the library for writing into the trace buffer of the selected _instance_. It is not mandatory to call this API before writing data, the -_tracefs_binary_write()_ will call it automatically, if the library is not yet initialized. -But calling _tracefs_binary_init()_ in advance will speed up the writing. +*tracefs_binary_write()* will call it automatically, if the library is not yet initialized. +But calling *tracefs_binary_init()* in advance will speed up the writing. -The _tracefs_binary_write()_ function writes a binary data in the trace buffer of the selected +The *tracefs_binary_write()* function writes a binary data in the trace buffer of the selected _instance_. The _data_ points to the data with length _len_, that is going to be written in the trace buffer. -The _tracefs_binary_close()_ function closes the resources, used by the library for writing in +The *tracefs_binary_close()* function closes the resources, used by the library for writing in the trace buffer of the selected instance. RETURN VALUE ------------ -The _tracefs_binary_init()_, and _tracefs_binary_write()_ functions return 0 if the operation is +The *tracefs_binary_init()*, and *tracefs_binary_write()* functions return 0 if the operation is successful, or -1 in case of an error. EXAMPLE
Documentation/libtracefs-option-get.txt +9 -9
@@ -25,35 +25,35 @@ DESCRIPTION This set of APIs can be used to get and check current ftrace options. Supported ftrace options may depend on the kernel version and the kernel configuration. -The _tracefs_options_get_supported()_ function gets all ftrace options supported by the system in +The *tracefs_options_get_supported()* function gets all ftrace options supported by the system in the given _instance_. If _instance_ is NULL, supported options of the top trace instance are returned. The set of supported options is the same in all created trace instances, but may be different than the top trace instance. -The _tracefs_option_is_supported()_ function checks if the option with given _id_ is supported by +The *tracefs_option_is_supported()/ function checks if the option with given _id_ is supported by the system in the given _instance_. If _instance_ is NULL, the top trace instance is used. If an option is supported at the top trace instance, it it may not be supported in a created trace instance. -The _tracefs_options_get_enabled()_ function gets all ftrace options, currently enabled in +The *tracefs_options_get_enabled()* function gets all ftrace options, currently enabled in the given _instance_. If _instance_ is NULL, enabled options of the top trace instance are returned. -The _tracefs_option_is_enabled()_ function checks if the option with given _id_ is enabled in the +The *tracefs_option_is_enabled()* function checks if the option with given _id_ is enabled in the given _instance_. If _instance_ is NULL, the top trace instance is used. -The _tracefs_option_mask_is_set()_ function checks if the bit, corresponding to the option with _id_ is -set in the _options_ bitmask returned from _tracefs_option_get_enabled()_ and _tracefs_option_is_supported()_. +The *tracefs_option_mask_is_set()* function checks if the bit, corresponding to the option with _id_ is +set in the _options_ bitmask returned from *tracefs_option_get_enabled()* and *tracefs_option_is_supported()*. RETURN VALUE ------------ -The _tracefs_options_get_supported()_ and _tracefs_options_get_enabled()_ functions, on success, +The *tracefs_options_get_supported()* and *tracefs_options_get_enabled()* functions, on success, return a pointer to the bitmask within the instance, or a global bitmask for the top level, or NULL in case of an error. As the returned bitmask is part of the instance structure (or a global variable) and must not be freed or modified. -The _tracefs_option_is_supported()_ and _tracefs_option_is_enabled()_ functions return true if the +The *tracefs_option_is_supported()* and *tracefs_option_is_enabled()* functions return true if the option in supported / enabled, or false otherwise. -The _tracefs_option_mask_is_set()_ returns true if the corresponding option is set in the mask +The *tracefs_option_mask_is_set()* returns true if the corresponding option is set in the mask or false otherwise. EXAMPLE
Documentation/libtracefs-option-misc.txt +5 -5
@@ -21,22 +21,22 @@ DESCRIPTION ----------- This set of APIs can be used to enable and disable ftrace options and to get the name of an option. -The _tracefs_option_enable()_ function enables the option with _id_ in the given _instance_. If +The *tracefs_option_enable()* function enables the option with _id_ in the given _instance_. If _instance_ is NULL, the option is enabled in the top trace instance. -The _tracefs_option_disable()_ function disables the option with _id_ in the given _instance_. If +The *tracefs_option_disable()* function disables the option with _id_ in the given _instance_. If _instance_ is NULL, the option is disabled in the top trace instance. -The _tracefs_option_name()_ function returns a string, representing the option with _id_. The string +The *tracefs_option_name()* function returns a string, representing the option with _id_. The string must *not* be freed. RETURN VALUE ------------ -The _tracefs_option_enable()_ and _tracefs_option_disable()_ functions return 0 if the state of the +The *tracefs_option_enable()* and *tracefs_option_disable()* functions return 0 if the state of the option is set successfully, or -1 in case of an error. -The _tracefs_option_name()_ function returns string with option name, or "unknown" in case of an +The *tracefs_option_name()* function returns string with option name, or "unknown" in case of an error. The returned string must *not* be freed. EXAMPLE
Documentation/libtracefs-sql.txt +4 -4
@@ -3,7 +3,7 @@ libtracefs(3) NAME ---- -tracefs_sql - Create a synthetitc event via an SQL statement +tracefs_sql - Create a synthetic event via an SQL statement SYNOPSIS --------
@@ -11,8 +11,8 @@ SYNOPSIS -- *#include <tracefs.h>* -struct tracefs_synth *tracefs_sql(struct tep_handle pass:[*]tep, const char pass:[*]name, - const char pass:[*]sql_buffer, char pass:[**]err); +struct tracefs_synth pass:[*]*tracefs_sql*(struct tep_handle pass:[*]_tep_, const char pass:[*]_name_, + const char pass:[*]_sql_buffer_, char pass:[**]_err_); -- DESCRIPTION
@@ -35,7 +35,7 @@ be created from two different events. For simple SQL queries to make a histogram instead of a synthetic event, see HISTOGRAMS below. -*tracefs_sql*() takes in a *tep* handler (See _tep_local_events_(3)) that is used to +*tracefs_sql*() takes in a _tep_ handler (See _tep_local_events_(3)) that is used to verify the events within the _sql_buffer_ expression. The _name_ is the name of the synthetic event to create. If _err_ points to an address of a string, it will be filled with a detailed message on any type of parsing error, including fields that do not belong
Documentation/libtracefs-stream.txt +7 -7
@@ -12,9 +12,9 @@ SYNOPSIS -- *#include <tracefs.h>* -ssize_t tracefs_trace_pipe_stream(int fd, struct tracefs_instance *instance, int flags); -ssize_t tracefs_trace_pipe_print(struct tracefs_instance *instance, int flags); -void tracefs_trace_pipe_stop(struct tracefs_instance *instance); +ssize_t *tracefs_trace_pipe_stream*(int _fd_, struct tracefs_instance pass:[*]_instance_, int _flags_); +ssize_t *tracefs_trace_pipe_print*(struct tracefs_instance pass:[*]_instance_, int _flags_); +void *tracefs_trace_pipe_stop*(struct tracefs_instance pass:[*]_instance_); --
@@ -23,24 +23,24 @@ DESCRIPTION ----------- If NULL is passed as _instance_, the top trace instance is used. -The reading of the trace_pipe file can be stopped by calling tracefs_trace_pipe_stop() +The reading of the trace_pipe file can be stopped by calling *tracefs_trace_pipe_stop()* which could be placed in a signal handler in case the application wants to stop the reading, for example, with the user pressing Ctrl-C. -The _tracefs_trace_pipe_stream()_ function redirects the stream of trace data to an output +The *tracefs_trace_pipe_stream()* function redirects the stream of trace data to an output file. The "splice" system call is used to moves the data without copying between kernel address space and user address space. The _fd_ is the file descriptor of the output file and _flags_ is a bit mask of flags to be passed to the open system call of the trace_pipe file (see ). If flags contain O_NONBLOCK, then that is also passed to the splice calls that may read the file to the output stream file descriptor. -The _tracefs_trace_pipe_print()_ function is similar to _tracefs_trace_pipe_stream()_, but +The *tracefs_trace_pipe_print()* function is similar to *tracefs_trace_pipe_stream()*, but the stream of trace data is redirected to stdout. RETURN VALUE ------------ -The _tracefs_trace_pipe_stream()_, and _tracefs_trace_pipe_print()_ functions return the +The *tracefs_trace_pipe_stream()*, and *tracefs_trace_pipe_print()* functions return the number of bytes transfered if the operation is successful, or -1 in case of an error. EXAMPLE
Documentation/libtracefs-synth.txt +42 -42
128 lines not on this page · raw message
Documentation/libtracefs-synth2.txt +29 -26
88 lines not on this page · raw message
Documentation/libtracefs-traceon.txt +9 -9
@@ -15,7 +15,7 @@ SYNOPSIS int *tracefs_trace_is_on*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_on*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_off*(struct tracefs_instance pass:[*]_instance_); -int _tracefs_trace_on_get_fd_(struct tracefs_instance pass:[*]_instance_); +int *tracefs_trace_on_get_fd*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_on_fd*(int _fd_); int *tracefs_trace_off_fd*(int _fd_); --
@@ -25,31 +25,31 @@ DESCRIPTION This set of functions can be used to check, enable or disable writing to the ring buffer in the given trace instance. The tracing is enabled when writing to the ring buffer is enabled. -The _tracefs_trace_is_on()_ function checks if tracing is enabled for the given _instance_. If +The *tracefs_trace_is_on()* function checks if tracing is enabled for the given _instance_. If _instance_ is NULL, the top instance is used. -The _tracefs_trace_on()_ and _tracefs_trace_off()_ functions set the tracing in the _instance_ +The *tracefs_trace_on()* and *tracefs_trace_off()* functions set the tracing in the _instance_ to enable or disable state. If _instance_ is NULL, the top instance is used. -The _tracefs_trace_on_get_fd()_ function returns a file deascriptor to the "tracing_on" file from +The *tracefs_trace_on_get_fd()* function returns a file descriptor to the "tracing_on" file from the given _instance_. If _instance_ is NULL, the top trace instance is used. The returned descriptor can be used for fast enabling or disabling the tracing of the instance. -The _tracefs_trace_on_fd()_ and _tracefs_trace_off_fd()_ functions set the tracing state to enable +The *tracefs_trace_on_fd()* and *tracefs_trace_off_fd()* functions set the tracing state to enable or disable using the given _fd_. This file descriptor must be opened for writing with *tracefs_trace_on_get_fd*(3) of the desired trace instance. These functions are faster than *tracefs_trace_on* and *tracefs_trace_off*. RETURN VALUE ------------ -The _tracefs_trace_is_on()_ function returns 0 if tracing is disable, 1 if it is enabled or +The *tracefs_trace_is_on()* function returns 0 if tracing is disable, 1 if it is enabled or -1 in case of an error. -The _tracefs_trace_on_get_fd()_ function returns a file descriptor to "tracing_on" +The *tracefs_trace_on_get_fd()* function returns a file descriptor to "tracing_on" file for reading and writing, which must be closed wuth close(). In case of an error -1 is returned. -The _tracefs_trace_on()_, _tracefs_trace_off()_, _tracefs_trace_on_fd()_ and -_tracefs_trace_off_fd()_ functions return -1 in case of an error or 0 otherwise. +The *tracefs_trace_on()*, *tracefs_trace_off()*, *tracefs_trace_on_fd()* and +*tracefs_trace_off_fd()* functions return -1 in case of an error or 0 otherwise. EXAMPLE -------
Documentation/libtracefs-tracer.txt +2 -2
@@ -20,7 +20,7 @@ DESCRIPTION ----------- *tracefs_tracer_set* enables a tracer in the given instance, defined by the _instance_ parameter. If _instance_ is NULL, then the top level instance is -changed. If _tracer_ is set to _TRACFES_TRACER_CUSTOM_ then a const char pass[*] +changed. If _tracer_ is set to *TRACFES_TRACER_CUSTOM* then a _name_ string must be passed in as the third parameter, and that is written into the instance to enable the tracer with that name. This is useful for newer or custom kernels that contain tracers that are not yet identified by the
@@ -38,7 +38,7 @@ The currently defined enums that are accepted are: *TRACEFS_TRACER_NOP* : This is the idle tracer, which does nothing and is used to clear any -active tarcer. +active tracer. *TRACEFS_TRACER_FUNCTION* : Enables most functions in the kernel to be traced.
Documentation/libtracefs-utils.txt +8 -8
@@ -21,28 +21,28 @@ DESCRIPTION ----------- Various useful functions for working with trace file system. -The _tracefs_tracers()_ function returns array of strings with the +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 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. +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, +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()_ +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. +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 +The *tracefs_get_clock()* returns string, that must be freed with free(), or NULL in case of an error. EXAMPLE
Documentation/libtracefs.txt +1 -1
@@ -48,7 +48,7 @@ Trace helper functions: int *tracefs_trace_is_on*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_on*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_off*(struct tracefs_instance pass:[*]_instance_); - int _tracefs_trace_on_get_fd_(struct tracefs_instance pass:[*]_instance_); + int *tracefs_trace_on_get_fd*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_on_fd*(int _fd_); int *tracefs_trace_off_fd*(int _fd_);
Signature · 1 line
2.34.1
Re: [PATCH 1/2] libtracefs: Unify man pages style
Quoted 7 lines · On Fri, 14 Jan 2022 11:59:49 +0200 "Tzvetomir Stoyanov (VMware)"…
Man pages of the library should have consistent view. There are some differences in functions and arguments visualisation across current man pages. Made the style of all pages consistent:
- all function names in bold
- all arguments are underlined.
Fixed also a few spelling mistakes.
A patch about consistency should be consistent ;-)
Quoted 27 lines
Documentation/libtracefs-hist.txt +3
-11@@ -4,7 +4,7 @@ libtracefs(3) NAME ---- tracefs_hist_alloc, tracefs_hist_free, tracefs_hist_add_key, tracefs_hist_add_value, tracefs_hist_add_name, tracefs_hist_start, -tracefs_hist_destory, tracefs_hist_add_sort_key, tracefs_hist_set_sort_key, tracefs_hist_sort_key_direction +tracefs_hist_destroy, tracefs_hist_add_sort_key, tracefs_hist_set_sort_key, tracefs_hist_sort_key_direction tracefs_hist_echo_cmd, tracefs_hist_get_name, tracefs_hist_get_event, tracefs_hist_get_system - Create, update and describe event histograms SYNOPSIS@@ -13,68 +13,68 @@ SYNOPSIS -- *#include <tracefs.h>* -enum tracefs_hist_key_type { - TRACEFS_HIST_KEY_NORMAL = 0, - TRACEFS_HIST_KEY_HEX, - TRACEFS_HIST_KEY_SYM, - TRACEFS_HIST_KEY_SYM_OFFSET, - TRACEFS_HIST_KEY_SYSCALL, - TRACEFS_HIST_KEY_EXECNAME, - TRACEFS_HIST_KEY_LOG, - TRACEFS_HIST_KEY_USECS, - TRACEFS_HIST_KEY_MAX +enum *tracefs_hist_key_type* { + _TRACEFS_HIST_KEY_NORMAL_ = 0,
Documentation/libtracefs-hist.txt SYNOPSIS · line 27
Quoted 10 lines
Documentation/libtracefs-hist.txt +8
-0+ _TRACEFS_HIST_KEY_HEX_, + _TRACEFS_HIST_KEY_SYM_, + _TRACEFS_HIST_KEY_SYM_OFFSET_, + _TRACEFS_HIST_KEY_SYSCALL_, + _TRACEFS_HIST_KEY_EXECNAME_, + _TRACEFS_HIST_KEY_LOG_, + _TRACEFS_HIST_KEY_USECS_, + _TRACEFS_HIST_KEY_MAX_ };
The above you have enums be underlined.
Quoted 6 lines
Documentation/libtracefs-synth2.txt +0
-0@@ -14,24 +14,24 @@ SYNOPSIS --
Documentation/libtracefs-synth2.txt SYNOPSIS · line 23
Quoted 10 lines
Documentation/libtracefs-synth2.txt +5
-3+[verse] +-- enum tracefs_synth_handler { - TRACEFS_SYNTH_HANDLE_MATCH, - TRACEFS_SYNTH_HANDLE_MAX, - TRACEFS_SYNTH_HANDLE_CHANGE, + *TRACEFS_SYNTH_HANDLE_MATCH*, + *TRACEFS_SYNTH_HANDLE_MAX*, + *TRACEFS_SYNTH_HANDLE_CHANGE*, };
Here they are bold.
Actually, bold is correct.
-- Steve
PATCH 2/2 libtracefs: Update main man page
In reply to Tzvetomir Stoyanov (VMware)All API functions of the library should be listed in the main man page, "man libtracefs". Some of the newly added APIs are missing there, updated the list.
--- Documentation/libtracefs.txt | 138 ++++++++++++++++++++++++++++++++++- 1 file changed, 137 insertions(+), 1 deletion(-)
Documentation/libtracefs.txt +137 -1
@@ -32,6 +32,9 @@ Trace instances: 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_); + int *tracefs_instance_set_affinity*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_cpu_str_); + int *tracefs_instance_set_affinity_set*(struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_set_, size_t _set_size_); + int *tracefs_instance_set_affinity_raw*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_mask_); Trace events: char pass:[*]pass:[*]*tracefs_event_systems*(const char pass:[*]_tracing_dir_);
@@ -41,9 +44,21 @@ Trace events: 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_); +Event filters: + int *tracefs_filter_string_append*(struct tep_event pass:[*]_event_, char pass:[**]_filter_, + struct tracefs_filter _type_, const char pass:[*]_field_, + enum tracefs_synth_compare _compare_, const char pass:[*]_val_); + int *tracefs_filter_string_verify*(struct tep_event pass:[*]_event_, const char pass:[*]_filter_, char pass:[**]_err_); + int *tracefs_event_filter_apply*(struct tracefs_instance pass:[*]_instance_, struct tep_event pass:[*]_event_, const char pass:[*]_filter_); + int *tracefs_event_filter_clear*(struct tracefs_instance pass:[*]_instance_, struct tep_event pass:[*]_event_); + +Function filters: + int *tracefs_function_filter*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_filter_, const char pass:[*]_module_, int _flags_); + int *tracefs_function_notrace*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_filter_, const char pass:[*]_module_, int _flags_); + int *tracefs_filter_functions*(const char pass:[*]_filter_, const char pass:[*]_module_, char pass:[*]pass:[*]pass:[*]_list_); + Trace helper functions: void *tracefs_list_free*(char pass:[*]pass:[*]_list_); - char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_is_on*(struct tracefs_instance pass:[*]_instance_); int *tracefs_trace_on*(struct tracefs_instance pass:[*]_instance_);
@@ -52,6 +67,22 @@ Trace helper functions: int *tracefs_trace_on_fd*(int _fd_); int *tracefs_trace_off_fd*(int _fd_); +Trace options: + const struct tracefs_options_mask pass:[*]*tracefs_options_get_supported*(struct tracefs_instance pass:[*]_instance_); + bool *tracefs_option_is_supported*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_); + const struct tracefs_options_mask pass:[*]*tracefs_options_get_enabled*(struct tracefs_instance pass:[*]_instance_); + bool *tracefs_option_is_enabled*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_); + bool *tracefs_option_mask_is_set*(const struct tracefs_options_mask *options, enum tracefs_option_id id); + int *tracefs_option_enable*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_); + int *tracefs_option_disable*(struct tracefs_instance pass:[*]_instance_, enum tracefs_option_id _id_); + const char pass:[*]*tracefs_option_name*(enum tracefs_option_id _id_); + +Ftrace tracers: + char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_); + int *tracefs_tracer_set*(struct tracefs_instance pass:[*]_instance_, enum tracefs_tracers _tracer_); + int *tracefs_tracer_set*(struct tracefs_instance pass:[*]_instance_, enum tracefs_tracers _tracer_, const char pass:[*]_name_); + int *tracefs_tracer_clear*(struct tracefs_instance pass:[*]_instance_); + Writing data in the trace buffer: int *tracefs_print_init*(struct tracefs_instance pass:[*]_instance_); int *tracefs_printf*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_fmt_, _..._);
@@ -83,6 +114,111 @@ Kprobes and Kretprobes: struct tracefs_dynevent pass:[*] *tracefs_kretprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_, const char pass:[*]_addr_, const char pass:[*]_format_, unsigned int _max_); int *tracefs_kprobe_raw*(const char pass:[*]_system_, const char pass:[*]_event_, const char pass:[*]_addr_, const char pass:[*]_format_); int *tracefs_kretprobe_raw*(const char pass:[*]_system_, const char pass:[*]_event_, const char pass:[*]_addr_, const char pass:[*]_format_); + +Synthetic events: + struct tracefs_synth pass:[*]*tracefs_sql*(struct tep_handle pass:[*]_tep_, const char pass:[*]_name_, + const char pass:[*]_sql_buffer_, char pass:[**]_err_); + struct tracefs_synth pass:[*]*tracefs_synth_alloc*(struct tep_handle pass:[*]_tep_, + const char pass:[*]_name_, + const char pass:[*]_start_system_, + const char pass:[*]_start_event_, + const char pass:[*]_end_system_, + const char pass:[*]_end_event_, + const char pass:[*]_start_match_field_, + const char pass:[*]_end_match_field_, + const char pass:[*]_match_name_); + int *tracefs_synth_add_match_field*(struct tracefs_synth pass:[*]_synth_, + const char pass:[*]_start_match_field_, + const char pass:[*]_end_match_field_, + const char pass:[*]_name_); + int *tracefs_synth_add_compare_field*(struct tracefs_synth pass:[*]_synth_, + const char pass:[*]_start_compare_field_, + const char pass:[*]_end_compare_field_, + enum tracefs_synth_calc _calc_, + const char pass:[*]_name_); + int *tracefs_synth_add_start_field*(struct tracefs_synth pass:[*]_synth_, + const char pass:[*]_start_field_, + const char pass:[*]_name_); + int *tracefs_synth_add_end_field*(struct tracefs_synth pass:[*]_synth_, + const char pass:[*]_end_field_, + const char pass:[*]_name_); + int *tracefs_synth_append_start_filter*(struct tracefs_synth pass:[*]_synth_, + struct tracefs_filter _type_, + const char pass:[*]_field_, + enum tracefs_synth_compare _compare_, + const char pass:[*]_val_); + int *tracefs_synth_append_end_filter*(struct tracefs_synth pass:[*]_synth_, + struct tracefs_filter _type_, + const char pass:[*]_field_, + enum tracefs_synth_compare _compare_, + const char pass:[*]_val_); + void *tracefs_synth_free*(struct tracefs_synth pass:[*]_synth_); + int *tracefs_synth_create*(struct tracefs_synth pass:[*]_synth_); + int *tracefs_synth_destroy*(struct tracefs_synth pass:[*]_synth_); + int *tracefs_synth_echo_cmd*(struct trace_seq pass:[*]_seq_, struct tracefs_synth pass:[*]_synth_); + bool *tracefs_synth_complete*(struct tracefs_synth pass:[*]_synth_); + struct tracefs_hist pass:[*]*tracefs_synth_get_start_hist*(struct tracefs_synth pass:[*]_synth_); + int *tracefs_synth_trace*(struct tracefs_synth pass:[*]_synth_, + enum tracefs_synth_handler _type_, const char pass:[*]_var_); + int *tracefs_synth_snapshot*(struct tracefs_synth pass:[*]_synth_, + enum tracefs_synth_handler _type_, const char pass:[*]_var_); + int *tracefs_synth_save*(struct tracefs_synth pass:[*]_synth_, + enum tracefs_synth_handler _type_, const char pass:[*]_var_, + char pass:[**]_save_fields_); + const char pass:[*]*tracefs_synth_get_name*(struct tracefs_synth pass:[*]_synth_); + int *tracefs_synth_raw_fmt*(struct trace_seq pass:[*]_seq_, struct tracefs_synth pass:[*]_synth_); + const char pass:[*]*tracefs_synth_show_event*(struct tracefs_synth pass:[*]_synth_); + const char pass:[*]*tracefs_synth_show_start_hist*(struct tracefs_synth pass:[*]_synth_); + const char pass:[*]*tracefs_synth_show_end_hist*(struct tracefs_synth pass:[*]_synth_); + +Ftrace errors reporting: + char pass:[*]*tracefs_error_last*(struct tracefs_instance pass:[*]_instance_); + char pass:[*]*tracefs_error_all*(struct tracefs_instance pass:[*]_instance_); + int *tracefs_error_clear*(struct tracefs_instance pass:[*]_instance_); + +Histograms: + struct tracefs_hist pass:[*]*tracefs_hist_alloc*(struct tracefs_tep pass:[*] _tep_, + const char pass:[*]_system_, const char pass:[*]_event_, + const char pass:[*]_key_, enum tracefs_hist_key_type _type_); + struct tracefs_hist pass:[*]*tracefs_hist_alloc_2d*(struct tracefs_tep pass:[*] _tep_, + const char pass:[*]_system_, const char pass:[*]_event_, + const char pass:[*]_key1_, enum tracefs_hist_key_type _type1_, + const char pass:[*]_key2_, enum tracefs_hist_key_type _type2_)); + struct tracefs_hist pass:[*]*tracefs_hist_alloc_nd*(struct tracefs_tep pass:[*] _tep_, + const char pass:[*]_system_, const char pass:[*]_event_, + struct tracefs_hist_axis pass:[*]_axes_); + void *tracefs_hist_free*(struct tracefs_hist pass:[*]_hist_); + int *tracefs_hist_add_key*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_key_, + enum tracefs_hist_key_type _type_); + int *tracefs_hist_add_value*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_value_); + int *tracefs_hist_add_sort_key*(struct tracefs_hist pass:[*]_hist_, + const char pass:[*]_sort_key_); + int *tracefs_hist_set_sort_key*(struct tracefs_hist pass:[*]_hist_, + const char pass:[*]_sort_key_, _..._); + int *tracefs_hist_sort_key_direction*(struct tracefs_hist pass:[*]_hist_, + const char pass:[*]_sort_key_, + enum tracefs_hist_sort_direction _dir_); + int *tracefs_hist_add_name*(struct tracefs_hist pass:[*]_hist_, const char pass:[*]_name_); + int *tracefs_hist_append_filter*(struct tracefs_hist pass:[*]_hist_, + enum tracefs_filter _type_, + const char pass:[*]_field_, + enum tracefs_compare _compare_, + const char pass:[*]_val_); + int *tracefs_hist_echo_cmd*(struct trace_seq pass:[*]_s_, struct tracefs_instance pass:[*]_instance_, + struct tracefs_hist pass:[*]_hist_, + enum tracefs_hist_command _command_); + int *tracefs_hist_command*(struct tracefs_instance pass:[*]_instance_, + struct tracefs_hist pass:[*]_hist_, + enum tracefs_hist_command _command_); + const char pass:[*]*tracefs_hist_get_name*(struct tracefs_hist pass:[*]_hist_); + const char pass:[*]*tracefs_hist_get_event*(struct tracefs_hist pass:[*]_hist_); + const char pass:[*]*tracefs_hist_get_system*(struct tracefs_hist pass:[*]_hist_); + int *tracefs_hist_start*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); + int *tracefs_hist_destroy*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); + int *tracefs_hist_pause*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); + int *tracefs_hist_continue*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); + int *tracefs_hist_reset*(struct tracefs_instance pass:[*]_instance_, struct tracefs_hist pass:[*]_hist_); + -- DESCRIPTION
Signature · 1 line
2.34.1
Re: [PATCH 2/2] libtracefs: Update main man page
Quoted 6 lines · On Fri, 14 Jan 2022 11:59:50 +0200 "Tzvetomir Stoyanov (VMware)"…
All API functions of the library should be listed in the main man page, "man libtracefs". Some of the newly added APIs are missing there, updated the list.
Signed-off-by Tzvetomir Stoyanov (VMware) <[email protected]>---
I took this patch and pushed it up.
-- Steve