xref: /illumos-gate/usr/src/lib/libnvpair/libnvpair.h (revision 2db6d663)
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) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
23  * Copyright (c) 2013, Joyent, Inc. All rights reserved.
24  */
25 
26 #ifndef	_LIBNVPAIR_H
27 #define	_LIBNVPAIR_H
28 
29 #include <sys/nvpair.h>
30 #include <stdlib.h>
31 #include <stdio.h>
32 #include <regex.h>
33 
34 #ifdef	__cplusplus
35 extern "C" {
36 #endif
37 
38 /*
39  * All interfaces described in this file are private to Solaris, and
40  * are subject to change at any time and without notice.  The public
41  * nvlist/nvpair interfaces, as documented in manpage sections 3NVPAIR,
42  * are all imported from <sys/nvpair.h> included above.
43  */
44 
45 extern int nvpair_value_match(nvpair_t *, int, char *, char **);
46 extern int nvpair_value_match_regex(nvpair_t *, int, char *, regex_t *,
47     char **);
48 
49 extern void nvlist_print(FILE *, nvlist_t *);
50 extern int nvlist_print_json(FILE *, nvlist_t *);
51 extern void dump_nvlist(nvlist_t *, int);
52 
53 /*
54  * Private nvlist printing interface that allows the caller some control
55  * over output rendering (as opposed to nvlist_print and dump_nvlist).
56  *
57  * Obtain an opaque nvlist_prtctl_t cookie using nvlist_prtctl_alloc
58  * (NULL on failure);  on return the cookie is set up for default formatting
59  * and rendering.  Quote the cookie in subsequent customisation functions and
60  * then pass the cookie to nvlist_prt to render the nvlist.  Finally,
61  * use nvlist_prtctl_free to release the cookie.
62  *
63  * For all nvlist_lookup_xxx and nvlist_lookup_xxx_array functions
64  * we have a corresponding brace of functions that appoint replacement
65  * rendering functions:
66  *
67  *	extern void nvlist_prtctl_xxx(nvlist_prtctl_t,
68  *	    void (*)(nvlist_prtctl_t ctl, void *private, const char *name,
69  *	    xxxtype value))
70  *
71  *	and
72  *
73  *	extern void nvlist_prtctl_xxx_array(nvlist_prtctl_t,
74  *	    void (*)(nvlist_prtctl_t ctl, void *private, const char *name,
75  *	    xxxtype value, uint_t count))
76  *
77  * where xxxtype is the C datatype corresponding to xxx, eg int8_t for "int8"
78  * and char * for "string".  The function that is appointed to render the
79  * specified datatype receives as arguments the cookie, the nvlist
80  * member name, the value of that member (or a pointer for array function),
81  * and (for array rendering functions) a count of the number of elements.
82  */
83 
84 typedef struct nvlist_prtctl *nvlist_prtctl_t;	/* opaque */
85 
86 enum nvlist_indent_mode {
87 	NVLIST_INDENT_ABS,	/* Absolute indentation */
88 	NVLIST_INDENT_TABBED	/* Indent with tabstops */
89 };
90 
91 extern nvlist_prtctl_t nvlist_prtctl_alloc(void);
92 extern void nvlist_prtctl_free(nvlist_prtctl_t);
93 extern void nvlist_prt(nvlist_t *, nvlist_prtctl_t);
94 
95 /* Output stream */
96 extern void nvlist_prtctl_setdest(nvlist_prtctl_t, FILE *);
97 extern FILE *nvlist_prtctl_getdest(nvlist_prtctl_t);
98 
99 /* Indentation mode, start indent, indent increment; default tabbed/0/1 */
100 extern void nvlist_prtctl_setindent(nvlist_prtctl_t, enum nvlist_indent_mode,
101     int, int);
102 extern void nvlist_prtctl_doindent(nvlist_prtctl_t, int);
103 
104 enum nvlist_prtctl_fmt {
105 	NVLIST_FMT_MEMBER_NAME,		/* name fmt; default "%s = " */
106 	NVLIST_FMT_MEMBER_POSTAMBLE,	/* after nvlist member; default "\n" */
107 	NVLIST_FMT_BTWN_ARRAY		/* between array members; default " " */
108 };
109 
110 extern void nvlist_prtctl_setfmt(nvlist_prtctl_t, enum nvlist_prtctl_fmt,
111     const char *);
112 extern void nvlist_prtctl_dofmt(nvlist_prtctl_t, enum nvlist_prtctl_fmt, ...);
113 
114 /*
115  * Function prototypes for interfaces that appoint a new rendering function
116  * for single-valued nvlist members.
117  *
118  * A replacement function receives arguments as follows:
119  *
120  *	nvlist_prtctl_t	Print control structure; do not change preferences
121  *			for this object from a print callback function.
122  *
123  *	void *		The function-private cookie argument registered
124  *			when the replacement function was appointed.
125  *
126  *	nvlist_t *	The full nvlist that is being processed.  The
127  *			rendering function is called to render a single
128  *			member (name and value passed as below) but it may
129  *			want to reference or incorporate other aspects of
130  *			the full nvlist.
131  *
132  *	const char *	Member name to render
133  *
134  *	valtype		Value of the member to render
135  *
136  * The function must return non-zero if it has rendered output for this
137  * member, or 0 if it wants to default to standard rendering for this
138  * one member.
139  */
140 
141 #define	NVLIST_PRINTCTL_SVDECL(funcname, valtype) \
142     extern void funcname(nvlist_prtctl_t, \
143     int (*)(nvlist_prtctl_t, void *, nvlist_t *, const char *, valtype), \
144     void *)
145 
146 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_boolean, int);
147 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_boolean_value, boolean_t);
148 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_byte, uchar_t);
149 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int8, int8_t);
150 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint8, uint8_t);
151 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int16, int16_t);
152 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint16, uint16_t);
153 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int32, int32_t);
154 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint32, uint32_t);
155 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int64, int64_t);
156 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint64, uint64_t);
157 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_double, double);
158 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_string, char *);
159 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_hrtime, hrtime_t);
160 NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_nvlist, nvlist_t *);
161 
162 #undef	NVLIST_PRINTCTL_SVDECL	/* was just for "clarity" above */
163 
164 /*
165  * Function prototypes for interfaces that appoint a new rendering function
166  * for array-valued nvlist members.
167  *
168  * One additional argument is taken: uint_t for the number of array elements
169  *
170  * Return values as above.
171  */
172 #define	NVLIST_PRINTCTL_AVDECL(funcname, vtype) \
173     extern void funcname(nvlist_prtctl_t, \
174     int (*)(nvlist_prtctl_t, void *, nvlist_t *, const char *, vtype, uint_t), \
175     void *)
176 
177 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_boolean_array, boolean_t *);
178 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_byte_array, uchar_t *);
179 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int8_array, int8_t *);
180 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint8_array, uint8_t *);
181 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int16_array, int16_t *);
182 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint16_array, uint16_t *);
183 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int32_array, int32_t *);
184 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint32_array, uint32_t *);
185 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int64_array, int64_t *);
186 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint64_array, uint64_t *);
187 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_string_array, char **);
188 NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_nvlist_array, nvlist_t **);
189 
190 #undef	NVLIST_PRINTCTL_AVDECL	/* was just for "clarity" above */
191 
192 #ifdef	__cplusplus
193 }
194 #endif
195 
196 #endif	/* _LIBNVPAIR_H */
197