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

FreeBSD Manual Pages

  
 
  

home | help 
JAIL(3)			    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
       system 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)
       system calls, and the security.jail.param MIB entries.	It  simplifies
       the  conversion	of  prison parameters between internal and string for-
       mats, allowing 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 responsibil-
       ity  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 para-
       meters, 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,
       converting   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) hav-
       ing been	given a	value with jailparam_import().

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

       The  jailparam_free()  function	frees the stored names and values in a
       parameter 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  dynami-
       cally allocated string on success, or NULL on error.

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

       The  jailparam_init(),  jailparam_import()  and	jailparam_import_raw()
       functions 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	possi-
       ble:

       [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(3lua), jail(8)

HISTORY
       The jail	library	first appeared in FreeBSD 8.0.

AUTHORS
       James Gritton

FreeBSD	14.3			August 31, 2010			       JAIL(3)

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

home | help