ea_free(3exacct)

1ea_set_item(3EXAECxCtTe)nded Accounting File Access Library Funcetai_osnest_item(3EXACCT)
2
3
4

NAME

6       ea_set_item,  ea_alloc,  ea_strdup, ea_set_group, ea_match_object_cata‐
7       log,  ea_attach_to_object,  ea_attach_to_group,  ea_free,   ea_strfree,
8       ea_free_item,  ea_free_object  -  create, destroy and manipulate exacct
9       objects
10

SYNOPSIS

12       cc [ flag... ] file... -lexacct [ library... ]
13       #include <exacct.h>
14
15       int ea_set_item(ea_object_t *obj, ea_catalog_t tag, void *value,
16            size_t valsize);
17
18
19       void *ea_alloc(size_t size);
20
21
22       char *ea_strdup(char *ptr);
23
24
25       int ea_set_group(ea_object_t *obj, ea_catalog_t tag);
26
27
28       int ea_match_object_catalog(ea_object_t *obj, ea_catalog_t catmask);
29
30
31       void ea_attach_to_object(ea_object_t *head_obj, ea_object_t *obj);
32
33
34       void ea_attach_to_group(ea_object_t *group_obj, ea_object_t *obj);
35
36
37       void ea_free(void *ptr, size_t size);
38
39
40       void ea_strfree(char *ptr);
41
42
43       int ea_free_item(ea_object_t *obj, int flag);
44
45
46       void ea_free_object(ea_object_t *obj, int flag);
47
48

DESCRIPTION

50       The ea_alloc() function allocates a block of memory  of  the  requested
51       size.  This  block can be safely passed to libexacct functions, and can
52       be safely freed by any of the ea_free() functions.
53
54
55       The ea_strdup() function can be used to duplicate a string that  is  to
56       be stored inside an ea_object_t structure.
57
58
59       The  ea_set_item()  function   assigns  the given exacct object to be a
60       data item with value set according to  the  remaining  arguments.   For
61       buffer-based  data values (EXT_STRING, EXT_EXACCT_OBJECT, and EXT_RAW),
62       a copy of the passed buffer is taken. In the case of EXT_EXACCT_OBJECT,
63       the  passed  buffer  should  be  a  packed exacct object as returned by
64       ea_pack_object(3EXACCT). Any item assigned with ea_set_item() should be
65       freed with ea_free_item() specifying a flag value of EUP_ALLOC when the
66       item is no longer needed.
67
68
69       The ea_match_object_catalog()  function  returns  TRUE  if  the  exacct
70       object  specified by obj has a catalog tag that matches the mask speci‐
71       fied by catmask.
72
73
74       The ea_attach_to_object() function attaches  an  object  to  the  given
75       object.  The  ea_attach_to_group() function attaches a chain of objects
76       as member items of the given group. Objects are inserted at the end  of
77       the list of any previously attached objects.
78
79
80       The  ea_free() function frees a block of memory previously allocated by
81       ea_alloc().
82
83
84       The  ea_strfree()  function  frees  a  string  previously   copied   by
85       ea_strdup().
86
87
88       The  ea_free_item()  function frees the value fields in the ea_object_t
89       indicated by obj, if EUP_ALLOC is specified. The object itself  is  not
90       freed. The ea_free_object() function frees the specified object and any
91       attached  hierarchy  of  objects.  If  the  flag  argument  is  set  to
92       EUP_ALLOC,  ea_free_object() will also free any variable-length data in
93       the object hierarchy; if set to EUP_NOALLOC, ea_free_object() will  not
94       free  variable-length  data.   In particular, these flags should corre‐
95       spond to those specified in calls to ea_unpack_object(3EXACCT).
96

RETURN VALUES

98       The ea_match_object_catalog() function returns 0 if the object's  cata‐
99       log tag does not match the given mask, and 1 if there is a match.
100
101
102       Other  integer-valued functions return 0 if successful. Otherwise these
103       functions return -1 and set the extended accounting error  code  appro‐
104       priately. Pointer-valued functions return a valid pointer if successful
105       and NULL otherwise, setting the extended accounting error  code  appro‐
106       priately.  The  extended  accounting  error  code  can be examined with
107       ea_error(3EXACCT).
108

ERRORS

110       The ea_set_item(), ea_set_group(), and ea_match_object_catalog()  func‐
111       tions may fail if:
112
113       EXR_SYSCALL_FAIL      A system call invoked by the function failed. The
114                             errno variable contains the error  value  set  by
115                             the underlying call.
116
117
118       EXR_INVALID_OBJECT    The  passed  object  is of an incorrect type, for
119                             example passing a group object to ea_set_item().
120
121

USAGE

123       The exacct file format can be used to represent data other than that in
124       the  extended accounting format.  By using a unique creator type in the
125       file header, application writers can develop their own format suited to
126       the needs of their application.
127

EXAMPLES

129       Example 1 Open and close exacct file.
130
131
132       Construct  an  exacct file consisting of a single object containing the
133       current process ID.
134
135
136         #include <sys/types.h>
137         #include <unistd.h>
138         #include <exacct.h>
139
140         ...
141
142         ea_file_t ef;
143         ea_object_t obj;
144         pid_t my_pid;
145
146         my_pid = getpid();
147         ea_set_item(&obj, EXT_UINT32 | EXC_DEFAULT | EXT_PROC_PID,
148                &my_pid, sizeof(my_pid));
149
150         ...
151
152

ATTRIBUTES

154       See attributes(5) for descriptions of the following attributes:
155
156
157
158
159       ┌─────────────────────────────┬─────────────────────────────┐
160       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
161       ├─────────────────────────────┼─────────────────────────────┤
162       │Interface Stability          │Evolving                     │
163       ├─────────────────────────────┼─────────────────────────────┤
164       │MT-Level                     │MT-Safe                      │
165       └─────────────────────────────┴─────────────────────────────┘
166