include/libnvpair.h

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