trc_hookname Subroutine

Purpose

Returns one or all hooks and associated names from the template file.

Library

libtrace.a

Syntax

#include <sys/libtrace.h>

int trc_hookname (handle, hook, hooknamep)
trc_log_handle_t handle;
trc_hookid_t hook;
trc_hookname_t *hooknamep;

Description

The trc_hookname subroutine returns one or more hook ids and their associated descriptions. This allows a trace data formatter to provide a hook selection list with some descriptive text for each hook.

Parameters

Item Description
handle Contains a trc_log_handle_t data item returned from a successful call to the trc_open subroutine.
hook Before AIX® 6.1, the hook parameter contained a hook ID in the form of 0xhhh where hhh was a 3-hex-digit hook ID. Beginning with AIX 6.1, the hook parameter contains a hook ID in the form of 0xhhhh where hhhh is a 4-hex-digit hook ID. If the hook parameter is TRC_HOOK_ALL, the names for all of the hooks in the template file are returned.
hooknamep Points to a trc_hookname_t structure. The trc_free subroutine should be used to free any data referenced by the trc_hookname_t data item.
/* Array element type for hook ids and names. */
     typedef struct {
             trc_hookid_t hookid;
             char *hookname;
     } trc_hooknm_t;

     typedef struct {
             int trchn_magic;                /* Identifier for this data structure. */
             unsigned trchn_nhooks;          /* Number of hooks. */
             trc_hooknm_t *trchn_names;      /* Pointer to array of ids and names. */
     } trc_hookname_t;

Return Values

Upon successful completion, the trc_hookname subroutine returns 0.

Error Codes

Item Description
ENOMEM Not enough memory to satisfy the request.
TRCE_WARN A formatting error was found in the template file. If TRCE_WARN is returned, the function completed.
TRCE_BADFORMAT A formatting error was found in the template file. If TRCE_BADFORMAT was returned, the errno global variable is set to EINVAL.