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

FreeBSD Manual Pages


home | help
SYSCTL(8)		  BSD System Manager's Manual		     SYSCTL(8)

     sysctl -- get or set kernel state

     sysctl [-AdeMnq] [-r | -x]	[name ...]
     sysctl [-nq] [-r |	-x] -w name[?]=value ...
     sysctl [-en] [-r |	-x] -a
     sysctl [-nq] [-r |	-x] -f file

     The sysctl	utility	retrieves kernel state and allows processes with ap-
     propriate privilege to set	kernel state.  The state to be retrieved or
     set is described using a ``Management Information Base'' (``MIB'')	style
     name, described as	a dotted set of	components.  The `/' character may
     also be used as a separator and a leading separator character is ac-
     cepted.  If name specifies	a non-leaf node	in the MIB, all	the nodes un-
     derneath name will	be printed.

     The following options are available:

     -A	     List all the known	MIB names including tables, unless any MIB ar-
	     guments or	-f file	are given.  Those with string or integer val-
	     ues will be printed as with the -a	flag; for table	or structure
	     values that sysctl	is not able to print, the name of the utility
	     to	retrieve them is given.	 Errors	in retrieving or setting val-
	     ues will be directed to stdout instead of stderr.

     -a	     List all the currently available string or	integer	values.	 The
	     use of a solitary separator character (either `.' or `/') by it-
	     self has the same effect.	Any given name arguments are ignored
	     if	this option is specified.

     -d	     Descriptions of each of the nodes selected	will be	printed	in-
	     stead of their values.

     -e	     Separate the name and the value of	the variable(s)	with `='.
	     This is useful for	producing output which can be fed back to the
	     sysctl utility.  This option is ignored if	-n is specified	or a
	     variable is being set.

     -f	     Specifies the name	of a file to read and process.	Blank lines
	     and comments (beginning with `#') are ignored.  Line continua-
	     tions with	`\' are	permitted.  Remaining lines are	processed sim-
	     ilarly to command line arguments of the form name or name=value.
	     The -w flag is implied by -f.  Any	name arguments are ignored.

     -M	     Makes sysctl print	the MIB	instead	of any of the actual values
	     contained in the MIB.  This causes	the entire MIB to be printed
	     unless specific MIB arguments or -f file are also given.

     -n	     Specifies that the	printing of the	field name should be sup-
	     pressed and that only its value should be output.	This flag is
	     useful for	setting	shell variables.  For example, to save the pa-
	     gesize in variable	psize, use:
		   set psize=`sysctl -n	hw.pagesize`

     -q	     Used to indicate that nothing should be printed for reads or
	     writes unless an error is detected.  For reads, not finding a
	     variable does not print an	error, but exits with an error code.
	     This is useful just for testing that a variable exists.

     -r	     Raw output	form.  Values printed are in their raw binary forms as
	     retrieved directly	from the kernel.  Some additional nodes	that
	     sysctl cannot print directly can be retrieved with	this flag.
	     This option conflicts with	the -x option.

     -w	     Sets the MIB style	name given to the value	given.	The MIB	style
	     name and value must be separated by `=' with no whitespace.  To
	     prevent an	error if the MIB style name does not exist (as would
	     be	the case with optional kernel components), one can separate
	     the MIB style name	and the	value with `?='.  Only integral	and
	     string values can be set via this method.

     -x	     Makes sysctl print	the requested value in a hexadecimal represen-
	     tation instead of its regular form.  If specified more than once,
	     the output	for each value resembles that of hexdump(1) when given
	     the -C flag.  This	option conflicts with the -r option.

     The `proc'	top-level MIB has a special semantic: it represent per-process
     values and	as such	may differ from	one process to another.	 The second-
     level name	is the pid of the process (in decimal form), or	the special
     word `curproc'.  For variables below `proc.<pid>.rlimit', the integer
     value may be replaced with	the string `unlimited' if it matches the magic
     value used	to disable a limit.

     The information available from sysctl consists of integers, strings, and
     tables.  The tabular information can only be retrieved by special purpose
     programs such as ps, systat, and netstat.	See sysctl(7) for description
     of	available MIBs.

     New nodes are allowed to be created by the	superuser when the kernel is
     running at	security level 0.  These new nodes may refer to	existing ker-
     nel data or to new	data that is only instrumented by sysctl(3) itself.

     The syntax	for creating new nodes is "//create=new.node.path" followed by
     one or more of the	following attributes separated by commas.  The use of
     a double separator	(both `/' and `.' can be used as separators) as	the
     prefix tells sysctl that the first	series of tokens is not	a MIB name,
     but a command.  It	is recommended that the	double separator preceding the
     command not be the	same as	the separator used in naming the MIB entry so
     as	to avoid possible parse	conflicts.  The	"value"	assigned, if one is
     given, must be last.

     +o	 type=<T> where	T must be one of "node", "int",	"string", "quad", or
	 "struct".  If the type	is omitted, the	"node" type is assumed.
     +o	 size=<S> here,	S asserts the size of the new node.  Nodes of type
	 "node"	should not have	a size set.  The size may be omitted for nodes
	 of types "int"	or "quad".  If the size	is omitted for a node of type
	 "string", the size will be determined by the length of	the given
	 value,	or by the kernel for kernel strings.  Nodes of type "struct"
	 must have their size explicitly set.
     +o	 addr=<A> or symbol=<A>	The kernel address of the data being instru-
	 mented.  If "symbol" is used, the symbol must be globally visible to
	 the in-kernel ksyms(4)	driver.
     +o	 n=<N> The MIB number to be assigned to	the new	node.  If no number is
	 specified, the	kernel will assign a value.
     +o	 flags=<F> A concatenated string of single letters that	govern the be-
	 havior	of the node.  Flags currently available	are:

	 a    Allow anyone to write to the node, if it is writable.

	 h    "Hidden".	 sysctl	must be	invoked	with -A	or the hidden node
	      must be specifically requested in	order to see it

	 i    "Immediate".  Makes the node store data in itself, rather	than
	      allocating new space for it.  This is the	default	for nodes of
	      type "int" and "quad".  This is the opposite of owning data.

	 o    "Own".  When the node is created,	separate space will be allo-
	      cated to store the data to be instrumented.  This	is the default
	      for nodes	of type	"string" and "struct" where it is not possible
	      to guarantee sufficient space to store the data in the node it-

	 p    "Private".  Nodes	that are marked	private, and children of nodes
	      so marked, are only viewable by the superuser.  Be aware that
	      the immediate data that some nodes may store is not necessarily
	      protected	by this.

	 x    "Hexadecimal".  Make sysctl default to hexadecimal display of
	      the retrieved value

	 r    "Read-only".  The	data instrumented by the given node is read-
	      only.  Note that other mechanisms	may still exist	for changing
	      the data.	 This is the default for nodes that instrument data.

	 w    "Writable".  The data instrumented by the	given node is writable
	      at any time.  This is the	default	for nodes that can have	chil-

     +o	 value=<V> An initial starting value for a new node that does not ref-
	 erence	existing kernel	data.  Initial values can only be assigned for
	 nodes of the "int", "quad", and "string" types.

     New nodes must fit	the following set of criteria:

     +o	 If the	new node is to address an existing kernel object, only one of
	 the "symbol" or "addr"	arguments may be given.
     +o	 The size for a	"struct" type node must	be specified; no initial value
	 is expected or	permitted.
     +o	 Either	the size or the	initial	value for a "string" node must be
     +o	 The node which	will be	the parent of the new node must	be writable.

     If	any of the given parameters describes an invalid configuration,	sysctl
     will emit a diagnostic message to the standard error and exit.

     Descriptions can be added by the super-user to any	node that does not
     have one, provided	that the node is not marked with the "PERMANENT" flag.
     The syntax	is similar to the syntax for creating new nodes	with the ex-
     ception of	the keyword that follows the double separator at the start of
     the command: "//describe=new.node.path=new	node description".  Once a de-
     scription has been	added, it cannot be changed or removed.

     When destroying nodes, only the path to the node is necessary, i.e.,
     "//destroy=old.node.path".	 No other parameters are expected or permit-
     ted.  Nodes being destroyed must have no children,	and their parent must
     be	writable.  Nodes that are marked with the "PERMANENT" flag (as as-
     signed by the kernel) may not be deleted.

     In	all cases, the initial `=' that	follows	the command (eg, "create",
     "destroy",	or "describe") may be replaced with another instance of	the
     separator character, provided that	the same separator character is	used
     for the length of the name	specification.

     /etc/sysctl.conf  sysctl variables	set at boot time

     For example, to retrieve the maximum number of processes allowed in the
     system, one would use the following request:
	   sysctl kern.maxproc

     To	set the	maximum	number of processes allowed in the system to 1000, one
     would use the following request:
	   sysctl -w kern.maxproc=1000

     Information about the system clock	rate may be obtained with:
	   sysctl kern.clockrate

     Information about the load	average	history	may be obtained	with:
	   sysctl vm.loadavg

     To	view the values	of the per-process variables of	the current shell, the
	   sysctl proc.$$
     can be used if the	shell interpreter replaces $$ with its pid (this is
     true for most shells).

     To	redirect core dumps to the /var/tmp/<username> directory,
	   sysctl -w proc.$$.corename=/var/tmp/%u/%n.core
     should be used.
	   sysctl -w proc.curproc.corename=/var/tmp/%u/%n.core
     changes the value for the sysctl process itself, and will not have	the
     desired effect.

     To	create the root	of a new sub-tree called "local" add some children to
     the new node, and some descriptions:
	   sysctl -w //create=local
	   sysctl -w //describe=local=my local sysctl tree
	   sysctl -w //create=local.esm_debug,type=int,symbol=esm_debug,flags=w
	   sysctl -w //describe=local.esm_debug=esm driver debug knob
	   sysctl -w //create=local.audiodebug,type=int,symbol=audiodebug,flags=w
	   sysctl -w //describe=local.audiodebug=generic audio debug knob
     Note that the children are	made writable so that the two debug settings
     in	question can be	tuned arbitrarily.

     To	destroy	that same subtree:
	   sysctl -w //destroy=local.esm_debug
	   sysctl -w //destroy=local.audiodebug
	   sysctl -w //destroy=local

     sysctl(3),	ksyms(4), sysctl(7)

     sysctl first appeared in 4.4BSD.

BSD				August 2, 2011				   BSD


Want to link to this manual page? Use this URL:

home | help