Change node ref.
[kopensolaris-gnu/glibc.git] / 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 Domain}.  
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 ()
78 This function returns the Internet address of the machine the program is
79 running on.
80 @end deftypefun
81
82 @comment unistd.h
83 @comment BSD
84 @deftypefun int sethostid (long int @var{id})
85 The @code{sethostid} function sets the address of the host machine to
86 @var{id}.  Only privileged processes are allowed to do this.  Usually it
87 happens just once, at system boot time.
88
89 The return value is @code{0} on success and @code{-1} on failure.
90 The following @code{errno} error condition is defined for this function:
91
92 @table @code
93 @item EPERM
94 This process cannot set the host name because it is not privileged.
95 @end table
96 @end deftypefun
97
98 @node Hardware/Software Type ID
99 @section Hardware/Software Type Identification
100
101 You can use the @code{uname} function to find out some information about
102 the type of computer your program is running on.  This function and the
103 associated data type are declared in the header file
104 @file{sys/utsname.h}.
105 @pindex sys/utsname.h
106
107 @comment sys/utsname.h
108 @comment POSIX.1
109 @deftp {Data Type} {struct utsname}
110 The @code{utsname} structure is used to hold information returned
111 by the @code{uname} function.  It has the following members:
112
113 @table @code
114 @item char sysname[]
115 This is the name of the operating system implementation.  In the
116 GNU library, the value is the string @code{"GNU C Library"}.
117 @strong{Incomplete:} That had better not be true.
118
119 @item char nodename[]
120 This is the network name of this particular computer.  In the GNU
121 library, the value is the same as that returned by @code{gethostname};
122 see @ref{Host Identification}.
123
124 @item char release[]
125 This is the current release level of the operating system implementation.
126
127 @item char version[]
128 This is the current version level within the release of the operating
129 system.
130
131 @item char machine[]
132 This is a description of the type of hardware that is in use.
133
134 The GNU C Library fills in this field based on the configuration name
135 that was specified when building and installing the library.  GNU uses a
136 three-part name to describe a system configuration; the three parts are
137 @var{cpu}, @var{manufacturer} and @var{system-type}, and they are
138 separated with dashes.  Any possible combination of three names is
139 potentially meaningful, but most such combinations are meaningless in
140 practice and even the meaningful ones are not necessarily supported by
141 any particular GNU program.
142
143 Since the value in @code{machine} is supposed to describe just the
144 hardware, it consists of the first two parts of the configuration name:
145 @samp{@var{cpu}-@var{manufacturer}}.
146
147 Here is a list of all the possible alternatives:
148
149 @quotation
150 @code{"i386-@var{anything}"}, @code{"m68k-hp"}, @code{"sparc-sun"}
151 @end quotation
152 @end table
153 @end deftp
154
155 @comment sys/utsname.h
156 @comment POSIX.1
157 @deftypefun int uname (struct utsname *@var{info})
158 The @code{uname} function fills in the structure pointed to by
159 @var{info} with information about the operating system and host machine.
160 A non-negative value indicates that the data was successfully stored.
161 @code{-1} as the value indicates an error.
162
163 @strong{Incomplete:} What can cause an error in this function?
164 @end deftypefun
165
166
167
168