Update.
[kopensolaris-gnu/glibc.git] / manual / sysinfo.texi
index 5bce9a5..ee5009b 100644 (file)
-@node System Information, System Configuration, Users and Groups, Top
-@c %MENU% Getting information about the hardware and operating system
-@chapter System Information
+@node System Management, System Configuration, Users and Groups, Top
+@c %MENU% Controlling the system and getting information about it
+@chapter System Management
+
+This chapter describes facilities for controlling the system that
+underlies a process (including the operating system and hardware) and
+for getting information about it.  Anyone can generally use the
+informational facilities, but usually only a properly privileged process
+can make changes.
 
-This chapter describes functions that return information about the
-particular machine that is in use---the type of hardware, the type of
-software, and the individual machine's name.
 
 @menu
 * Host Identification::         Determining the name of the machine.
-* Hardware/Software Type ID::   Determining the hardware type of the
-                                 machine and what operating system it is
-                                 running.
-* Filesystem handling::         Which is mounted and/or available?
+* Platform Type::               Determining operating system and basic
+                                  machine type
+* Filesystem Handling::         Controlling/querying mounts
+* System Parameters::           Getting and setting various system parameters
 @end menu
 
+To get information on parameters of the system that are built into the
+system, such as the maximum length of a filename, @ref{System
+Configuration}.
 
 @node Host Identification
 @section Host Identification
 
-This section explains how to identify the particular machine that your
-program is running on.  The identification of a machine consists of its
-Internet host name and Internet address; see @ref{Internet Namespace}.
-The host name should always be a fully qualified domain name, like
-@w{@samp{crispy-wheats-n-chicken.ai.mit.edu}}, not a simple name like
-just @w{@samp{crispy-wheats-n-chicken}}.
+This section explains how to identify the particular system on which your
+program is running.  First, let's review the various ways computer systems
+are named, which is a little complicated because of the history of the
+development of the Internet.
+
+Every Unix system (also known as a host) has a host name, whether it's
+connected to a network or not.  In its simplest form, as used before
+computer networks were an issue, it's just a word like @samp{chicken}.
+@cindex host name
+
+But any system attached to the Internet or any network like it conforms
+to a more rigorous naming convention as part of the Domain Name System
+(DNS).  In DNS, every host name is composed of two parts:
+@cindex DNS
+@cindex Domain Name System
+
+@enumerate
+@item
+hostname
+@cindex hostname
+@item
+domain name
+@cindex domain name
+@end enumerate
+
+You will note that ``hostname'' looks a lot like ``host name'', but is
+not the same thing, and that people often incorrectly refer to entire
+host names as ``domain names.''
+
+In DNS, the full host name is properly called the FQDN (Fully Qualified
+Domain Name) and consists of the hostname, then a period, then the
+domain name.  The domain name itself usually has multiple components
+separated by periods.  So for example, a system's hostname may be
+@samp{chicken} and its domain name might be @samp{ai.mit.edu}, so
+its FQDN (which is its host name) is @samp{chicken.ai.mit.edu}.
+@cindex FQDN
+
+Adding to the confusion, though, is that DNS is not the only name space
+in which a computer needs to be known.  Another name space is the
+NIS (aka YP) name space.  For NIS purposes, there is another domain
+name, which is called the NIS domain name or the YP domain name.  It
+need not have anything to do with the DNS domain name.
+@cindex YP
+@cindex NIS
+@cindex NIS domain name
+@cindex YP domain name
+
+Confusing things even more is the fact that in DNS, it is possible for
+multiple FQDNs to refer to the same system.  However, there is always
+exactly one of them that is the true host name, and it is called the
+canonical FQDN.
+
+In some contexts, the host name is called a ``node name.''
+
+For more information on DNS host naming, @xref{Host Names}.
 
 @pindex hostname
 @pindex hostid
 @pindex unistd.h
-Prototypes for these functions appear in @file{unistd.h}.  The shell
-commands @code{hostname} and @code{hostid} work by calling them.
+Prototypes for these functions appear in @file{unistd.h}.
+
+The programs @code{hostname}, @code{hostid}, and @code{domainname} work
+by calling these functions.
 
 @comment unistd.h
 @comment BSD
 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
-This function returns the name of the host machine in the array
-@var{name}.  The @var{size} argument specifies the size of this array,
-in bytes.
+This function returns the host name of the system on which it is called,
+in the array @var{name}.  The @var{size} argument specifies the size of
+this array, in bytes.  Note that this is @emph{not} the DNS hostname.
+If the system participates in DNS, this is the FQDN (see above).
 
 The return value is @code{0} on success and @code{-1} on failure.  In
 the GNU C library, @code{gethostname} fails if @var{size} is not large
@@ -63,10 +121,17 @@ error code.
 @comment unistd.h
 @comment BSD
 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
-The @code{sethostname} function sets the name of the host machine to
-@var{name}, a string with length @var{length}.  Only privileged
-processes are allowed to do this.  Usually it happens just once, at
-system boot time.
+The @code{sethostname} function sets the host name of the system that
+calls it to @var{name}, a string with length @var{length}.  Only
+privileged processes are permitted to do this.
+
+Usually @code{sethostname} gets called just once, at system boot time.
+Often, the program that calls it sets it to the value it finds in the
+file @code{/etc/hostname}.
+@cindex /etc/hostname
+
+Be sure to set the host name to the full host name, not just the DNS
+hostname (see above).
 
 The return value is @code{0} on success and @code{-1} on failure.
 The following @code{errno} error condition is defined for this function:
@@ -78,22 +143,64 @@ This process cannot set the host name because it is not privileged.
 @end deftypefun
 
 @comment unistd.h
+@comment ???
+@deftypefun int getdomainnname (char *@var{name}, size_t @var{length})
+@cindex NIS domain name
+@cindex YP domain name
+
+@code{getdomainname} returns the NIS (aka YP) domain name of the system
+on which it is called.  Note that this is not the more popular DNS
+domain name.  Get that with @code{gethostname}.
+
+The specifics of this function are analogous to @code{gethostname}, above.
+
+@end deftypefun
+
+@comment unistd.h
+@comment ???
+@deftypefun int setdomainnname (const char *@var{name}, size_t @var{length})
+@cindex NIS domain name
+@cindex YP domain name
+
+@code{getdomainname} sets the NIS (aka YP) domain name of the system
+on which it is called.  Note that this is not the more popular DNS
+domain name.  Set that with @code{sethostname}.
+
+The specifics of this function are analogous to @code{sethostname}, above.
+
+@end deftypefun
+
+@comment unistd.h
 @comment BSD
 @deftypefun {long int} gethostid (void)
 This function returns the ``host ID'' of the machine the program is
-running on.  By convention, this is usually the primary Internet address
+running on.  By convention, this is usually the primary Internet IP address
 of that machine, converted to a @w{@code{long int}}.  However, on some
 systems it is a meaningless but unique number which is hard-coded for
 each machine.
+
+This is not widely used.  It arose in BSD 4.2, but was dropped in BSD 4.4.
+It is not required by POSIX.
+
+The proper way to query the IP address is to use @code{gethostbyname}
+on the results of @code{gethostname}.  For more information on IP addresses,
+@xref{Host Addresses}.
 @end deftypefun
 
 @comment unistd.h
 @comment BSD
 @deftypefun int sethostid (long int @var{id})
 The @code{sethostid} function sets the ``host ID'' of the host machine
-to @var{id}.  Only privileged processes are allowed to do this.  Usually
+to @var{id}.  Only privileged processes are permitted to do this.  Usually
 it happens just once, at system boot time.
 
+The proper way to establish the primary IP address of a system
+is to configure the IP address resolver to associate that IP address with
+the system's host name as returned by @code{gethostname}.  For example,
+put a record for the system in @file{/etc/hosts}.
+
+See @code{gethostid} above for more information on host ids.
+
 The return value is @code{0} on success and @code{-1} on failure.
 The following @code{errno} error conditions are defined for this function:
 
@@ -108,8 +215,8 @@ each machine.
 @end table
 @end deftypefun
 
-@node Hardware/Software Type ID
-@section Hardware/Software Type Identification
+@node Platform Type
+@section Platform Type Identification
 
 You can use the @code{uname} function to find out some information about
 the type of computer your program is running on.  This function and the
@@ -117,6 +224,12 @@ associated data type are declared in the header file
 @file{sys/utsname.h}.
 @pindex sys/utsname.h
 
+As a bonus, @code{uname} also gives some information identifying the
+particular system your program is running on.  This is the same information
+which you can get with functions targetted to this purpose described in
+@ref{Host Identification}.
+
+
 @comment sys/utsname.h
 @comment POSIX.1
 @deftp {Data Type} {struct utsname}
@@ -127,11 +240,6 @@ by the @code{uname} function.  It has the following members:
 @item char sysname[]
 This is the name of the operating system in use.
 
-@item char nodename[]
-This is the network name of this particular computer.  In the GNU
-library, the value is the same as that returned by @code{gethostname};
-see @ref{Host Identification}.
-
 @item char release[]
 This is the current release level of the operating system implementation.
 
@@ -166,6 +274,22 @@ hardware, it consists of the first two parts of the configuration name:
 @code{"m68k-sun"},
 @code{"mips-dec"}
 @end quotation
+
+@item char nodename[]
+This is the host name of this particular computer.  In the GNU C
+library, the value is the same as that returned by @code{gethostname};
+see @ref{Host Identification}.
+
+@ gethostname() is implemented with a call to uname().
+
+@item char domainname[]
+This is the NIS or YP domain name.  It is the same value returned by
+@code{getdomainname}; see @ref{Host Identification}.  This element
+is a relatively recent invention and use of it is not as portable as
+use of the rest of the structure.
+
+@c getdomainname() is implemented with a call to uname().
+
 @end table
 @end deftp
 
@@ -182,15 +306,45 @@ possibility.
 @end deftypefun
 
 
-@node Filesystem handling
-@section Which filesystems are mounted and/or available?
+@node Filesystem Handling
+@section Controlling and Querying Mounts
+
+All files are in filesystems, and before you can access any file, its
+filesystem must be mounted.  Because of Unix's concept of
+@emph{Everything is a file}, mounting of filesystems is central to doing
+almost anything.  This section explains how to find out what filesystems
+are currently mounted and what filesystems are available for mounting,
+and how to change what is mounted.
+
+The classic filesystem is the contents of a disk drive.  The concept is
+considerably more abstract, though, and lots of things other than disk
+drives can be mounted.
 
-The Unix concept of @emph{Everything is a file} is based on the
-ability to @dfn{mount} filesystems or other things into the
-filesystem.  For some programs it is desirable and necessary to access
-information about whether a certain filesystem is mounted and, if it is, 
-where, or simply to get lists of all the available filesystems.  The
-GNU libc provides some functions to retrieve this information portably.
+Some block devices don't correspond to traditional devices like disk
+drives.  For example, a loop device is a block device whose driver uses
+a regular file in another filesystem as its medium.  So if that regular
+file contains appropriate data for a filesystem, you can by mounting the
+loop device essentially mount a regular file.
+
+Some filesystems aren't based on a device of any kind.  The ``proc''
+filesystem, for example, contains files whose data is made up by the
+filesystem driver on the fly whenever you ask for it.  And when you
+write to it, the data you write causes changes in the system.  No data
+gets stored.
+
+@c It would be good to mention NFS mounts here.
+
+@menu
+* Mount Information::           What is or could be mounted?
+* Mount-Unmount-Remount::       Controlling what is mounted and how
+@end menu
+
+@node Mount Information, Mount-Unmount-Remount, , Filesystem Handling
+
+For some programs it is desirable and necessary to access information
+about whether a certain filesystem is mounted and, if it is, where, or
+simply to get lists of all the available filesystems.  The GNU libc
+provides some functions to retrieve this information portably.
 
 Traditionally Unix systems have a file named @file{/etc/fstab} which
 describes all possibly mounted filesystems.  The @code{mount} program
@@ -203,6 +357,13 @@ functions described in this section can do this and they also provide
 the functionality to convert the external textual representation to the
 internal representation.
 
+Note that the @file{fstab} and @file{mtab} files are maintained on a
+system by @emph{convention}.  It is possible for the files not to exist
+or not to be consistent with what is really mounted or available to
+mount, if the system's administration policy allows it.  But programs
+that mount and unmount filesystems typically maintain and use these
+files as described herein.
+
 @vindex _PATH_FSTAB
 @vindex _PATH_MNTTAB
 @vindex FSTAB
@@ -215,6 +376,15 @@ defined in @file{fstab.h} and @code{_PATH_MNTTAB}, defined in
 deprecated and kept only for backward compatibility.  The two former
 names should always be used.
 
+@menu
+* fstab::                       The @file{fstab} file
+* mtab::                        The @file{mtab} file
+* Other Mount Information::     Other (non-libc) sources of mount information
+@end menu
+
+@node fstab
+@subsection The @file{fstab} file
+
 The internal representation for entries of the file is @w{@code{struct
 fstab}}, defined in @file{fstab.h}.
 
@@ -363,11 +533,12 @@ function is not thread-safe.  If an error occurred @code{getfsent}
 returns a @code{NULL} pointer.
 @end deftypefun
 
-To access the @file{mtab} file there is a different set of functions and
-also a different structure to describe the results.
 
+@node mtab
+@subsection The @file{mtab} file
+The following functions and data structure access the @file{mtab} file.
 
-@comment fstab.h
+@comment mntent.h
 @comment BSD
 @deftp {Data Type} {struct mntent}
 This structure is used with the @code{getmntent}, @code{getmntent_t},
@@ -572,3 +743,450 @@ This function is useful to test whether a specific option is present but
 when all options have to be processed one is better off with using the
 @code{getsubopt} function to iterate over all options in the string.
 @end deftypefun
+
+@node Other Mount Information
+@subsection Other (Non-libc) Sources of Mount Information
+
+On a system with a Linux kernel and the @code{proc} filesystem, you can
+get information on currently mounted filesystems from the file
+@file{mounts} in the @code{proc} filesystem.  Its format is similar to
+that of the @file{mtab} file, but represents what is truly mounted
+without relying on facilities outside the kernel to keep @file{mtab} up
+to date.
+
+
+@node Mount-Unmount-Remount, , Mount Information, Filesystem Handling
+
+This section describes the functions for mounting, unmounting, and
+remounting filesystems.
+
+Only the superuser can mount, unmount, or remount a filesystem.
+
+These functions do not access the @file{fstab} and @file{mtab} files.  You
+should maintain and use these separately.  @xref{Mount Information}.
+
+The symbols in this section are declared in @file{sys/mount.h}.
+
+@comment sys/mount.h
+@comment SVID, BSD
+@deftypefun {int} mount (const char *@var{special_file}, const char *@var{dir}, const char *@var{fstype}, unsigned long int @var{options}, const void *@var{data})
+
+@code{mount} mounts or remounts a filesystem.  The two operations are
+quite different and are merged rather unnnaturally into this one function.
+The @code{MS_REMOUNT} option, explained below, determines whether
+@code{mount} mounts or remounts.
+
+For a mount, the filesystem on the block device represented by the
+device special file named @var{special_file} gets mounted over the mount
+point @var{dir}.  This means that the directory @var{dir} (along with any
+files in it) is no longer visible; in its place (and still with the name
+@var{dir}) is the root directory of the filesystem on the device.
+
+As an exception, if the filesystem type (see below) is one which is not
+based on a device (e.g. ``proc''), @code{mount} instantiates a
+filesystem and mounts it over @var{dir} and ignores @var{special_file}.
+
+For a remount, @var{dir} specifies the mount point where the filesystem
+to be remounted is (and remains) mounted and @var{special_file} is
+ignored.  Remounting a filesystem means changing the options that control
+operations on the filesystem while it is mounted.  It does not mean
+unmounting and mounting again.
+
+For a mount, you must identify the type of the filesystem as
+@var{fstype}.  This type tells the kernel how to access the filesystem
+and can be thought of as the name of a filesystem driver.  The
+acceptable values are system dependent.  On a system with a Linux kernel
+and the @code{proc} filesystem, the list of possible values is in the
+file @file{filesystems} in the @code{proc} filesystem (e.g. type
+@kbd{cat /proc/filesystems} to see the list).  With a Linux kernel, the
+types of filesystems that @code{mount} can mount, and their type names,
+depends on what filesystem drivers are configured into the kernel or
+loaded as loadable kernel modules.  An example of a common value for
+@var{fstype} is @code{ext2}.
+
+For a remount, @code{mount} ignores @var{fstype}.
+
+@c This is traditionally called "rwflag" for historical reasons.
+@c No point in confusing people today, though.
+@var{options} specifies a variety of options that apply until the
+filesystem is unmounted or remounted.  The precise meaning of an option
+depends on the filesystem and with some filesystems, an option may have
+no effect at all.  Furthermore, for some filesystems, some of these
+options (but never @code{MS_RDONLY}) can be overridden for individual
+file accesses via @code{ioctl}.
+
+@var{options} is a bit string with bit fields defined using the
+following mask and masked value macros:
+
+@table @code
+@item MS_MGC_MASK
+This multibit field contains a magic number.  If it does not have the value
+@code{MS_MGC_VAL}, @code{mount} assumes all the following bits are zero and
+the @var{data} argument is a null string, regardless of their actual values.
+
+@item MS_REMOUNT
+This bit on means to remount the filesystem.  Off means to mount it.
+@c There is a mask MS_RMT_MASK in mount.h that says only two of the options
+@c can be reset by remount.  But the Linux kernel has its own version of
+@c MS_RMT_MASK that says they all can be reset.  As far as I can tell,
+@c libc just passes the arguments straight through to the kernel.
+
+@item MS_RDONLY
+This bit on specifies that no writing to the filesystem shall be allowed
+while it is mounted.  This cannot be overridden by @code{ioctl}.  This
+option is available on nearly all filesystems.
+
+@item S_IMMUTABLE
+This bit on specifies that no writing to the files in the filesystem
+shall be allowed while it is mounted.  This can be overridden for a
+particular file access by a properly privileged call to @code{ioctl}.
+This option is a relatively new invention and is not available on many
+filesystems.
+
+@item S_APPEND
+This bit on specifies that the only file writing that shall be allowed
+while the filesystem is mounted is appending.  Some filesystems allow
+this to be overridden for a particular process by a properly privileged
+call to @code{ioctl}.  This is a relatively new invention and is not
+available on many filesystems.
+
+@item MS_NOSUID
+This bit on specifies that Setuid and Setgid permissions on files in the
+filesystem shall be ignored while it is mounted.
+
+@item MS_NOEXEC
+This bit on specifies that no files in the filesystem shall be executed
+while the filesystem is mounted.
+
+@item MS_NODEV
+This bit on specifies that no device special files in the filesystem
+shall be accessible while the filesystem is mounted.
+
+@item MS_SYNCHRONOUS
+This bit on specifies that all writes to the filesystem while it is
+mounted shall be synchronous; i.e. data shall be synced before each
+write completes rather than held in the buffer cache.
+
+@item MS_MANDLOCK
+This bit on specifies that mandatory locks on files shall be permitted while
+the filesystem is mounted.
+
+@item MS_NOATIME
+This bit on specifies that access times of files shall not be updated when
+the files are accessed while the filesystem is mounted.
+
+@item MS_NODIRATIME
+This bit on specifies that access times of directories shall not be updated
+when the directories are accessed while the filesystem in mounted.
+
+@c there is also S_QUOTA Linux fs.h (mount.h still uses its former name
+@c S_WRITE), but I can't see what it does.  Turns on quotas, I guess.
+
+@end table
+
+Any bits not covered by the above masks should be set off; otherwise,
+results are undefined.
+
+The meaning of @var{data} depends on the filesystem type and is controlled
+entirely by the filesystem driver in the kernel.
+
+Example:
+
+@smallexample
+@group
+#include <sys/mount.h>
+
+mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");
+
+mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
+
+@end group
+@end smallexample
+
+Appropriate arguments for @code{mount} are conventionally recorded in
+the @file{fstab} table.  @xref{Mount Information}.
+
+The return value is zero if the mount or remount is successful.  Otherwise,
+it is @code{-1} and @code{errno} is set appropriately.  The values of
+@code{errno} are filesystem dependent, but here is a general list:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@item ENODEV
+The file system type @var{fstype} is not known to the kernel.
+@item ENOTBLK
+The file @var{dev} is not a block device special file.
+@item EBUSY
+
+@itemize @bullet
+
+@item
+The device is already mounted.
+
+@item
+The mount point is busy.  (E.g. it is some process' working directory or
+has a filesystem mounted on it already).
+
+@item
+The request is to remount read-only, but there are files open for write.
+@end itemize
+
+@item EINVAL
+@itemize @bullet
+
+@item
+A remount was attempted, but there is no filesystem mounted over the
+specified mount point.
+
+@item
+The supposed filesystem has an invalid superblock.
+
+@end itemize
+
+@item EACCESS
+@itemize @bullet
+
+@item
+The filesystem is inherently read-only (possibly due to a switch on the
+device) and the process attempted to mount it read/write (by setting the
+@code{MS_RDONLY} bit off).
+
+@item
+@var{special_file} or @var{dir} is not accessible due to file permissions.
+
+@item
+@var{special_file} is not accessible because it is in a filesystem that is
+mounted with the @code{MS_NODEV} option.
+
+@end itemize
+
+@item EM_FILE
+The table of dummy devices is full.  @code{mount} needs to create a
+dummy device (aka ``unnamed'' device) if the filesystem being mounted is
+not one that uses a device.
+
+@end table
+
+@end deftypefun
+
+
+@comment sys/mount.h
+@comment GNU
+@deftypefun {int} umount2 (const char *@var{file}, int @var{flags})
+
+@code{umount2} unmounts a filesystem.
+
+You can identify the filesystem to unmount either by the device special
+file that contains the filesystem or by the mount point.  The effect is
+the same.  Specify either as the string @var{file}.
+
+@var{flags} contains the one-bit field identified by the following
+mask macro:
+
+@table @code
+
+@item MNT_FORCE
+This bit on means to force the unmounting even if the filesystem is
+busy, by making it unbusy first.  If the bit is off and the filesystem is
+busy, @code{umount2} fails with @code{errno} = @code{EBUSY}.  Depending
+on the filesystem, this may override all, some, or no busy conditions.
+
+@end table
+
+All other bits in @var{flags} should be set to zero; otherwise, the result
+is undefined.
+
+Example:
+
+@smallexample
+@group
+#include <sys/mount.h>
+
+umount2("/mnt", MNT_FORCE);
+
+umount2("/dev/hdd1", 0);
+
+@end group
+@end smallexample
+
+After the filesystem is unmounted, the directory that was the mount point
+is visible, as are any files in it.
+
+As part of unmounting, @code{umount2} syncs the filesystem.
+
+If the unmounting is successful, the return value is zero.  Otherwise, it
+is @code{-1} and @code{errno} is set accordingly:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@item EBUSY
+The filesystem cannot be unmounted because it is busy.  E.g. it contains
+a directory that is some process's working directory or a file that some
+process has open.  With some filesystems in some cases, you can avoid
+this failure with the @code{MNT_FORCE} option.
+
+@item EINVAL
+@var{file} validly refers to a file, but that file is neither a mount
+point nor a device special file of a currently mounted filesystem.
+
+@end table
+
+This function is not available on all systems.
+@end deftypefun
+
+@comment sys/mount.h
+@comment SVID, GNU
+@deftypefun {int} umount (const char *@var{file})
+
+@code{umount} does the same thing as @code{umount2} with @var{flags} set
+to zeroes.  It is more widely available than @code{umount2} but since it
+lacks the possibility to forcefully unmount a filesystem is deprecated
+when @code{umount2} is also available.
+@end deftypefun
+
+
+
+@node System Parameters
+@section System Parameters
+
+This section describes the @code{sysctl} function, which gets and sets
+a variety of system parameters.
+
+The symbols used in this section are declared in the file @file{sysctl.h}.
+
+@comment sysctl.h
+@comment BSD
+@deftypefun int sysctl (int *@var{names}, int @var{nlen}, void *@var{oldval},
+        size_t *@var{oldlenp}, void *@var{newval}, size_t @var{newlen})
+
+@code{sysctl} 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:
+
+@itemize @bullet
+@item network domain name
+@item paging parameters
+@item network Address Resolution Protocol timeout time
+@item maximum number of files that may be open
+@item root filesystem device
+@item when kernel was built
+@end itemize
+
+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.
+
+The system parameters with which @code{syslog} 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 @file{sysctl.h}.  @var{names} 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} is the number of components
+in the path.
+
+For example, the first component of the path for all the paging
+parameters is the value @code{CTL_VM}.  For the free page thresholds, the
+second component of the path is @code{VM_FREEPG}.  So to get the free
+page threshold values, make @var{names} an array containing the two
+elements @code{CTL_VM} and @code{VM_FREEPG} and make @var{nlen} = 2.
+
+
+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.
+
+In any case, you identify a place to return the parameter's value with
+@var{oldval} and specify the amount of storage available at that
+location as *@var{oldlenp}.  *@var{oldlenp} does double duty because it
+is also the output location that contains the actual length of the
+returned value.
+
+If you don't want the parameter value returned, specify a null pointer
+for @var{oldval}.
+
+To set the parameter, specify the address and length of the new value
+as @var{newval} and @var{newlen}.  If you don't want to set the parameter,
+specify a null pointer as @var{newval}.
+
+If you get and set a parameter in the same @code{sysctl} call, the value
+returned is the value of the parameter before it was set.
+
+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.
+
+
+@code{sysctl} returns a zero return value if it succeeds.  Otherwise, it
+returns @code{-1} and sets @code{errno} appropriately.  Besides the
+failures that apply to all system calls, the following are the
+@code{errno} codes for all possible failures:
+
+@table @code
+@item EPERM
+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.
+@c There is some indication in the Linux 2.2 code that the code is trying to
+@c return EACCESS here, but the EACCESS value never actually makes it to the
+@c user.
+@item ENOTDIR
+There is no system parameter corresponding to @var{name}.
+@item EFAULT
+@var{oldval} is not null, which means the process wanted to read the parameter,
+but *@var{oldlenp} is zero, so there is no place to return it.
+@item EINVAL
+@itemize @bullet
+@item
+The process attempted to set a system parameter to a value that is not valid
+for that parameter.
+@item
+The space provided for the return of the system parameter is not the right
+size for that parameter.
+@end itemize
+@item ENOMEM
+This value may be returned instead of the more correct @code{EINVAL} in some
+cases where the space provided for the return of the system parameter is too
+small.
+
+@end table
+
+@end deftypefun
+
+If you have a Linux kernel with the @code{proc} filesystem, you can get
+and set most of the same parameters by reading and writing to files in
+the @code{sys} directory of the @code{proc} filesystem.  In the @code{sys}
+directory, the directory structure represents the hierarchical structure
+of the parameters.  E.g. you can display the free page thresholds with
+@smallexample
+cat /proc/sys/vm/freepages
+@end smallexample
+@c In Linux, the sysctl() and /proc instances of the parameter are created
+@c together.  The proc filesystem accesses the same data structure as
+@c sysctl(), which has special fields in it for /proc.  But it is still
+@c possible to create a sysctl-only parameter.
+
+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:
+
+@itemize @bullet
+@item
+@code{getdomainname}, @code{setdomainname}
+@item
+@code{gethostname}, @code{sethostname} (@xref{Host Identification}.)
+@item
+@code{uname} (@xref{Platform Type}.)
+@item
+@code{bdflush}
+@end itemize