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