Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JAIL(3)			 BSD Library Functions Manual		       JAIL(3)

NAME
     jail_getid, jail_getname, jail_setv, jail_getv, jailparam_all,
     jailparam_init, jailparam_import, jailparam_import_raw, jailparam_set,
     jailparam_get, jailparam_export, jailparam_free --	create and manage sys-
     tem jails

LIBRARY
     Jail Library (libjail, -ljail)

SYNOPSIS
     #include <sys/param.h>
     #include <sys/jail.h>
     #include <jail.h>

     extern char jail_errmsg[];

     int
     jail_getid(const char *name);

     char *
     jail_getname(int jid);

     int
     jail_setv(int flags, ...);

     int
     jail_getv(int flags, ...);

     int
     jailparam_all(struct jailparam **jpp);

     int
     jailparam_init(struct jailparam *jp, const	char *name);

     int
     jailparam_import(struct jailparam *jp, const char *value);

     int
     jailparam_import_raw(struct jailparam *jp,	void *value, size_t valuelen);

     int
     jailparam_set(struct jailparam *jp, unsigned njp, int flags);

     int
     jailparam_get(struct jailparam *jp, unsigned njp, int flags);

     char *
     jailparam_export(struct jailparam *jp);

     void
     jailparam_free(struct jailparam *jp, unsigned njp);

DESCRIPTION
     The jail library is an interface to the jail_set(2) and jail_get(2) sys-
     tem calls,	and the	security.jail.param MIB	entries.  It simplifies	the
     conversion	of prison parameters between internal and string formats, al-
     lowing the	setting	and querying of	prisons	without	knowing	the parameter
     formats.

     The jail_getid() function returns the JID of the jail identified by name,
     or	-1 if the jail does not	exist.

     The jail_getname()	function returns the name of the jail identified by
     jid, or NULL if the jail does not exist.

     The jail_setv() function takes a null-terminated list of name and value
     strings, and passes it to jail_set(2).

     The jail_getv() function takes a null-terminated list of name and value
     strings, and passes it to jail_get(2).  It	is the caller's	responsibility
     to	ensure that the	value strings point to buffers large enough to hold
     the string	representation of the returned parameters.

     The jailparam_all() function sets jpp to a	list of	all known jail parame-
     ters, and returns the number of parameters.  The list should later	be
     freed with	jailparam_free() and free(3).

     The jailparam_init() function clears a parameter record and copies	the
     name to it.  After	use, it	should be freed	with jailparam_free().

     The jailparam_import() function adds a value to a parameter record, con-
     verting it	from a string to its native form.  The jailparam_import_raw()
     function adds a value without performing any conversion.

     The jailparam_set() function passes a list	of parameters to jail_set(2).
     The parameters are	assumed	to have	been created with jailparam_init() and
     jailparam_import().

     The jailparam_get() function passes a list	of parameters to jail_get(2).
     The parameters are	assumed	to have	been created with jailparam_init() or
     jailparam_list(), with one	parameter (the key) having been	given a	value
     with jailparam_import().

     The jailparam_export() function returns the string	equivalent of a	param-
     eter value.  The returned string should be	freed after use.

     The jailparam_free() function frees the stored names and values in	a pa-
     rameter list.  If the list	itself came from jailparam_all(), it should be
     freed as well.

RETURN VALUES
     The jail_getid(), jail_setv(), jail_getv(), jailparam_set() and
     jailparam_get() functions return a	JID on success,	or -1 on error.

     The jail_getname()	and jailparam_export() functions return	a dynamically
     allocated string on success, or NULL on error.

     The jailparam_all() function returns the number of	parameters on success,
     or	-1 on error.

     The jailparam_init(), jailparam_import() and jailparam_import_raw() func-
     tions return 0 on success,	or -1 on error.

     Whenever an error is returned, errno is set, and the global string
     jail_errmsg contains a description	of the error, possibly from
     jail_set(2) or jail_get(2).

EXAMPLES
     Set the hostname of jail "foo" to "foo.bar":

	   jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar",
	       NULL);

     OR:

	   struct jailparam params[2];
	   jailparam_init(&params[0], "name");
	   jailparam_import(&params[0],	"foo");
	   jailparam_init(&params[1], "host.hostname");
	   jailparam_import(&params[1],	"foo.bar");
	   jailparam_set(params, 2, JAIL_UPDATE);
	   jailparam_free(params, 2);

     Retrieve the hostname of jail "foo":

	   char	hostname[MAXHOSTNAMELEN];
	   jail_getv(0,	"name",	"foo", "host.hostname",	hostname, NULL);

     OR:

	   struct jailparam params[2];
	   jailparam_init(&params[0], "name");
	   jailparam_import(&params[0],	"foo");
	   jailparam_init(&params[1], "host.hostname");
	   jailparam_get(params, 2, 0);
	   hostname = jailparam_export(&params[1]);
	   jailparam_free(params, 2);
	   ...
	   free(hostname);

ERRORS
     The jail functions	may return errors from jail_set(2), jail_get(2),
     malloc(3) or sysctl(3).  In addition, the following errors	are possible:

     [EINVAL]		A parameter value cannot be converted from the passed
			string to its internal form.

     [ENOENT]		The named parameter does not exist.

     [ENOENT]		A parameter is of an unknown type.

SEE ALSO
     jail(2), sysctl(3), jail(8)

HISTORY
     The jail library first appeared in	FreeBSD	8.0.

AUTHORS
     James Gritton

BSD				August 31, 2010				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=jail_getid&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help