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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SYSCTL(9)	       FreeBSD 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
     being 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 function, 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
		     array.

     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
		      securelevel 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	secu-
     rity implications of the monitoring or management interface being cre-
     ated.  Most sysctls present in the	kernel are read-only or	writable only
     by	the superuser.	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, applica-
     tions, 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
     several 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	10.1		       November	23, 2006		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SYSCTL NAMING | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=9&manpath=FreeBSD+7.0-RELEASE>

home | help