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