1ea_pack_object(3EExXtAeCnCdTe)d Accounting File Access Library Feuan_cptaicokn_sobject(3EXACCT)
2
6 ea_pack_object, ea_unpack_object, ea_get_creator, ea_get_hostname,
7 ea_next_object, ea_previous_object, ea_get_object, ea_write_object,
8 ea_copy_object, ea_copy_object_tree, ea_get_object_tree - construct,
9 read, and write extended accounting records
10
12 cc [ flag... ] file... -lexacct [ library... ]
13 #include <exacct.h>
14 size_t ea_pack_object(ea_object_t *obj, void *buf,
16 size_t bufsize);
17 ea_object_type_t ea_unpack_object(ea_object_t **objp, int flag,
20 void *buf, size_t bufsize);
21 const char *ea_get_creator(ea_file_t *ef);
24 const char *ea_get_hostname(ea_file_t *ef);
27 ea_object_type_t ea_next_object(ea_file_t *ef, ea_object_t *obj);
30 ea_object_type_t ea_previous_object(ea_file_t *ef,
33 ea_object_t *obj);
34 ea_object_type_t ea_get_object(ea_file_t *ef, ea_object_t *obj);
37 int ea_write_object(ea_file_t *ef, ea_object_t *obj);
40 ea_object_type_t *ea_copy_object(const ea_object_t *src);
43 ea_object_type_t *ea_copy_object_tree(const ea_object_t *src);
46 ea_object_type_t *ea_get_object_tree(ea_file_t *ef,
49 uint32_tnobj);
50
53 The ea_pack_object() function converts exacct objects from their in-
54 memory representation to their file representation. It is passed an
55 object pointer that points to the top of an exacct object hierarchy
56 representing one or more exacct records. It returns the size of the
57 buffer required to contain the packed buffer representing the object
58 hierarchy. To obtain the correct size of the required buffer, the buf
59 and bufsize parameters can be set to NULL and 0 respectively, and the
60 required buffer size will be returned. The resulting packed record can
61 be passed to putacct(2) or to ea_set_item(3EXACCT) when constructing an
62 object of type EXT_EXACCT_OBJECT.
63 The ea_unpack_object() function reverses the packing process performed
66 by ea_pack_object(). A packed buffer passed to ea_unpack_object() is
67 unpacked into the original hierarchy of objects. If the unpack opera‐
68 tion fails (for example, due to a corrupted or incomplete buffer), it
69 returns EO_ERROR; otherwise, the object type of the first object in the
70 hierarchy is returned. If ea_unpack_object() is invoked with flag
71 equal to EUP_ALLOC, it allocates memory for the variable-length data in
72 the included objects. Otherwise, with flag equal to EUP_NOALLOC, it
73 sets the variable length data pointers within the unpacked object
74 structures to point within the buffer indicated by buf. In both cases,
75 ea_unpack_object() allocates all the necessary exacct objects to repre‐
76 sent the unpacked record. The resulting object hierarchy can be freed
77 using ea_free_object(3EXACCT) with the same flag value.
78 The ea_get_creator() function returns a pointer to a string represent‐
81 ing the recorded creator of the exacct file. The ea_get_hostname()
82 function returns a pointer to a string representing the recorded host‐
83 name on which the exacct file was created. These functions will return
84 NULL if their respective field was not recorded in the exacct file
85 header.
86 The ea_next_object() function reads the basic fields (eo_catalog and
89 eo_type) into the ea_object_t indicated by obj from the exacct file
90 referred to by ef and rewinds to the head of the record. If the read
91 object is corrupted, ea_next_object() returns EO_ERROR and records the
92 extended accounting error code, accessible with ea_error(3EXACCT). If
93 end-of-file is reached, EO_ERROR is returned and the extended account‐
94 ing error code is set to EXR_EOF.
95 The ea_previous_object() function skips back one object in the file and
98 reads its basic fields (eo_catalog and eo_type) into the indicated
99 ea_object_t. If the read object is corrupted, ea_previous_object()
100 returns EO_ERROR and records the extended accounting error code, acces‐
101 sible with ea_error(3EXACCT). If end-of-file is reached, EO_ERROR is
102 returned and the extended accounting error code is set to EXR_EOF.
103 The ea_get_object() function reads the value fields into the
106 ea_object_t indicated by obj, allocating memory as necessary, and
107 advances to the head of the next record. Once a record group object is
108 retrieved using ea_get_object(), subsequent calls to ea_get_object()
109 and ea_next_object() will track through the objects within the record
110 group, and on reaching the end of the group, will return the next
111 object at the same level as the group from the file. If the read object
112 is corrupted, ea_get_object() returns EO_ERROR and records the extended
113 accounting error code, accessible with ea_error(3EXACCT). If end-of-
114 file is reached, EO_ERROR is returned and the extended accounting error
115 code is set to EXR_EOF.
116 The ea_write_object() function appends the given object to the open
119 exacct file indicated by ef and returns 0. If the write fails,
120 ea_write_object() returns −1 and sets the extended accounting error
121 code to indicate the error, accessible with ea_error(3EXACCT).
122 The ea_copy_object() function copies an ea_object_t. If the source
125 object is part of a chain, only the current object is copied. If the
126 source object is a group, only the group object is copied without its
127 list of members and the eg_nobjs and eg_objs fields are set to 0 and
128 NULL, respectively. Use ea_copy_tree() to copy recursively a group or a
129 list of items.
130 The ea_copy_object_tree() function recursively copies an ea_object_t.
133 All elements in the eo_next list are copied, and any group objects are
134 recursively copied. The returned object can be completely freed with
135 ea_free_object(3EXACCT) by specifying the EUP_ALLOC flag.
136 The ea_get_object_tree() function reads in nobj top-level objects from
139 the file, returning the same data structure that would have originally
140 been passed to ea_write_object(). On encountering a group object, the
141 ea_get_object() function reads only the group header part of the group,
142 whereas ea_get_object_tree() reads the group and all its member items,
143 recursing into sub-records if necessary. The returned object data
144 structure can be completely freed with ea_free_object() by specifying
145 the EUP_ALLOC flag.
146
148 The ea_pack_object() function returns the number of bytes required to
149 hold the exacct object being operated upon. If the returned size
150 exceeds bufsize, the pack operation does not complete and the function
151 returns (size_t) -1 and sets the extended accounting error code to
152 indicate the error.
153 The ea_get_object() function returns the ea_object_type of the object
156 if the object was retrieved successfully. Otherwise, it returns
157 EO_ERROR and sets the extended accounting error code to indicate the
158 error.
159 The ea_next_object() function returns the ea_object_type of the next
162 exacct object in the file. It returns EO_ERROR if the exacct file is
163 corrupted sets the extended accounting error code to indicate the
164 error.
165 The ea_unpack_object() function returns the ea_object_type of the first
168 exacct object unpacked from the buffer. It returns EO_ERROR if the
169 exacct file is corrupted, and sets the extended accounting error code
170 to indicate the error.
171 The ea_write_object() function returns 0 on success. Otherwise it
174 returns −1 and sets the extended accounting error code to indicate the
175 error.
176 The ea_copy_object() and ea_copy_object_tree() functions return the
179 copied object on success. Otherwise they return NULL and set the
180 extended accounting error code to indicate the error.
181 The ea_get_object_tree() function returns the list of objects read from
184 the file on success. Otherwise it returns NULL and sets the extended
185 accounting error code to indicate the error.
186 The extended account error code can be retrieved using
189 ea_error(3EXACCT).
190
192 These functions may fail if:
193 EXR_SYSCALL_FAIL
195 A system call invoked by the function failed. The errno variable
197 contains the error value set by the underlying call. On memory
198 allocation failure, errno will be set to ENOMEM.
199 EXR_CORRUPT_FILE
202 The file referred to by name is not a valid exacct file, or is
204 unparsable, and therefore appears corrupted. This error is also
205 used by ea_unpack_buffer() to indicate a corrupted buffer.
206 EXR_EOF
209 The end of the file has been reached. In the case of ea_previ‐
211 ous_record(), the previous record could not be reached, either
212 because the head of the file was encountered or because the previ‐
213 ous record could not be skipped over.
214
217 The exacct file format can be used to represent data other than that in
218 the extended accounting format. By using a unique creator type in the
219 file header, application writers can develop their own format suited to
220 the needs of their application.
221
223 Example 1 Open and close exacct file.
224 The following example opens the extended accounting data file for pro‐
227 cesses. The exacct file is then closed.
228 #include <stdio.h>
231 #include <exacct.h>
232 ea_file_t ef;
234 ea_object_t *obj;
235 ...
237 ea_open(&ef, "foo", O_RDONLY, ...);
239 while ((obj = ea_get_object_tree(&ef, 1)) != NULL) {
241 if (obj->eo_type == EO_ITEM) {
242 /* handle item */
243 } else {
244 /* handle group */
245 }
246 ea_free_object(obj, EUP_ALLOC);
247 }
248 if (ea_error() != EXR_EOF) {
250 /* handle error */
251 }
252 ea_close(&ef);
254 Example 2 Construct an exacct file consisting of a single object con‐
257 taining the current process ID.
258 #include <sys/types.h>
260 #include <unistd.h>
261 #include <exacct.h>
262 ...
264 ea_file_t ef;
266 ea_object_t obj;
267 pid_t my_pid;
268 ea_open(&ef, "foo", O_CREAT | O_WRONLY, ...);
270 my_pid = getpid();
272 ea_set_item(&obj, EXT_UINT32 | EXC_DEFAULT | EXT_PROC_PID, &my_pid, 0);
273 (void) ea_write_object(&ef, &obj);
274 ea_close(&ef);
276 ...
278
281 See attributes(5) for descriptions of the following attributes:
282 ┌─────────────────────────────┬─────────────────────────────┐
287 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
288 ├─────────────────────────────┼─────────────────────────────┤
289 │Interface Stability │Committed │
290 ├─────────────────────────────┼─────────────────────────────┤
291 │MT-Level │MT-Safe │
292 └─────────────────────────────┴─────────────────────────────┘
293
295 read(2), ea_error(3EXACCT), ea_open(3EXACCT), ea_set_item(3EXACCT),
296 libexacct(3LIB), attributes(5)
297SunOS 5.11 4 Oct 2007 ea_pack_object(3EXACCT)