1 .\" Copyright (c) 2009 James Gritton.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nm jailparam_import ,
38 .Nm jailparam_import_raw ,
41 .Nm jailparam_export ,
43 .Nd create and manage system jails
50 .Vt extern char jail_errmsg[] ;
52 .Fn jail_getid "const char *name"
54 .Fn jail_getname "int jid"
56 .Fn jail_setv "int flags" ...
58 .Fn jail_getv "int flags" ...
60 .Fn jailparam_all "struct jailparam **jpp"
62 .Fn jailparam_init "struct jailparam *jp" "const char *name"
64 .Fn jailparam_import "struct jailparam *jp" "const char *value"
66 .Fn jailparam_import_raw "struct jailparam *jp" "void *value" "size_t valuelen"
68 .Fn jailparam_set "struct jailparam *jp" "unsigned njp" "int flags"
70 .Fn jailparam_get "struct jailparam *jp" "unsigned njp" "int flags"
72 .Fn jailparam_export "struct jailparam *jp"
74 .Fn jailparam_free "struct jailparam *jp" "unsigned njp"
78 library is an interface to the
83 .Va security.jail.param
85 It simplifies the conversion of prison parameters between internal and
86 string formats, allowing the setting and querying of prisons without
87 knowing the parameter formats.
91 function returns the JID of the jail identified by
93 or \-1 if the jail does not exist.
97 function returns the name of the jail identified by
99 or NULL if the jail does not exist.
103 function takes a null-terminated list of name and value strings,
109 function takes a null-terminated list of name and value strings,
112 It is the caller's responsibility to ensure that the value strings point
113 to buffers large enough to hold the string representation of the
120 to a list of all known jail parameters, and returns the number of
122 The list should later be freed with
129 function clears a parameter record and copies the
131 to it. After use, it should be freed with
138 to a parameter record, converting it from a string to its native form.
140 .Fn jailparam_import_raw
141 function adds a value without performing any conversion.
145 function passes a list of parameters to
147 The parameters are assumed to have been created with
150 .Fn jailparam_import .
154 function function passes a list of parameters to
156 The parameters are assumed to have been created with
160 with one parameter (the key) having been given a value with
161 .Fn jailparam_import .
165 function returns the string equivalent of a parameter value.
166 The returned string should freed after use.
170 function frees the stored names and values in a parameter list.
171 If the list itself came from
173 it should be freed as well.
175 Set the hostname of jail
179 .Bd -literal -offset indent
180 jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar",
185 .Bd -literal -offset indent
186 struct jailparam params[2];
187 jailparam_init(¶ms[0], "name");
188 jailparam_import(¶ms[0], "foo");
189 jailparam_init(¶ms[1], "host.hostname");
190 jailparam_import(¶ms[1], "foo.bar");
191 jailparam_set(params, 2, JAIL_UPDATE);
192 jailparam_free(params, 2);
195 Retrieve the hostname of jail
197 .Bd -literal -offset indent
198 char hostname[MAXHOSTNAMELEN];
199 jail_getv(0, "name", "foo", "host.hostname", hostname, NULL);
203 .Bd -literal -offset indent
204 struct jailparam params[2];
205 jailparam_init(¶ms[0], "name");
206 jailparam_import(¶ms[0], "foo");
207 jailparam_init(¶ms[1], "host.hostname");
208 jailparam_get(params, 2, 0);
209 hostname = jailparam_export(¶ms[1]);
210 jailparam_free(params, 2);
222 functions return a JID on success, or \-1 on error.
228 functions return a dynamically allocated string on success, or NULL on error.
232 function returns the number of parameters on success, or \-1 on error.
238 .Fn jailparam_import_raw
239 functions return 0 on success, or \-1 on error.
241 Whenever an error is returned,
243 is set, and the global string
245 contains a descrption of the error, possibly from
252 functions may return errors from
258 In addition, the following errors are possible:
261 A prameter value cannot be convert from the passed string to its
264 The named parameter does not exist.
266 A parameter is of an unknown type.
274 library first appeared in