manual/sysinfo.texi

   1 @node System Information, System Configuration, Users and Groups, Top
   2 @chapter System Information
   3
   4 This chapter describes functions that return information about the
   5 particular machine that is in use---the type of hardware, the type of
   6 software, and the individual machine's name.
   7
   8 @menu
   9 * Host Identification::         Determining the name of the machine.
  10 * Hardware/Software Type ID::   Determining the hardware type of the
  11                                  machine and what operating system it is
  12                                  running.
  13 @end menu
  14
  15
  16 @node Host Identification
  17 @section Host Identification
  18
  19 This section explains how to identify the particular machine that your
  20 program is running on.  The identification of a machine consists of its
  21 Internet host name and Internet address; see @ref{Internet Namespace}.
  22 The host name should always be a fully qualified domain name, like
  23 @w{@samp{crispy-wheats-n-chicken.ai.mit.edu}}, not a simple name like
  24 just @w{@samp{crispy-wheats-n-chicken}}.
  25
  26 @pindex hostname
  27 @pindex hostid
  28 @pindex unistd.h
  29 Prototypes for these functions appear in @file{unistd.h}.  The shell
  30 commands @code{hostname} and @code{hostid} work by calling them.
  31
  32 @comment unistd.h
  33 @comment BSD
  34 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
  35 This function returns the name of the host machine in the array
  36 @var{name}.  The @var{size} argument specifies the size of this array,
  37 in bytes.
  38
  39 The return value is @code{0} on success and @code{-1} on failure.  In
  40 the GNU C library, @code{gethostname} fails if @var{size} is not large
  41 enough; then you can try again with a larger array.  The following
  42 @code{errno} error condition is defined for this function:
  43
  44 @table @code
  45 @item ENAMETOOLONG
  46 The @var{size} argument is less than the size of the host name plus one.
  47 @end table
  48
  49 @pindex sys/param.h
  50 On some systems, there is a symbol for the maximum possible host name
  51 length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
  52 But you can't count on this to exist, so it is cleaner to handle
  53 failure and try again.
  54
  55 @code{gethostname} stores the beginning of the host name in @var{name}
  56 even if the host name won't entirely fit.  For some purposes, a
  57 truncated host name is good enough.  If it is, you can ignore the
  58 error code.
  59 @end deftypefun
  60
  61 @comment unistd.h
  62 @comment BSD
  63 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
  64 The @code{sethostname} function sets the name of the host machine to
  65 @var{name}, a string with length @var{length}.  Only privileged
  66 processes are allowed to do this.  Usually it happens just once, at
  67 system boot time.
  68
  69 The return value is @code{0} on success and @code{-1} on failure.
  70 The following @code{errno} error condition is defined for this function:
  71
  72 @table @code
  73 @item EPERM
  74 This process cannot set the host name because it is not privileged.
  75 @end table
  76 @end deftypefun
  77
  78 @comment unistd.h
  79 @comment BSD
  80 @deftypefun {long int} gethostid (void)
  81 This function returns the ``host ID'' of the machine the program is
  82 running on.  By convention, this is usually the primary Internet address
  83 of that machine, converted to a @w{@code{long int}}.  However, some
  84 systems it is a meaningless but unique number which is hard-coded for
  85 each machine.
  86 @end deftypefun
  87
  88 @comment unistd.h
  89 @comment BSD
  90 @deftypefun int sethostid (long int @var{id})
  91 The @code{sethostid} function sets the ``host ID'' of the host machine
  92 to @var{id}.  Only privileged processes are allowed to do this.  Usually
  93 it happens just once, at system boot time.
  94
  95 The return value is @code{0} on success and @code{-1} on failure.
  96 The following @code{errno} error condition is defined for this function:
  97
  98 @table @code
  99 @item EPERM
 100 This process cannot set the host name because it is not privileged.
 101
 102 @item ENOSYS
 103 The operating system does not support setting the host ID.  On some
 104 systems, the host ID is a meaningless but unique number hard-coded for
 105 each machine.
 106 @end table
 107 @end deftypefun
 108
 109 @node Hardware/Software Type ID
 110 @section Hardware/Software Type Identification
 111
 112 You can use the @code{uname} function to find out some information about
 113 the type of computer your program is running on.  This function and the
 114 associated data type are declared in the header file
 115 @file{sys/utsname.h}.
 116 @pindex sys/utsname.h
 117
 118 @comment sys/utsname.h
 119 @comment POSIX.1
 120 @deftp {Data Type} {struct utsname}
 121 The @code{utsname} structure is used to hold information returned
 122 by the @code{uname} function.  It has the following members:
 123
 124 @table @code
 125 @item char sysname[]
 126 This is the name of the operating system in use.
 127
 128 @item char nodename[]
 129 This is the network name of this particular computer.  In the GNU
 130 library, the value is the same as that returned by @code{gethostname};
 131 see @ref{Host Identification}.
 132
 133 @item char release[]
 134 This is the current release level of the operating system implementation.
 135
 136 @item char version[]
 137 This is the current version level within the release of the operating
 138 system.
 139
 140 @item char machine[]
 141 This is a description of the type of hardware that is in use.
 142
 143 Some systems provide a mechanism to interrogate the kernel directly for
 144 this information.  On systems without such a mechanism, the GNU C
 145 library fills in this field based on the configuration name that was
 146 specified when building and installing the library.
 147
 148 GNU uses a three-part name to describe a system configuration; the three
 149 parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they
 150 are separated with dashes.  Any possible combination of three names is
 151 potentially meaningful, but most such combinations are meaningless in
 152 practice and even the meaningful ones are not necessarily supported by
 153 any particular GNU program.
 154
 155 Since the value in @code{machine} is supposed to describe just the
 156 hardware, it consists of the first two parts of the configuration name:
 157 @samp{@var{cpu}-@var{manufacturer}}.  For example, it might be one of these:
 158
 159 @quotation
 160 @code{"sparc-sun"},
 161 @code{"i386-@var{anything}"},
 162 @code{"m68k-hp"},
 163 @code{"m68k-sony"},
 164 @code{"m68k-sun"},
 165 @code{"mips-dec"}
 166 @end quotation
 167 @end table
 168 @end deftp
 169
 170 @comment sys/utsname.h
 171 @comment POSIX.1
 172 @deftypefun int uname (struct utsname *@var{info})
 173 The @code{uname} function fills in the structure pointed to by
 174 @var{info} with information about the operating system and host machine.
 175 A non-negative value indicates that the data was successfully stored.
 176
 177 @code{-1} as the value indicates an error.  The only error possible is
 178 @code{EFAULT}, which we normally don't mention as it is always a
 179 possibility.
 180 @end deftypefun