1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2021 John H. Baldwin <jhb@FreeBSD.org>
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 *    notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 *    notice, this list of conditions and the following disclaimer in the
13 *    documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 * SUCH DAMAGE.
26 */
27
28#ifndef __CONFIG_H__
29#define	__CONFIG_H__
30
31#include <sys/nv.h>
32
33/*-
34 * Manages a configuration database backed by an nv(9) list.
35 *
36 * The database only stores string values.  Callers should parse
37 * values into other types if needed.  String values can reference
38 * other configuration variables using a '%(name)' syntax.  In this
39 * case, the name must be the full path of the configuration
40 * variable.  The % character can be escaped with a preceding \ to
41 * avoid expansion.  Any \ characters must be escaped.
42 *
43 * Configuration variables are stored in a tree.  The full path of a
44 * variable is specified as a dot-separated name similar to sysctl(8)
45 * OIDs.
46 */
47
48/*
49 * Fetches the value of a configuration variable.  If the "raw" value
50 * contains references to other configuration variables, this function
51 * expands those references and returns a pointer to the parsed
52 * string.  The string's storage is only stable until the next call to
53 * this function.
54 *
55 * If no node is found, returns NULL.
56 *
57 * If 'parent' is NULL, 'name' is assumed to be a top-level variable.
58 */
59const char *get_config_value_node(const nvlist_t *parent, const char *name);
60
61/*
62 * Similar to get_config_value_node but expects a full path to the
63 * leaf node.
64 */
65const char *get_config_value(const char *path);
66
67/* Initializes the tree to an empty state. */
68void	init_config(void);
69
70/*
71 * Creates an existing configuration node via a dot-separated OID
72 * path.  Will fail if the path names an existing leaf configuration
73 * variable.  If the node already exists, this returns a pointer to
74 * the existing node.
75 */
76nvlist_t *create_config_node(const char *path);
77
78/*
79 * Looks for an existing configuration node via a dot-separated OID
80 * path.  Will fail if the path names an existing leaf configuration
81 * variable.
82 */
83nvlist_t *find_config_node(const char *path);
84
85/*
86 * Similar to the above, but treats the path relative to an existing
87 * 'parent' node rather than as an absolute path.
88 */
89nvlist_t *create_relative_config_node(nvlist_t *parent, const char *path);
90nvlist_t *find_relative_config_node(nvlist_t *parent, const char *path);
91
92/*
93 * Adds or replaces the value of the specified variable.
94 *
95 * If 'parent' is NULL, 'name' is assumed to be a top-level variable.
96 */
97void	set_config_value_node(nvlist_t *parent, const char *name,
98    const char *value);
99
100/*
101 * Similar to set_config_value_node but only sets value if it's unset yet.
102 */
103void 	set_config_value_node_if_unset(nvlist_t *const parent,
104    const char *const name, const char *const value);
105
106/*
107 * Similar to set_config_value_node but expects a full path to the
108 * leaf node.
109 */
110void	set_config_value(const char *path, const char *value);
111
112/*
113 * Similar to set_config_value but only sets the value if it's unset yet.
114 */
115void 	set_config_value_if_unset(const char *const path,
116    const char *const value);
117
118/* Convenience wrappers for boolean variables. */
119bool	get_config_bool(const char *path);
120bool	get_config_bool_node(const nvlist_t *parent, const char *name);
121bool	get_config_bool_default(const char *path, bool def);
122bool	get_config_bool_node_default(const nvlist_t *parent, const char *name,
123    bool def);
124void	set_config_bool(const char *path, bool value);
125void	set_config_bool_node(nvlist_t *parent, const char *name, bool value);
126
127void	dump_config(void);
128
129#endif /* !__CONFIG_H__ */
130