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
101 if the jail does not exist.
105 function takes a null-terminated list of name and value strings,
111 function takes a null-terminated list of name and value strings,
114 It is the caller's responsibility to ensure that the value strings point
115 to buffers large enough to hold the string representation of the
122 to a list of all known jail parameters, and returns the number of
124 The list should later be freed with
131 function clears a parameter record and copies the
134 After use, it should be freed with
141 to a parameter record, converting it from a string to its native form.
143 .Fn jailparam_import_raw
144 function adds a value without performing any conversion.
148 function passes a list of parameters to
150 The parameters are assumed to have been created with
153 .Fn jailparam_import .
157 function passes a list of parameters to
159 The parameters are assumed to have been created with
163 with one parameter (the key) having been given a value with
164 .Fn jailparam_import .
168 function returns the string equivalent of a parameter value.
169 The returned string should be freed after use.
173 function frees the stored names and values in a parameter list.
174 If the list itself came from
176 it should be freed as well.
185 functions return a JID on success, or \-1 on error.
191 functions return a dynamically allocated string on success, or
197 function returns the number of parameters on success, or \-1 on error.
203 .Fn jailparam_import_raw
204 functions return 0 on success, or \-1 on error.
206 Whenever an error is returned,
208 is set, and the global string
210 contains a description of the error, possibly from
215 Set the hostname of jail
219 .Bd -literal -offset indent
220 jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar",
225 .Bd -literal -offset indent
226 struct jailparam params[2];
227 jailparam_init(¶ms[0], "name");
228 jailparam_import(¶ms[0], "foo");
229 jailparam_init(¶ms[1], "host.hostname");
230 jailparam_import(¶ms[1], "foo.bar");
231 jailparam_set(params, 2, JAIL_UPDATE);
232 jailparam_free(params, 2);
235 Retrieve the hostname of jail
237 .Bd -literal -offset indent
238 char hostname[MAXHOSTNAMELEN];
239 jail_getv(0, "name", "foo", "host.hostname", hostname, NULL);
243 .Bd -literal -offset indent
244 struct jailparam params[2];
245 jailparam_init(¶ms[0], "name");
246 jailparam_import(¶ms[0], "foo");
247 jailparam_init(¶ms[1], "host.hostname");
248 jailparam_get(params, 2, 0);
249 hostname = jailparam_export(¶ms[1]);
250 jailparam_free(params, 2);
255 functions may return errors from
261 In addition, the following errors are possible:
264 A parameter value cannot be converted from the passed string to its
267 The named parameter does not exist.
269 A parameter is of an unknown type.
278 library first appeared in