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  conver-
     sion of prison parameters between internal and string formats, 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  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  parame-
     ter value.  The returned string should be freed after use.

     The  jailparam_free() function frees the stored names and values in a para-
     meter 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  jail-
     param_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), mal-
     loc(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(3lua), jail(8)

HISTORY
     The jail library first appeared in FreeBSD 8.0.

AUTHORS
     James Gritton

FreeBSD ports 15.quarterly	 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+15.1-RELEASE+and+Ports.quarterly>

home | help