1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21/*
22 * Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
23 */
24
25#ifndef _LIBUUTIL_H
26#define _LIBUUTIL_H
27
28#include <solaris.h>
29#include <sys/types.h>
30#include <stdarg.h>
31#include <stdio.h>
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37/*
38 * Standard flags codes.
39 */
40#define UU_DEFAULT 0
41
42/*
43 * Standard error codes.
44 */
45#define UU_ERROR_NONE 0 /* no error */
46#define UU_ERROR_INVALID_ARGUMENT 1 /* invalid argument */
47#define UU_ERROR_UNKNOWN_FLAG 2 /* passed flag invalid */
48#define UU_ERROR_NO_MEMORY 3 /* out of memory */
49#define UU_ERROR_CALLBACK_FAILED 4 /* callback-initiated error */
50#define UU_ERROR_NOT_SUPPORTED 5 /* operation not supported */
51#define UU_ERROR_EMPTY 6 /* no value provided */
52#define UU_ERROR_UNDERFLOW 7 /* value is too small */
53#define UU_ERROR_OVERFLOW 8 /* value is too value */
54#define UU_ERROR_INVALID_CHAR 9 /* value contains unexpected char */
55#define UU_ERROR_INVALID_DIGIT 10 /* value contains digit not in base */
56
57#define UU_ERROR_SYSTEM 99 /* underlying system error */
58#define UU_ERROR_UNKNOWN 100 /* error status not known */
59
60/*
61 * Standard program exit codes.
62 */
63#define UU_EXIT_OK (*(uu_exit_ok()))
64#define UU_EXIT_FATAL (*(uu_exit_fatal()))
65#define UU_EXIT_USAGE (*(uu_exit_usage()))
66
67/*
68 * Exit status profiles.
69 */
70#define UU_PROFILE_DEFAULT 0
71#define UU_PROFILE_LAUNCHER 1
72
73/*
74 * Error reporting functions.
75 */
76uint32_t uu_error(void);
77const char *uu_strerror(uint32_t);
78
79/*
80 * Program notification functions.
81 */
82extern void uu_alt_exit(int);
83extern const char *uu_setpname(char *);
84extern const char *uu_getpname(void);
85/*PRINTFLIKE1*/
86extern void uu_warn(const char *, ...);
87extern void uu_vwarn(const char *, va_list);
88/*PRINTFLIKE1*/
89extern void uu_die(const char *, ...) __NORETURN;
90extern void uu_vdie(const char *, va_list) __NORETURN;
91/*PRINTFLIKE2*/
92extern void uu_xdie(int, const char *, ...) __NORETURN;
93extern void uu_vxdie(int, const char *, va_list) __NORETURN;
94
95/*
96 * Exit status functions (not to be used directly)
97 */
98extern int *uu_exit_ok(void);
99extern int *uu_exit_fatal(void);
100extern int *uu_exit_usage(void);
101
102/*
103 * string->number conversions
104 */
105extern int uu_strtoint(const char *, void *, size_t, int, int64_t, int64_t);
106extern int uu_strtouint(const char *, void *, size_t, int, uint64_t, uint64_t);
107
108/*
109 * Debug print facility functions.
110 */
111typedef struct uu_dprintf uu_dprintf_t;
112
113typedef enum {
114 UU_DPRINTF_SILENT,
115 UU_DPRINTF_FATAL,
116 UU_DPRINTF_WARNING,
117 UU_DPRINTF_NOTICE,
118 UU_DPRINTF_INFO,
119 UU_DPRINTF_DEBUG
120} uu_dprintf_severity_t;
121
122extern uu_dprintf_t *uu_dprintf_create(const char *, uu_dprintf_severity_t,
123 uint_t);
124/*PRINTFLIKE3*/
125extern void uu_dprintf(uu_dprintf_t *, uu_dprintf_severity_t,
126 const char *, ...);
127extern void uu_dprintf_destroy(uu_dprintf_t *);
128extern const char *uu_dprintf_getname(uu_dprintf_t *);
129
130/*
131 * Identifier test flags and function.
132 */
133#define UU_NAME_DOMAIN 0x1 /* allow SUNW, or com.sun, prefix */
134#define UU_NAME_PATH 0x2 /* allow '/'-delimited paths */
135
136int uu_check_name(const char *, uint_t);
137
138/*
139 * File creation functions.
140 */
141extern int uu_open_tmp(const char *dir, uint_t uflags);
142
143/*
144 * Convenience functions.
145 */
146#define UU_NELEM(a) (sizeof (a) / sizeof ((a)[0]))
147
148/*PRINTFLIKE1*/
149extern char *uu_msprintf(const char *format, ...);
150extern void *uu_zalloc(size_t);
151extern char *uu_strdup(const char *);
152extern void uu_free(void *);
153
154extern boolean_t uu_strcaseeq(const char *a, const char *b);
155extern boolean_t uu_streq(const char *a, const char *b);
156extern char *uu_strndup(const char *s, size_t n);
157extern boolean_t uu_strbw(const char *a, const char *b);
158extern void *uu_memdup(const void *buf, size_t sz);
159extern void uu_dump(FILE *out, const char *prefix, const void *buf, size_t len);
160
161/*
162 * Comparison function type definition.
163 * Developers should be careful in their use of the _private argument. If you
164 * break interface guarantees, you get undefined behavior.
165 */
166typedef int uu_compare_fn_t(const void *__left, const void *__right,
167 void *__private);
168
169/*
170 * Walk variant flags.
171 * A data structure need not provide support for all variants and
172 * combinations. Refer to the appropriate documentation.
173 */
174#define UU_WALK_ROBUST 0x00000001 /* walk can survive removes */
175#define UU_WALK_REVERSE 0x00000002 /* reverse walk order */
176
177#define UU_WALK_PREORDER 0x00000010 /* walk tree in pre-order */
178#define UU_WALK_POSTORDER 0x00000020 /* walk tree in post-order */
179
180/*
181 * Walk callback function return codes.
182 */
183#define UU_WALK_ERROR -1
184#define UU_WALK_NEXT 0
185#define UU_WALK_DONE 1
186
187/*
188 * Walk callback function type definition.
189 */
190typedef int uu_walk_fn_t(void *_elem, void *_private);
191
192/*
193 * lists: opaque structures
194 */
195typedef struct uu_list_pool uu_list_pool_t;
196typedef struct uu_list uu_list_t;
197
198typedef struct uu_list_node {
199 uintptr_t uln_opaque[2];
200} uu_list_node_t;
201
202typedef struct uu_list_walk uu_list_walk_t;
203
204typedef uintptr_t uu_list_index_t;
205
206/*
207 * lists: interface
208 *
209 * basic usage:
210 * typedef struct foo {
211 * ...
212 * uu_list_node_t foo_node;
213 * ...
214 * } foo_t;
215 *
216 * static int
217 * foo_compare(void *l_arg, void *r_arg, void *private)
218 * {
219 * foo_t *l = l_arg;
220 * foo_t *r = r_arg;
221 *
222 * if (... l greater than r ...)
223 * return (1);
224 * if (... l less than r ...)
225 * return (-1);
226 * return (0);
227 * }
228 *
229 * ...
230 * // at initialization time
231 * foo_pool = uu_list_pool_create("foo_pool",
232 * sizeof (foo_t), offsetof(foo_t, foo_node), foo_compare,
233 * debugging? 0 : UU_AVL_POOL_DEBUG);
234 * ...
235 */
236uu_list_pool_t *uu_list_pool_create(const char *, size_t, size_t,
237 uu_compare_fn_t *, uint32_t);
238#define UU_LIST_POOL_DEBUG 0x00000001
239
240void uu_list_pool_destroy(uu_list_pool_t *);
241
242/*
243 * usage:
244 *
245 * foo_t *a;
246 * a = malloc(sizeof(*a));
247 * uu_list_node_init(a, &a->foo_list, pool);
248 * ...
249 * uu_list_node_fini(a, &a->foo_list, pool);
250 * free(a);
251 */
252void uu_list_node_init(void *, uu_list_node_t *, uu_list_pool_t *);
253void uu_list_node_fini(void *, uu_list_node_t *, uu_list_pool_t *);
254
255uu_list_t *uu_list_create(uu_list_pool_t *, void *_parent, uint32_t);
256#define UU_LIST_DEBUG 0x00000001
257#define UU_LIST_SORTED 0x00000002 /* list is sorted */
258
259void uu_list_destroy(uu_list_t *); /* list must be empty */
260
261size_t uu_list_numnodes(uu_list_t *);
262
263void *uu_list_first(uu_list_t *);
264void *uu_list_last(uu_list_t *);
265
266void *uu_list_next(uu_list_t *, void *);
267void *uu_list_prev(uu_list_t *, void *);
268
269int uu_list_walk(uu_list_t *, uu_walk_fn_t *, void *, uint32_t);
270
271uu_list_walk_t *uu_list_walk_start(uu_list_t *, uint32_t);
272void *uu_list_walk_next(uu_list_walk_t *);
273void uu_list_walk_end(uu_list_walk_t *);
274
275void *uu_list_find(uu_list_t *, void *, void *, uu_list_index_t *);
276void uu_list_insert(uu_list_t *, void *, uu_list_index_t);
277
278void *uu_list_nearest_next(uu_list_t *, uu_list_index_t);
279void *uu_list_nearest_prev(uu_list_t *, uu_list_index_t);
280
281void *uu_list_teardown(uu_list_t *, void **);
282
283void uu_list_remove(uu_list_t *, void *);
284
285/*
286 * lists: interfaces for non-sorted lists only
287 */
288int uu_list_insert_before(uu_list_t *, void *_target, void *_elem);
289int uu_list_insert_after(uu_list_t *, void *_target, void *_elem);
290
291/*
292 * avl trees: opaque structures
293 */
294typedef struct uu_avl_pool uu_avl_pool_t;
295typedef struct uu_avl uu_avl_t;
296
297typedef struct uu_avl_node {
298#ifdef _LP64
299 uintptr_t uan_opaque[3];
300#else
301 uintptr_t uan_opaque[4];
302#endif
303} uu_avl_node_t;
304
305typedef struct uu_avl_walk uu_avl_walk_t;
306
307typedef uintptr_t uu_avl_index_t;
308
309/*
310 * avl trees: interface
311 *
312 * basic usage:
313 * typedef struct foo {
314 * ...
315 * uu_avl_node_t foo_node;
316 * ...
317 * } foo_t;
318 *
319 * static int
320 * foo_compare(void *l_arg, void *r_arg, void *private)
321 * {
322 * foo_t *l = l_arg;
323 * foo_t *r = r_arg;
324 *
325 * if (... l greater than r ...)
326 * return (1);
327 * if (... l less than r ...)
328 * return (-1);
329 * return (0);
330 * }
331 *
332 * ...
333 * // at initialization time
334 * foo_pool = uu_avl_pool_create("foo_pool",
335 * sizeof (foo_t), offsetof(foo_t, foo_node), foo_compare,
336 * debugging? 0 : UU_AVL_POOL_DEBUG);
337 * ...
338 */
339uu_avl_pool_t *uu_avl_pool_create(const char *, size_t, size_t,
340 uu_compare_fn_t *, uint32_t);
341#define UU_AVL_POOL_DEBUG 0x00000001
342
343void uu_avl_pool_destroy(uu_avl_pool_t *);
344
345/*
346 * usage:
347 *
348 * foo_t *a;
349 * a = malloc(sizeof(*a));
350 * uu_avl_node_init(a, &a->foo_avl, pool);
351 * ...
352 * uu_avl_node_fini(a, &a->foo_avl, pool);
353 * free(a);
354 */
355void uu_avl_node_init(void *, uu_avl_node_t *, uu_avl_pool_t *);
356void uu_avl_node_fini(void *, uu_avl_node_t *, uu_avl_pool_t *);
357
358uu_avl_t *uu_avl_create(uu_avl_pool_t *, void *_parent, uint32_t);
359#define UU_AVL_DEBUG 0x00000001
360
361void uu_avl_destroy(uu_avl_t *); /* list must be empty */
362
363size_t uu_avl_numnodes(uu_avl_t *);
364
365void *uu_avl_first(uu_avl_t *);
366void *uu_avl_last(uu_avl_t *);
367
368void *uu_avl_next(uu_avl_t *, void *);
369void *uu_avl_prev(uu_avl_t *, void *);
370
371int uu_avl_walk(uu_avl_t *, uu_walk_fn_t *, void *, uint32_t);
372
373uu_avl_walk_t *uu_avl_walk_start(uu_avl_t *, uint32_t);
374void *uu_avl_walk_next(uu_avl_walk_t *);
375void uu_avl_walk_end(uu_avl_walk_t *);
376
377void *uu_avl_find(uu_avl_t *, void *, void *, uu_avl_index_t *);
378void uu_avl_insert(uu_avl_t *, void *, uu_avl_index_t);
379
380void *uu_avl_nearest_next(uu_avl_t *, uu_avl_index_t);
381void *uu_avl_nearest_prev(uu_avl_t *, uu_avl_index_t);
382
383void *uu_avl_teardown(uu_avl_t *, void **);
384
385void uu_avl_remove(uu_avl_t *, void *);
386
387#ifdef __cplusplus
388}
389#endif
390
391#endif /* _LIBUUTIL_H */
392