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
  23 @pindex hostname
  24 @pindex hostid
  25 @pindex unistd.h
  26 Prototypes for these functions appear in @file{unistd.h}.  The shell
  27 commands @code{hostname} and @code{hostid} work by calling them.
  28
  29 @comment unistd.h
  30 @comment BSD
  31 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
  32 This function returns the name of the host machine in the array
  33 @var{name}.  The @var{size} argument specifies the size of this array,
  34 in bytes.
  35
  36 The return value is @code{0} on success and @code{-1} on failure.  In
  37 the GNU C library, @code{gethostname} fails if @var{size} is not large
  38 enough; then you can try again with a larger array.  The following
  39 @code{errno} error condition is defined for this function:
  40
  41 @table @code
  42 @item ENAMETOOLONG
  43 The @var{size} argument is less than the size of the host name plus one.
  44 @end table
  45
  46 @pindex sys/param.h
  47 On some systems, there is a symbol for the maximum possible host name
  48 length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
  49 But you can't count on this to exist, so it is cleaner to handle
  50 failure and try again.
  51
  52 @code{gethostname} stores the beginning of the host name in @var{name}
  53 even if the host name won't entirely fit.  For some purposes, a
  54 truncated host name is good enough.  If it is, you can ignore the
  55 error code.
  56 @end deftypefun
  57
  58 @comment unistd.h
  59 @comment BSD
  60 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
  61 The @code{sethostname} function sets the name of the host machine to
  62 @var{name}, a string with length @var{length}.  Only privileged
  63 processes are allowed to do this.  Usually it happens just once, at
  64 system boot time.
  65
  66 The return value is @code{0} on success and @code{-1} on failure.
  67 The following @code{errno} error condition is defined for this function:
  68
  69 @table @code
  70 @item EPERM
  71 This process cannot set the host name because it is not privileged.
  72 @end table
  73 @end deftypefun
  74
  75 @comment unistd.h
  76 @comment BSD
  77 @deftypefun {long int} gethostid (void)
  78 This function returns the Internet address of the machine the program is
  79 running on.
  80 @c !!! this is not necessarily the IP address.  it is whatever was set
  81 @c with sethostid (or the `hostid' program).  on sun4s, it is an
  82 @c unchangeable constant that is unique for each machine.
  83 @c making it the primary IP address is a convention.
  84 @end deftypefun
  85
  86 @comment unistd.h
  87 @comment BSD
  88 @deftypefun int sethostid (long int @var{id})
  89 The @code{sethostid} function sets the address of the host machine to
  90 @var{id}.  Only privileged processes are allowed to do this.  Usually it
  91 happens just once, at system boot time.
  92
  93 The return value is @code{0} on success and @code{-1} on failure.
  94 The following @code{errno} error condition is defined for this function:
  95
  96 @table @code
  97 @item EPERM
  98 This process cannot set the host name because it is not privileged.
  99 @end table
 100 @end deftypefun
 101
 102 @node Hardware/Software Type ID
 103 @section Hardware/Software Type Identification
 104
 105 You can use the @code{uname} function to find out some information about
 106 the type of computer your program is running on.  This function and the
 107 associated data type are declared in the header file
 108 @file{sys/utsname.h}.
 109 @pindex sys/utsname.h
 110
 111 @comment sys/utsname.h
 112 @comment POSIX.1
 113 @deftp {Data Type} {struct utsname}
 114 The @code{utsname} structure is used to hold information returned
 115 by the @code{uname} function.  It has the following members:
 116
 117 @table @code
 118 @item char sysname[]
 119 This is the name of the operating system in use.
 120
 121 @item char nodename[]
 122 This is the network name of this particular computer.  In the GNU
 123 library, the value is the same as that returned by @code{gethostname};
 124 see @ref{Host Identification}.
 125
 126 @item char release[]
 127 This is the current release level of the operating system implementation.
 128
 129 @item char version[]
 130 This is the current version level within the release of the operating
 131 system.
 132
 133 @item char machine[]
 134 This is a description of the type of hardware that is in use.
 135
 136 @c !!! this is only true if the operating system has no uname system call.
 137 The GNU C Library fills in this field based on the configuration name
 138 that was specified when building and installing the library.  GNU uses a
 139 three-part name to describe a system configuration; the three parts are
 140 @var{cpu}, @var{manufacturer} and @var{system-type}, and they are
 141 separated with dashes.  Any possible combination of three names is
 142 potentially meaningful, but most such combinations are meaningless in
 143 practice and even the meaningful ones are not necessarily supported by
 144 any particular GNU program.
 145
 146 Since the value in @code{machine} is supposed to describe just the
 147 hardware, it consists of the first two parts of the configuration name:
 148 @samp{@var{cpu}-@var{manufacturer}}.
 149
 150 @c !!! this is yet another case where you are losing massively because
 151 @c you want to have an explicit list.  many others are possible.
 152 Here is a list of all the possible alternatives:
 153
 154 @quotation
 155 @code{"i386-@var{anything}"}, @code{"m68k-hp"}, @code{"sparc-sun"},
 156 @code{"m68k-sun"}, @code{"m68k-sony"}, @code{"mips-dec"}
 157 @end quotation
 158 @end table
 159 @end deftp
 160
 161 @comment sys/utsname.h
 162 @comment POSIX.1
 163 @deftypefun int uname (struct utsname *@var{info})
 164 The @code{uname} function fills in the structure pointed to by
 165 @var{info} with information about the operating system and host machine.
 166 A non-negative value indicates that the data was successfully stored.
 167
 168 @code{-1} as the value indicates an error.  The only error possible is
 169 @code{EFAULT}, which we normally don't mention as it is always a
 170 possibility.
 171 @end deftypefun