| <html lang="en"> |
| <head> |
| <title>System Parameters - The GNU C Library</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The GNU C Library"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="System-Management.html#System-Management" title="System Management"> |
| <link rel="prev" href="Filesystem-Handling.html#Filesystem-Handling" title="Filesystem Handling"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU C library. |
| |
| This is Edition 0.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="System-Parameters"></a> |
| <p> |
| Previous: <a rel="previous" accesskey="p" href="Filesystem-Handling.html#Filesystem-Handling">Filesystem Handling</a>, |
| Up: <a rel="up" accesskey="u" href="System-Management.html#System-Management">System Management</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">30.4 System Parameters</h3> |
| |
| <p>This section describes the <code>sysctl</code> function, which gets and sets |
| a variety of system parameters. |
| |
| <p>The symbols used in this section are declared in the file <samp><span class="file">sysctl.h</span></samp>. |
| |
| <!-- sysctl.h --> |
| <!-- BSD --> |
| <div class="defun"> |
| — Function: int <b>sysctl</b> (<var>int *names, int nlen, void *oldval, size_t *oldlenp, void *newval, size_t newlen</var>)<var><a name="index-sysctl-3494"></a></var><br> |
| <blockquote> |
| <p><code>sysctl</code> gets or sets a specified system parameter. There are so |
| many of these parameters that it is not practical to list them all here, |
| but here are some examples: |
| |
| <ul> |
| <li>network domain name |
| <li>paging parameters |
| <li>network Address Resolution Protocol timeout time |
| <li>maximum number of files that may be open |
| <li>root filesystem device |
| <li>when kernel was built |
| </ul> |
| |
| <p>The set of available parameters depends on the kernel configuration and |
| can change while the system is running, particularly when you load and |
| unload loadable kernel modules. |
| |
| <p>The system parameters with which <code>syslog</code> is concerned are arranged |
| in a hierarchical structure like a hierarchical filesystem. To identify |
| a particular parameter, you specify a path through the structure in a |
| way analogous to specifying the pathname of a file. Each component of |
| the path is specified by an integer and each of these integers has a |
| macro defined for it by <samp><span class="file">sysctl.h</span></samp>. <var>names</var> is the path, in |
| the form of an array of integers. Each component of the path is one |
| element of the array, in order. <var>nlen</var> is the number of components |
| in the path. |
| |
| <p>For example, the first component of the path for all the paging |
| parameters is the value <code>CTL_VM</code>. For the free page thresholds, the |
| second component of the path is <code>VM_FREEPG</code>. So to get the free |
| page threshold values, make <var>names</var> an array containing the two |
| elements <code>CTL_VM</code> and <code>VM_FREEPG</code> and make <var>nlen</var> = 2. |
| |
| <p>The format of the value of a parameter depends on the parameter. |
| Sometimes it is an integer; sometimes it is an ASCII string; sometimes |
| it is an elaborate structure. In the case of the free page thresholds |
| used in the example above, the parameter value is a structure containing |
| several integers. |
| |
| <p>In any case, you identify a place to return the parameter's value with |
| <var>oldval</var> and specify the amount of storage available at that |
| location as *<var>oldlenp</var>. *<var>oldlenp</var> does double duty because it |
| is also the output location that contains the actual length of the |
| returned value. |
| |
| <p>If you don't want the parameter value returned, specify a null pointer |
| for <var>oldval</var>. |
| |
| <p>To set the parameter, specify the address and length of the new value |
| as <var>newval</var> and <var>newlen</var>. If you don't want to set the parameter, |
| specify a null pointer as <var>newval</var>. |
| |
| <p>If you get and set a parameter in the same <code>sysctl</code> call, the value |
| returned is the value of the parameter before it was set. |
| |
| <p>Each system parameter has a set of permissions similar to the |
| permissions for a file (including the permissions on directories in its |
| path) that determine whether you may get or set it. For the purposes of |
| these permissions, every parameter is considered to be owned by the |
| superuser and Group 0 so processes with that effective uid or gid may |
| have more access to system parameters. Unlike with files, the superuser |
| does not invariably have full permission to all system parameters, because |
| some of them are designed not to be changed ever. |
| |
| <p><code>sysctl</code> returns a zero return value if it succeeds. Otherwise, it |
| returns <code>-1</code> and sets <code>errno</code> appropriately. Besides the |
| failures that apply to all system calls, the following are the |
| <code>errno</code> codes for all possible failures: |
| |
| <dl> |
| <dt><code>EPERM</code><dd>The process is not permitted to access one of the components of the |
| path of the system parameter or is not permitted to access the system parameter |
| itself in the way (read or write) that it requested. |
| <!-- There is some indication in the Linux 2.2 code that the code is trying to --> |
| <!-- return EACCES here, but the EACCES value never actually makes it to the --> |
| <!-- user. --> |
| <br><dt><code>ENOTDIR</code><dd>There is no system parameter corresponding to <var>name</var>. |
| <br><dt><code>EFAULT</code><dd><var>oldval</var> is not null, which means the process wanted to read the parameter, |
| but *<var>oldlenp</var> is zero, so there is no place to return it. |
| <br><dt><code>EINVAL</code><dd> |
| <ul> |
| <li>The process attempted to set a system parameter to a value that is not valid |
| for that parameter. |
| <li>The space provided for the return of the system parameter is not the right |
| size for that parameter. |
| </ul> |
| <br><dt><code>ENOMEM</code><dd>This value may be returned instead of the more correct <code>EINVAL</code> in some |
| cases where the space provided for the return of the system parameter is too |
| small. |
| |
| </dl> |
| |
| </blockquote></div> |
| |
| <p>If you have a Linux kernel with the <code>proc</code> filesystem, you can get |
| and set most of the same parameters by reading and writing to files in |
| the <code>sys</code> directory of the <code>proc</code> filesystem. In the <code>sys</code> |
| directory, the directory structure represents the hierarchical structure |
| of the parameters. E.g. you can display the free page thresholds with |
| <pre class="smallexample"> cat /proc/sys/vm/freepages |
| </pre> |
| <!-- In Linux, the sysctl() and /proc instances of the parameter are created --> |
| <!-- together. The proc filesystem accesses the same data structure as --> |
| <!-- sysctl(), which has special fields in it for /proc. But it is still --> |
| <!-- possible to create a sysctl-only parameter. --> |
| <p>Some more traditional and more widely available, though less general, |
| GNU C library functions for getting and setting some of the same system |
| parameters are: |
| |
| <ul> |
| <li><code>getdomainname</code>, <code>setdomainname</code> |
| <li><code>gethostname</code>, <code>sethostname</code> (See <a href="Host-Identification.html#Host-Identification">Host Identification</a>.) |
| <li><code>uname</code> (See <a href="Platform-Type.html#Platform-Type">Platform Type</a>.) |
| <li><code>bdflush</code> |
| </ul> |
| |
| </body></html> |
| |
