-@node System Information
+@node System Information, System Configuration, Users and Groups, Top
@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
-* 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
-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}.
+
@pindex hostname
@pindex hostid
-
-Prototypes for these functions appear in @file{unistd.h}.
@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
@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}.
-@pindex 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
-@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 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)
-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})
-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
-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
@file{sys/utsname.h}.
@pindex sys/utsname.h
@comment sys/utsname.h
@comment POSIX.1
-@deftp {struct Type} utsname
+@deftp {Data Type} {struct utsname}
The @code{utsname} structure is used to hold information returned
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"}.
+This is the name of the operating system in use.
@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}.
+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.
system.
@item char machine[]
-This is a description of the hardware type that the operating system
-is running on.
+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
-
@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
projects / kopensolaris-gnu / glibc.git / blobdiff