libnvpair.h revision 277589
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