(i[34]86sol2): New abbrev for i[34]86-unknown-solaris2.
[kopensolaris-gnu/glibc.git] / manual / sysinfo.texi
index 0ddf583..e384f8d 100644 (file)
@@ -1,29 +1,30 @@
-@node System Information
+@node System Information, System Configuration, Users and Groups, Top
 @chapter System Information
 
 @chapter System Information
 
-This chapter contains information about functions that return 
-information about the particular machine a program is running on.
+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
 
 @menu
-* Host Identification::                         Determining the name of the
-                                                 machine.
-* Hardware/Software Type Identification::       Determining the hardware type
-                                                 of the machine and what
-                                                 operating system it is
-                                                 running.
+* 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. 
 @end menu
 
 
 @node Host Identification
 @section Host Identification
 
 @end menu
 
 
 @node Host Identification
 @section Host Identification
 
-The functions listed in this section access information to identify the
-particular machine that a program is running on.  In the GNU system,
-this information is the default Internet host name and host address of
-the machine; @pxref{The Internet Domain}.  These functions are the
-primitives for the @code{hostname} and @code{hostid} shell commands.
+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}.  
 
 
-Prototypes for these functions appear in @file{<unistd.h>}.
+@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.
 
 @comment unistd.h
 @comment BSD
 
 @comment unistd.h
 @comment BSD
@@ -32,48 +33,80 @@ 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.
 
 @var{name}.  The @var{size} argument specifies the size of this array,
 in bytes.
 
-@strong{Incomplete:}  The size of the host name is limited by a parameter
-@code{MAXHOSTNAMELENGTH}, declared in @file{<sys/param.h>}.
+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
+enough; then you can try again with a larger array.  The following
+@code{errno} error condition is defined for this function:
 
 
-The return value is @code{0} on success and @code{-1} on failure.
+@table @code
+@item ENAMETOOLONG
+The @var{size} argument is less than the size of the host name plus one.
+@end table
+
+@pindex sys/param.h
+On some systems, there is a symbol for the maximum possible host name
+length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
+But you can't count on this to exist, so it is cleaner to handle
+failure and try again.
+
+@code{gethostname} stores the beginning of the host name in @var{name}
+even if the host name won't entirely fit.  For some purposes, a
+truncated host name is good enough.  If it is, you can ignore the
+error code.
 @end deftypefun
 
 @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
 @end deftypefun
 
 @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}.  This function can only
-be called by the superuser, and is usually used only at system boot
-time.
+@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 return value is @code{0} on success and @code{-1} on failure.
 
 The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EPERM
+This process cannot set the host name because it is not privileged.
+@end table
 @end deftypefun
 
 @comment unistd.h
 @comment BSD
 @deftypefun {long int} gethostid (void)
 @end deftypefun
 
 @comment unistd.h
 @comment BSD
 @deftypefun {long int} gethostid (void)
-This function returns the address of the host machine.
+This function returns the Internet address of the machine the program is
+running on.
+@c !!! this is not necessarily the IP address.  it is whatever was set
+@c with sethostid (or the `hostid' program).  on sun4s, it is an
+@c unchangeable constant that is unique for each machine.
+@c making it the primary IP address is a convention.
 @end deftypefun
 
 @comment unistd.h
 @comment BSD
 @deftypefun int sethostid (long int @var{id})
 @end deftypefun
 
 @comment unistd.h
 @comment BSD
 @deftypefun int sethostid (long int @var{id})
-The @code{sethostid} function sets the address of the host machine
-to @var{id}.  This function can only be called by the superuser, and
-is usually used only at system boot time.
+The @code{sethostid} function sets the address of the host machine to
+@var{id}.  Only privileged processes are allowed to do this.  Usually it
+happens just once, at system boot time.
 
 
-@strong{Incomplete:}  Is the return type from this function really 
-@code{void}?  The BSD man page does not document a return value.
-@end deftypefun
+The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error condition is defined for this function:
 
 
+@table @code
+@item EPERM
+This process cannot set the host name because it is not privileged.
+@end table
+@end deftypefun
 
 
-@node Hardware/Software Type Identification
+@node Hardware/Software Type ID
 @section Hardware/Software Type Identification
 
 You can use the @code{uname} function to find out some information about
 @section Hardware/Software Type Identification
 
 You can use the @code{uname} function to find out some information about
-the computer system your program is running on.  This function and the
+the type of computer your program is running on.  This function and the
 associated data type are declared in the header file
 associated data type are declared in the header file
-@file{<sys/utsname.h>}.
+@file{sys/utsname.h}.
+@pindex sys/utsname.h
 
 @comment sys/utsname.h
 @comment POSIX.1
 
 @comment sys/utsname.h
 @comment POSIX.1
@@ -82,34 +115,57 @@ The @code{utsname} structure is used to hold information returned
 by the @code{uname} function.  It has the following members:
 
 @table @code
 by the @code{uname} function.  It has the following members:
 
 @table @code
-@item {char sysname[]}
-This is the name of the operating system implementation.  In the
-GNU Library, the value is the string @code{"GNU C Library"}.
-@item {char nodename[]}
-This is the name of this node within a communications network.  In the
-GNU Library, the value is the same as that returned by
-@code{gethostname}; @pxref{Host Identification}.
-@item {char release[]}
+@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.
 This is the current release level of the operating system implementation.
-@item {char version[]}
+
+@item char version[]
 This is the current version level within the release of the operating
 system.
 This is the current version level within the release of the operating
 system.
-@item {char machine[]}
-This is a description of the hardware type that the operating system
-is running on.
+
+@item char machine[]
+This is a description of the type of hardware that is in use.
+
+@c !!! this is only true if the operating system has no uname system call.
+The GNU C Library fills in this field based on the configuration name
+that was specified when building and installing the library.  GNU uses a
+three-part name to describe a system configuration; the three parts are
+@var{cpu}, @var{manufacturer} and @var{system-type}, and they are
+separated with dashes.  Any possible combination of three names is
+potentially meaningful, but most such combinations are meaningless in
+practice and even the meaningful ones are not necessarily supported by
+any particular GNU program.
+
+Since the value in @code{machine} is supposed to describe just the
+hardware, it consists of the first two parts of the configuration name:
+@samp{@var{cpu}-@var{manufacturer}}.
+
+@c !!! this is yet another case where you are losing massively because
+@c you want to have an explicit list.  many others are possible.
+Here is a list of all the possible alternatives:
+
+@quotation
+@code{"i386-@var{anything}"}, @code{"m68k-hp"}, @code{"sparc-sun"},
+@code{"m68k-sun"}, @code{"m68k-sony"}, @code{"mips-dec"}
+@end quotation
 @end table
 @end deftp
 
 @end table
 @end deftp
 
-
 @comment sys/utsname.h
 @comment POSIX.1
 @deftypefun int uname (struct utsname *@var{info})
 The @code{uname} function fills in the structure pointed to by
 @var{info} with information about the operating system and host machine.
 @comment sys/utsname.h
 @comment POSIX.1
 @deftypefun int uname (struct utsname *@var{info})
 The @code{uname} function fills in the structure pointed to by
 @var{info} with information about the operating system and host machine.
-A non-negative value is returned on successful completion; in the event
-of an error, @code{-1} is returned.
-@end deftypefun
-
-
-
+A non-negative value indicates that the data was successfully stored.
 
 
+@code{-1} as the value indicates an error.  The only error possible is
+@code{EFAULT}, which we normally don't mention as it is always a
+possibility.
+@end deftypefun