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
35extern "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
45extern int nvpair_value_match(nvpair_t *, int, char *, char **);
46extern int nvpair_value_match_regex(nvpair_t *, int, char *, regex_t *,
47 char **);
48
49extern void nvlist_print(FILE *, nvlist_t *);
50extern int nvlist_print_json(FILE *, nvlist_t *);
51extern 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
84typedef struct nvlist_prtctl *nvlist_prtctl_t; /* opaque */
85
86enum nvlist_indent_mode {
87 NVLIST_INDENT_ABS, /* Absolute indentation */
88 NVLIST_INDENT_TABBED /* Indent with tabstops */
89};
90
91extern nvlist_prtctl_t nvlist_prtctl_alloc(void);
92extern void nvlist_prtctl_free(nvlist_prtctl_t);
93extern void nvlist_prt(nvlist_t *, nvlist_prtctl_t);
94
95/* Output stream */
96extern void nvlist_prtctl_setdest(nvlist_prtctl_t, FILE *);
97extern FILE *nvlist_prtctl_getdest(nvlist_prtctl_t);
98
99/* Indentation mode, start indent, indent increment; default tabbed/0/1 */
100extern void nvlist_prtctl_setindent(nvlist_prtctl_t, enum nvlist_indent_mode,
101 int, int);
102extern void nvlist_prtctl_doindent(nvlist_prtctl_t, int);
103
104enum 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
110extern void nvlist_prtctl_setfmt(nvlist_prtctl_t, enum nvlist_prtctl_fmt,
111 const char *);
112extern 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
146NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_boolean, int);
147NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_boolean_value, boolean_t);
148NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_byte, uchar_t);
149NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int8, int8_t);
150NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint8, uint8_t);
151NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int16, int16_t);
152NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint16, uint16_t);
153NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int32, int32_t);
154NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint32, uint32_t);
155NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_int64, int64_t);
156NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_uint64, uint64_t);
157NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_double, double);
158NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_string, char *);
159NVLIST_PRINTCTL_SVDECL(nvlist_prtctlop_hrtime, hrtime_t);
160NVLIST_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
177NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_boolean_array, boolean_t *);
178NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_byte_array, uchar_t *);
179NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int8_array, int8_t *);
180NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint8_array, uint8_t *);
181NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int16_array, int16_t *);
182NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint16_array, uint16_t *);
183NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int32_array, int32_t *);
184NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint32_array, uint32_t *);
185NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_int64_array, int64_t *);
186NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_uint64_array, uint64_t *);
187NVLIST_PRINTCTL_AVDECL(nvlist_prtctlop_string_array, char **);
188NVLIST_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