diff options
author | Roland McGrath <roland@gnu.org> | 1995-02-18 01:27:10 +0000 |
---|---|---|
committer | Roland McGrath <roland@gnu.org> | 1995-02-18 01:27:10 +0000 |
commit | 28f540f45bbacd939bfd07f213bcad2bf730b1bf (patch) | |
tree | 15f07c4c43d635959c6afee96bde71fb1b3614ee /manual/sysinfo.texi |
initial import
Diffstat (limited to 'manual/sysinfo.texi')
-rw-r--r-- | manual/sysinfo.texi | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi new file mode 100644 index 0000000000..a30536db6e --- /dev/null +++ b/manual/sysinfo.texi @@ -0,0 +1,180 @@ +@node System Information, System Configuration, Users and Groups, Top +@chapter System Information + +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. +@end menu + + +@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}}. + +@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 +@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. + +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: + +@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}. 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 ``host ID'' of the machine the program is +running on. By convention, this is usually the primary Internet address +of that machine, converted to a @w{@code{long int}}. However, some +systems it is a meaningless but unique number which is hard-coded for +each machine. +@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 +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. + +@item ENOSYS +The operating system does not support setting the host ID. On some +systems, the host ID is a meaningless but unique number hard-coded for +each machine. +@end table +@end deftypefun + +@node Hardware/Software Type ID +@section Hardware/Software 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 +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 {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 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. + +@item char version[] +This is the current version level within the release of the operating +system. + +@item char machine[] +This is a description of the type of hardware that is in use. + +Some systems provide a mechanism to interrogate the kernel directly for +this information. On systems without such a mechanism, 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}}. For example, it might be one of these: + +@quotation +@code{"sparc-sun"}, +@code{"i386-@var{anything}"}, +@code{"m68k-hp"}, +@code{"m68k-sony"}, +@code{"m68k-sun"}, +@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 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 |