trc_find_first, trc_find_next, or trc_compare Subroutine

Purpose

Finds the first, or next, occurrence of the argument, or compares the current entry with the argument.

Library

libtrace.a

Syntax

#include <sys/libtrace.h>

int trc_find_first (handle, argp, ret)
trc_log_handle_t handle;
trc_logsearch_t *argp;
trc_read_t *ret;

int trc_find_next (handle, argp, ret)
trc_log_handle_t handle;
trc_logsearch_t *argp;
trc_read_t *ret;

int trc_compare (handle, argp)
trc_log_handle_t handle;
trc_logsearch_t *argp;

Description

The trc_find_first subroutine finds the first occurrence of the trace log entry matching the argument pointed to by the argp parameter. The trc_find_next subroutine finds the next occurrence of the argument starting from the current position in the log object. If the search argument pointer, argp, is NULL, the argument from the previous search is used. Both the trc_find_first and trc_find_next subroutines return the item found. If the flag field of the handle contains both TRC_MULTI_MERGE and TRC_REMOVE_DUPS, trc_find_first and trc_find_next will consume any duplicate entries of the current event that exist from other trace sources. The number of entries consumed will be returned in the trchi_dupcount or trcri_dupcount variable (depending on whether processed or raw data items, respectively, are requested).

The trc_compare subroutine is used to check the current entry against the argument. No data is read. It is useful when implementing exit criteria, where you need to find entries according to some criteria, but then check for an exit criteria which is not part of the normal search.

Parameters

The search argument consists of three parts, the operator, tls_op, and the left and right sides.

The operator values can be easily identified, because they have the form TLS_OP_.... Operators are split into two categories, leaf and compound operators. Leaf operators are operators that compare the field on the left with the value on the right. Compound operators are used to compare two expressions, (for example) to combined expressions.

Return Values

Upon successful completion, the trc_find_first, trc_find_next, and trc_compare subroutines return 0.

Error Codes

Examples

1. Find the SVC hooks, 101 and 104, for program mypgm.

   {
                     int rv;
                     trc_loghandle_t h;
                     trc_read_t r;
                     trc_logsearch_t t1, t2, t3, t4, t5;
   
                     /* Setup the leaf search arguments. */
                     t1.tls_op = TLS_OP_EQUAL;
                     t1.tls_field = TLS_MATCH_HOOKID;
                     t1.tls_ushortvalue = 0x101;
                     t2.tls_op = TLS_OP_EQUAL;
                     t2.tls_field = TLS_MATCH_HOOKID;
                     t2.tls_ushortvalue = 0x104;
                     t3.tls_op = TLS_OP_EQUAL;
                     t3.tls_field = TLS_MATCH_PROCNAME;
                     t3.tls_strvalue = "mypgm";
                     /* Join the items and form a single search tree. */
                     t4.tls_op = TLS_OP_AND;
                     t4.tls_left = &t1
                     t4.tls_right = &t2
                     t5.tls_op = TLS_OP_AND;
                     t5.tls_left = &t4
                     t5.tls_right = &t3
                     /* Open the default trace log object. */
                     rv = trc_open("", "", TRC_LOGREAD|TRC_LOGPROC, >h);
                     if (rv) {
                             trc_perror(h, rv, "open");
                             return(rv);
                     }
                     /* Do the search. */
                     rv = trc_find_first(h, &t5, &r);
                     if (rv) {
                             trc_perror(h, rv, "find test");
                             return(rv);
                     }
   
                     ...
             }

   Note that subsequent entries matching this search could be returned with the following:

   rv = trc_find_next(h, NULL, &r);

   After a find, trc_find_next can be used to change the search argument without starting the search over. In other words, trc_find_first always starts from the beginning of the file, while trc_find_next starts from the current position in the file, but either one can change the search argument.

2. Find the SVC hooks, 101 and 104, for program mypgm. Use a single argument to search for both hook ids.

   {
                     int rv;
                     trc_loghandle_t h;
                     trc_read_t r;
                     trc_logsearch_t t1, t2, t3;
                     trc_hookset_t hs;
   
                     /* Setup the hook set. */
                     trc_hkemptyset(hs);
                     (void)trc_hkaddset(hs, 0x101);
                     (void)trc_hkaddset(hs, 0x104);
                     /* Setup the leaf search arguments. */
                     t1.tls_op = TLS_OP_EQUAL;
                     t1.tls_field = TLS_MATCH_HOOKSET;
                     t1.tls_hooksetvalue = hs;
                     t2.tls_op = TLS_OP_EQUAL;
                     t2.tls_field = TLS_MATCH_PROCNAME;
                     t2.tls_strvalue = "mypgm";
                     /* Join the items and form a single search tree. */
                     t3.tls_op = TLS_OP_AND;
                     t3.tls_left = &t1
                     t3.tls_right = &t2
                     /* Open the default trace log object. */
                     rv = trc_open("", "", TRC_LOGREAD|TRC_LOGPROC, &h);
                     if (rv) {
                             trc_perror(h, rv, "open");
                             return(rv);
                     }
                     /* Do the search. */
                     rv = trc_find_first(h, &t3, &r);
                     if (rv) {
                             trc_perror(h, rv, "find test");
                             return(rv);
                     }
   
                     ...
             }

3. You can find hooks 101, 104 and 1AB1 for program mypgm using the trc_hookset64_t type. Hooks 101 and 104 are equal to 0x1010 and 0x1040.

   {
                     int rv;
                     trc_loghandle_t h;
                     trc_read_t r;
                     trc_logsearch_t t1, t2, t3;
                     trc_hookset64_t hs;
   
                     /* Setup the hook set. */
                     trc_hkemptyset64(hs);
                     (void)trc_hkaddset64(hs, 0x1010);
                     (void)trc_hkaddset64(hs, 0x1040);
                     (void)trc_hkaddset64(hs, 0x1AB1);
   
                     /* Setup the leaf search arguments. */
                     t1.tls_op = TLS_OP_EQUAL;
                     t1.tls_field = TLS_MATCH_HOOKSET64;
                     t1.tls_hooksetvalue = hs;
                     t2.tls_op = TLS_OP_EQUAL;
                     t2.tls_field = TLS_MATCH_PROCNAME;
                     t2.tls_strvalue = "mypgm";
                     /* Join the items and form a single search tree. */
                     t3.tls_op = TLS_OP_AND;
                     t3.tls_left = &t1
                     t3.tls_right = &t2
                     /* Open the default trace log object. */
                     rv = trc_open("", "", TRC_LOGREAD|TRC_LOGPROC, &h);
                     if (rv) {
                             trc_perror(h, rv, "open");
                             return(rv);
                     }
                     /* Do the search. */
                     rv = trc_find_first(h, &t3, &r);
                     if (rv) {
                             trc_perror(h, rv, "find test");
                             return(rv);
                     }
   
                     . . .
             }