home | help
SYSCTL(9)		    Kernel Developer's Manual		       SYSCTL(9)

NAME
     SYSCTL_DECL,    SYSCTL_INT,    SYSCTL_LONG,   SYSCTL_NODE,   SYSCTL_OPAQUE,
     SYSCTL_PROC,  SYSCTL_STRING,  SYSCTL_STRUCT,   SYSCTL_UINT,   SYSCTL_ULONG,
     SYSCTL_XINT, SYSCTL_XLONG -- Static sysctl declaration functions

SYNOPSIS
     #include <sys/types.h>
     #include <sys/sysctl.h>

     SYSCTL_DECL(name);

     SYSCTL_INT(parent, nbr, name, access, ptr, val, descr);

     SYSCTL_LONG(parent, nbr, name, access, ptr, val, descr);

     SYSCTL_NODE(parent, nbr, name, access, handler, descr);

     SYSCTL_OPAQUE(parent, nbr, name, access, ptr, len, fmt, descr);

     SYSCTL_PROC(parent, nbr, name, access, ptr, arg, handler, fmt, descr);

     SYSCTL_STRING(parent, nbr, name, access, arg, len, descr);

     SYSCTL_STRUCT(parent, nbr, name, access, ptr, type, descr);

     SYSCTL_UINT(parent, nbr, name, access, ptr, val, descr);

     SYSCTL_ULONG(parent, nbr, name, access, ptr, val, descr);

     SYSCTL_XINT(parent, nbr, name, access, ptr, val, descr);

     SYSCTL_XLONG(parent, nbr, name, access, ptr, val, descr);

DESCRIPTION
     The SYSCTL kernel interfaces allow code to statically declare sysctl(8) MIB
     entries,  which  will  be initialized when the kernel module containing the
     declaration is initialized.  When the module is unloaded, the  sysctl  will
     be automatically destroyed.

     Sysctl  nodes are created in a hierarchical tree, with all static nodes be-
     ing represented by named C data structures; in order to create a  new  node
     under  an existing node in the tree, the structure representing the desired
     parent node must be declared in the current context using SYSCTL_DECL().

     New  nodes  are  declared	using  one   of   SYSCTL_INT(),   SYSCTL_LONG(),
     SYSCTL_NODE(),	SYSCTL_OPAQUE(),     SYSCTL_PROC(),	SYSCTL_STRING(),
     SYSCTL_STRUCT(),	SYSCTL_UINT(),	 SYSCTL_ULONG(),   SYSCTL_XINT(),    and
     SYSCTL_XLONG().   Each  macro  accepts  a	parent	name,  as declared using
     SYSCTL_DECL(), an OID number, typically OID_AUTO, a node  name,  a  set  of
     control  and  access  flags,  and a description.  Depending on the macro, a
     pointer to a variable supporting the MIB entry, a	size,  a  value,  and  a
     function pointer implementing the MIB entry may also be present.

     For  most of the above macros, declaring a type as part of the access flags
     is not necessary -- however, when declaring a sysctl implemented by a func-
     tion, including a type in the access mask is required:

     CTLTYPE_NODE    This is a node intended to be a parent for other nodes.

     CTLTYPE_INT     This is a signed integer.

     CTLTYPE_STRING  This is a nul-terminated string stored in a  character  ar-
		     ray.

     CTLTYPE_QUAD    This is a 64-bit signed integer.

     CTLTYPE_OPAQUE  This is an opaque data structure.

     CTLTYPE_STRUCT  Alias for CTLTYPE_OPAQUE.

     CTLTYPE_UINT    This is an unsigned integer.

     CTLTYPE_LONG    This is a signed long.

     CTLTYPE_ULONG   This is an unsigned long.

     All sysctl types except for new node declarations require one or more flags
     to be set indicating the read and write disposition of the sysctl:

     CTLFLAG_RD       This is a read-only sysctl.

     CTLFLAG_WR       This is a writable sysctl.

     CTLFLAG_RW       This sysctl is readable and writable.

     CTLFLAG_ANYBODY  Any user or process can write to this sysctl.

     CTLFLAG_SECURE   This  sysctl  can  be written to only if the effective se-
		      curelevel of the process is <= 0.

     CTLFLAG_PRISON   This sysctl can be written to by processes in jail(2).

     CTLFLAG_SKIP     When iterating the sysctl name space,  do  not  list  this
		      sysctl.

     CTLFLAG_TUN      Also  declare  a system tunable with the same name to ini-
		      tialize this variable.

     CTLFLAG_RDTUN    Also declare a system tunable with the same name	to  ini-
		      tialize  this  variable; however, the run-time variable is
		      read-only.

     When creating new sysctls, careful attention should be paid to the security
     implications of the monitoring or management interface being created.  Most
     sysctls present in the kernel are read-only or writable only by  the  supe-
     ruser.   Sysctls  exporting extensive information on system data structures
     and operation, especially those implemented using procedures, will wish  to
     implement	access	control  to  limit the undesired exposure of information
     about other processes, network connections, etc.

     The following top level sysctl name spaces are commonly used:

     compat	 Compatibility layer information.

     debug	 Debugging information.  Various name spaces exist under debug.

     hw 	 Hardware and device driver information.

     kern	 Kernel behavior tuning; generally deprecated in favor	of  more
		 specific name spaces.

     machdep	 Machine-dependent configuration parameters.

     net	 Network  subsystem.   Various	protocols have name spaces under
		 net.

     regression  Regression test configuration and information.

     security	 Security and security-policy configuration and information.

     sysctl	 Reserved name space for the implementation of sysctl.

     user	 Configuration settings relating to user  application  behavior.
		 Generally,  configuring  applications	using  kernel sysctls is
		 discouraged.

     vfs	 Virtual file system configuration and information.

     vm 	 Virtual memory subsystem configuration and information.

EXAMPLES
     Sample use of SYSCTL_DECL() to declare the security sysctl tree for use  by
     new nodes:

	   SYSCTL_DECL(_security);

     Examples of integer, opaque, string, and procedure sysctls follow:

	   /*
	    * Example of a constant integer value.  Notice that the control
	    * flags are CTLFLAG_RD, the variable pointer is NULL, and the
	    * value is declared.
	    * If sysctl(8) should print this value in hex, use 'SYSCTL_XINT'.
	    */
	   SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, NULL,
	       sizeof(struct bio), "sizeof(struct bio)");

	   /*
	    * Example of a variable integer value.  Notice that the control
	    * flags are CTLFLAG_RW, the variable pointer is set, and the
	    * value is 0.
	    */
	   static int	   doingcache = 1;	   /* 1 => enable the cache */
	   SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
	       "Enable name cache");

	   /*
	    * Example of a variable string value.  Notice that the control
	    * flags are CTLFLAG_RW, that the variable pointer and string
	    * size are set.  Unlike newer sysctls, this older sysctl uses a
	    * static oid number.
	    */
	   char kernelname[MAXPATHLEN] = "/kernel";	   /* XXX bloat */
	   SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
	       kernelname, sizeof(kernelname), "Name of kernel file booted");

	   /*
	    * Example of an opaque data type exported by sysctl.  Notice that
	    * the variable pointer and size are provided, as well as a format
	    * string for sysctl(8).
	    */
	   static l_fp pps_freq;   /* scaled frequence offset (ns/s) */
	   SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
	       &pps_freq, sizeof(pps_freq), "I", "");

	   /*
	    * Example of a procedure based sysctl exporting string
	    * information.  Notice that the data type is declared, the NULL
	    * variable pointer and 0 size, the function pointer, and the
	    * format string for sysctl(8).
	    */
	   SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
	       CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
	       "");

SYSCTL NAMING
     When  adding,  modifying,	or  removing sysctl names, it is important to be
     aware that these interfaces may be used by users, libraries,  applications,
     or  documentation	(such  as published books), and are implicitly published
     application interfaces.  As with other application interfaces, caution must
     be taken not to break existing applications, and to think about future  use
     of  new  name spaces so as to avoid the need to rename or remove interfaces
     that might be depended on in the future.

     The semantics chosen for a new sysctl should be as clear as  possible,  and
     the  name	of the sysctl must closely reflect its semantics.  Therefore the
     sysctl name deserves a fair amount of consideration.  It  should  be  short
     but yet representative of the sysctl meaning.  If the name consists of sev-
     eral  words,  they  should  be  separated	by  underscore characters, as in
     compute_summary_at_mount.	Underscore characters may be omitted only if the
     name consists of not more than two words, each being not longer  than  four
     characters,  as in bootfile.  For boolean sysctls, negative logic should be
     totally  avoided.	 That  is,  do	not  use   names   like   no_foobar   or
     foobar_disable.   They are confusing and lead to configuration errors.  Use
     positive logic instead: foobar, foobar_enable.

     A temporary sysctl node that should not be relied upon must  be  designated
     as  such  by  a  leading  underscore  character  in its name.  For example:
     _dirty_hack.

SEE ALSO
     sysctl(8),   sysctl_add_oid(9),   sysctl_ctx_free(9),   sysctl_ctx_init(9),
     sysctl_remove_oid(9)

HISTORY
     The sysctl(8) utility first appeared in 4.4BSD.

AUTHORS
     The  sysctl  implementation  originally  found  in BSD has been extensively
     rewritten by Poul-Henning Kamp in order to add support  for  name	lookups,
     name space iteration, and dynamic addition of MIB nodes.

     This man page was written by Robert N. M. Watson.

FreeBSD 7.0			November 23, 2006		       SYSCTL(9)

home | help