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