From: "Steven Rostedt (Google)" <rostedt@xxxxxxxxxxx> Add man pages for: traceeval_delta_insert() traceeval_delta_insert_size() traceeval_delta_remove() traceeval_delta_remove_size() traceeval_delta_query() traceeval_delta_query_size() traceeval_delta_results_release() Signed-off-by: Steven Rostedt (Google) <rostedt@xxxxxxxxxxx> --- Documentation/libtraceeval-delta-insert.txt | 122 ++++++++++++++++++++ Documentation/libtraceeval.txt | 22 ++++ 2 files changed, 144 insertions(+) create mode 100644 Documentation/libtraceeval-delta-insert.txt diff --git a/Documentation/libtraceeval-delta-insert.txt b/Documentation/libtraceeval-delta-insert.txt new file mode 100644 index 000000000000..23ef6b201fe9 --- /dev/null +++ b/Documentation/libtraceeval-delta-insert.txt @@ -0,0 +1,122 @@ +libtraceeval(3) +=============== + +NAME +---- +traceeval_delta_insert, traceeval_delta_insert_size, traceeval_delta_remove, +traceeval_delta_remove_size, traceeval_delta_query, traceeval_delta_query_size, +traceeval_delta_results_release - Insert, remove, query traceeval delta elements + +SYNOPSIS +-------- +[verse] +-- +*#include <traceeval.h>* + + +int *traceeval_delta_insert*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, + const struct traceeval_data pass:[*]_vals_); +int *traceeval_delta_insert_size*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, size_t _nr_keys_, + const struct traceeval_data pass:[*]_vals_, size_t _nr_vals_); + +int *traceeval_delta_remove*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_); +int *traceeval_delta_remove_size*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, size_t _nr_keys_); + +int *traceeval_delta_query*(struct traceeval_delta pass:[*]_tdelta_, const struct traceeval_data pass:[*]_keys_, + const struct traceeval_data pass:[**]_results_); +int *traceeval_delta_query_size*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, + size_t nr_keys, const struct traceeval_data pass:[**]_results_); + +void *traceeval_delta_results_release*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_results_); +-- + +DESCRIPTION +----------- +These functions manipulate the traceeval_delta created by *traceeval_delta_init*(3), +and act very similar to the functions with the similar names for the traceeval +element (see *traceeval_insert*(3)). + + +The *traceveal_delta_insert()* will create a new instance if one does not exist +that matches the _keys_, or it will update an existing one. Note, this will not +modify the timestamp or delta associated with the instance. For new instances +the timestamp and delta will be zero, and for existing ones, they will remain +unchanged. + +Note that the _keys_ and _vals_ for *traceeval_data_insert()* must be static arrays. +If dynamic arrays are required, then use *traceeval_data_insert_size()* that +takes two additional arguments: _nr_keys_ to denote how many _keys_ are there, +and _nr_vals_ for the number of _vals_. + +Use *traceeval_delta_remove()* or *traceeval_delta_remove_size()* to remove +an instance matching the _keys_ from the traceeval_delta. The difference between +the two functions is that *traceeval_delta_remove()* requires _keys_ to be a +static array. + +The *traceeval_delta_query()* will return the element that matches the _keys_. The +_keys_ must be a static array that is the same size as the key types defined by +*traceeval_init()*. If an element is found, it will fill in the _results_ +pointer to point to the content of the values for the given element. The +results must be released with *traceeval_delta_results_release()*. + +The *traceeval_delta_results_release()* will release any necessary resources that a +*traceeval_delta_query()* may have added to return the _results_. + +RETURN VALUE +------------ +The *traceeval_delta_insert()* and *traceeval_delta_insert_size()* return 0 on succes and -1 on error. + +The *traceeval_delta_remove()* and *traceeval_delta_remove_size()* returns 1 if the item was found and removed, +0 if the item was not found, and -1 on an error (like invalid keys). + +The *traceeval_delta_query()* and *traceveal_delta_query_size()* return 1 if the item is found that matches +the _keys_ and _results_ will contain the values of the last values of that time. It will return +0 if not found, and -1 on error (like invalid keys). + + +EXAMPLE +------- +The usage for these functions are the same as the functions with similar names with +traceeval, and referencing those functions will give the same use cases. + +FILES +----- +[verse] +-- +*traceval.h* + Header file to include in order to have access to the library APIs. +*-ltraceeval* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +*libtraceeval*(3), +*traceeval_insert*(3), +*traceeval_insert_size*(3), +*traceeval_remove*(3), +*traceeval_remove_size*(3), +*traceeval_query*(3), +*traceeval_query_size*(3), +*traceeval_results_release*(3) + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@xxxxxxxxxxx>, author of *libtraceeval*. +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@xxxxxxxxxxxxxxx> + +LICENSE +------- +libtraceeval is licensed under MIT. + diff --git a/Documentation/libtraceeval.txt b/Documentation/libtraceeval.txt index 4d23ba0c5928..68fc182f7c46 100644 --- a/Documentation/libtraceeval.txt +++ b/Documentation/libtraceeval.txt @@ -103,6 +103,28 @@ Handling delta times between events: int *traceeval_delta_continue_size*(struct traceeval_delta pass:[*]_tdelta_, const struct traceeval_data pass:[*]keys, size_t _nr_keys_, unsigned long long _timestamp_); + +Handling insertion, deletion and querying of traceeval_delta elements: + int *traceeval_delta_insert*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, + const struct traceeval_data pass:[*]_vals_); + int *traceeval_delta_insert_size*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, size_t _nr_keys_, + const struct traceeval_data pass:[*]_vals_, size_t _nr_vals_); + + int *traceeval_delta_remove*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_); + int *traceeval_delta_remove_size*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, size_t _nr_keys_); + + int *traceeval_delta_query*(struct traceeval_delta pass:[*]_tdelta_, const struct traceeval_data pass:[*]_keys_, + const struct traceeval_data pass:[**]_results_); + int *traceeval_delta_query_size*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_keys_, + size_t nr_keys, const struct traceeval_data pass:[**]_results_); + + void *traceeval_delta_results_release*(struct traceeval_delta pass:[*]_tdelta_, + const struct traceeval_data pass:[*]_results_); -- DESCRIPTION -- 2.40.1
|