Add %MENU% tag.
[kopensolaris-gnu/glibc.git] / manual / sysinfo.texi
1 @node System Information, System Configuration, Users and Groups, Top
2 @c %MENU% Getting information about the hardware and operating system
3 @chapter System Information
4
5 This chapter describes functions that return information about the
6 particular machine that is in use---the type of hardware, the type of
7 software, and the individual machine's name.
8
9 @menu
10 * Host Identification::         Determining the name of the machine.
11 * Hardware/Software Type ID::   Determining the hardware type of the
12                                  machine and what operating system it is
13                                  running.
14 * Filesystem handling::         Which is mounted and/or available?
15 @end menu
16
17
18 @node Host Identification
19 @section Host Identification
20
21 This section explains how to identify the particular machine that your
22 program is running on.  The identification of a machine consists of its
23 Internet host name and Internet address; see @ref{Internet Namespace}.
24 The host name should always be a fully qualified domain name, like
25 @w{@samp{crispy-wheats-n-chicken.ai.mit.edu}}, not a simple name like
26 just @w{@samp{crispy-wheats-n-chicken}}.
27
28 @pindex hostname
29 @pindex hostid
30 @pindex unistd.h
31 Prototypes for these functions appear in @file{unistd.h}.  The shell
32 commands @code{hostname} and @code{hostid} work by calling them.
33
34 @comment unistd.h
35 @comment BSD
36 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
37 This function returns the name of the host machine in the array
38 @var{name}.  The @var{size} argument specifies the size of this array,
39 in bytes.
40
41 The return value is @code{0} on success and @code{-1} on failure.  In
42 the GNU C library, @code{gethostname} fails if @var{size} is not large
43 enough; then you can try again with a larger array.  The following
44 @code{errno} error condition is defined for this function:
45
46 @table @code
47 @item ENAMETOOLONG
48 The @var{size} argument is less than the size of the host name plus one.
49 @end table
50
51 @pindex sys/param.h
52 On some systems, there is a symbol for the maximum possible host name
53 length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
54 But you can't count on this to exist, so it is cleaner to handle
55 failure and try again.
56
57 @code{gethostname} stores the beginning of the host name in @var{name}
58 even if the host name won't entirely fit.  For some purposes, a
59 truncated host name is good enough.  If it is, you can ignore the
60 error code.
61 @end deftypefun
62
63 @comment unistd.h
64 @comment BSD
65 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
66 The @code{sethostname} function sets the name of the host machine to
67 @var{name}, a string with length @var{length}.  Only privileged
68 processes are allowed to do this.  Usually it happens just once, at
69 system boot time.
70
71 The return value is @code{0} on success and @code{-1} on failure.
72 The following @code{errno} error condition is defined for this function:
73
74 @table @code
75 @item EPERM
76 This process cannot set the host name because it is not privileged.
77 @end table
78 @end deftypefun
79
80 @comment unistd.h
81 @comment BSD
82 @deftypefun {long int} gethostid (void)
83 This function returns the ``host ID'' of the machine the program is
84 running on.  By convention, this is usually the primary Internet address
85 of that machine, converted to a @w{@code{long int}}.  However, some
86 systems it is a meaningless but unique number which is hard-coded for
87 each machine.
88 @end deftypefun
89
90 @comment unistd.h
91 @comment BSD
92 @deftypefun int sethostid (long int @var{id})
93 The @code{sethostid} function sets the ``host ID'' of the host machine
94 to @var{id}.  Only privileged processes are allowed to do this.  Usually
95 it happens just once, at system boot time.
96
97 The return value is @code{0} on success and @code{-1} on failure.
98 The following @code{errno} error condition is defined for this function:
99
100 @table @code
101 @item EPERM
102 This process cannot set the host name because it is not privileged.
103
104 @item ENOSYS
105 The operating system does not support setting the host ID.  On some
106 systems, the host ID is a meaningless but unique number hard-coded for
107 each machine.
108 @end table
109 @end deftypefun
110
111 @node Hardware/Software Type ID
112 @section Hardware/Software Type Identification
113
114 You can use the @code{uname} function to find out some information about
115 the type of computer your program is running on.  This function and the
116 associated data type are declared in the header file
117 @file{sys/utsname.h}.
118 @pindex sys/utsname.h
119
120 @comment sys/utsname.h
121 @comment POSIX.1
122 @deftp {Data Type} {struct utsname}
123 The @code{utsname} structure is used to hold information returned
124 by the @code{uname} function.  It has the following members:
125
126 @table @code
127 @item char sysname[]
128 This is the name of the operating system in use.
129
130 @item char nodename[]
131 This is the network name of this particular computer.  In the GNU
132 library, the value is the same as that returned by @code{gethostname};
133 see @ref{Host Identification}.
134
135 @item char release[]
136 This is the current release level of the operating system implementation.
137
138 @item char version[]
139 This is the current version level within the release of the operating
140 system.
141
142 @item char machine[]
143 This is a description of the type of hardware that is in use.
144
145 Some systems provide a mechanism to interrogate the kernel directly for
146 this information.  On systems without such a mechanism, the GNU C
147 library fills in this field based on the configuration name that was
148 specified when building and installing the library.
149
150 GNU uses a three-part name to describe a system configuration; the three
151 parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they
152 are separated with dashes.  Any possible combination of three names is
153 potentially meaningful, but most such combinations are meaningless in
154 practice and even the meaningful ones are not necessarily supported by
155 any particular GNU program.
156
157 Since the value in @code{machine} is supposed to describe just the
158 hardware, it consists of the first two parts of the configuration name:
159 @samp{@var{cpu}-@var{manufacturer}}.  For example, it might be one of these:
160
161 @quotation
162 @code{"sparc-sun"},
163 @code{"i386-@var{anything}"},
164 @code{"m68k-hp"},
165 @code{"m68k-sony"},
166 @code{"m68k-sun"},
167 @code{"mips-dec"}
168 @end quotation
169 @end table
170 @end deftp
171
172 @comment sys/utsname.h
173 @comment POSIX.1
174 @deftypefun int uname (struct utsname *@var{info})
175 The @code{uname} function fills in the structure pointed to by
176 @var{info} with information about the operating system and host machine.
177 A non-negative value indicates that the data was successfully stored.
178
179 @code{-1} as the value indicates an error.  The only error possible is
180 @code{EFAULT}, which we normally don't mention as it is always a
181 possibility.
182 @end deftypefun
183
184
185 @node Filesystem handling
186 @section Which filesystems are mounted and/or available?
187
188 The Unix concept of @emph{Everything is a file} is based on the
189 possibility to @dfn{mount} filesystems or other things into the
190 filesystem.  For some programs it is desirable and necessary to access
191 the information whether and, if yes, where a certain filesystem is
192 mounted or simply to get lists of all the available filesystems.  The
193 GNU libc provides some functions to retrieve this information portably.
194
195 Traditionally Unix systems have a file named @file{/etc/fstab} which
196 describes all possibly mounted filesystems.  The @code{mount} program
197 uses this file to mount at startup time of the system all the necessary
198 filesystems.  The information about all the filesystems actually mounted
199 is normally kept in a file named @file{/etc/mtab}.  Both files share
200 the same syntax and it is crucial that this syntax is followed all the
201 time.  Therefore it is best to never directly write the files.  The
202 functions described in this section can do this and they also provide
203 the functionality to convert the external textual representation to the
204 internal representation.
205
206 @vindex _PATH_FSTAB
207 @vindex _PATH_MNTTAB
208 @vindex FSTAB
209 @vindex _PATH_MOUNTED
210 The filenames given above should never be used directly.  The portable
211 way to handle these file is to use the macros @code{_PATH_FSTAB},
212 defined in @file{fstab.h} and @code{_PATH_MNTTAB}, defined in
213 @file{mntent.h}, respectively.  There are also two alternate macro names
214 @code{FSTAB} and @code{_PATH_MOUNTED} defined but both names are
215 deprecated and kept only for backward compatibility.  The two former
216 names should always be used.
217
218 The internal representation for entries of the file is @w{@code{struct
219 fstab}}, defined in @file{fstab.h}.
220
221 @comment fstab.h
222 @comment BSD
223 @deftp {Data Type} {struct fstab}
224 This structure is used with the @code{getfsent}, @code{getfsspec}, and
225 @code{getfsfile} functions.
226
227 @table @code
228 @item char *fs_spec
229 This element describes the device from which the filesystem is mounted.
230 Normally this is the name of a special device, such as a hard disk
231 partition, but it could also be a more or less generic string.  For
232 @dfn{NFS} it would be a hostname and directory name combination.
233
234 Even though the element is not declared @code{const} it shouldn't be
235 modified.  The missing @code{const} has historic reasons, since this
236 function predates @w{ISO C}.  The same is true for the other string
237 elements of this structure.
238
239 @item char *fs_file
240 This describes the mount point on the local system.  I.e., accessing any
241 file in this filesystem has implicitly or explicitly this string as a
242 prefix.
243
244 @item char *fs_vfstype
245 This is the type of the filesystem.  Depending on what the underlying
246 kernel understands it can be any string.
247
248 @item char *fs_mntops
249 This is a string containing options passed to the kernel with the
250 @code{mount} call.  Again, this can be almost anything.  There can be
251 more than one option, separated from the others by a comma.  Each option
252 consists of a name and an optional value part, introduced by an @code{=}
253 character.
254
255 If the value of this element must be processed it should best happen
256 using the @code{getsubopt} function; see @ref{Suboptions}.
257
258 @item const char *fs_type
259 This name is poorly chosen.  This element points to a string (possibly
260 in the @code{fs_mntops} string) which describes the modes with which the
261 filesystem is mounted.  @file{fstab} defines five macros to describe the
262 possible values:
263
264 @vtable @code
265 @item FSTAB_RW
266 The filesystems gets mounted with read and write enabled.
267 @item FSTAB_RQ
268 The filesystems gets mounted with read and write enabled.  Write access
269 is restricted by quotas.
270 @item FSTAB_RO
271 The filesystem gets mounted read-only.
272 @item FSTAB_SW
273 This is not a real filesystem, it is a swap device.
274 @item FSTAB_XX
275 This entry from the @file{fstab} file is totally ignored.
276 @end vtable
277
278 Testing for equality with these value must happen using @code{strcmp}
279 since these are all strings.  Comparing the pointer will probably always
280 fail.
281
282 @item int fs_freq
283 This element describes the dump frequency in days.
284
285 @item int fs_passno
286 This element describes the pass number on parallel dumps.  It is closely
287 related to the @code{dump} utility used on Unix systems.
288 @end table
289 @end deftp
290
291
292 To read the entire content of the of the @file{fstab} file the GNU libc
293 contains a set of three functions which are designed in the usual way.
294
295 @comment fstab.h
296 @comment BSD
297 @deftypefun int setfsent (void)
298 This function makes sure that the internal read pointer for the
299 @file{fstab} file is at the beginning of the file.  This is done by
300 either opening the file or resetting the read pointer.
301
302 Since the file handle is internal to the libc this function is not
303 thread-safe.
304
305 This function returns a non-zero value if the operation was successful
306 and the @code{getfs*} functions can be used to read the entries of the
307 file.
308 @end deftypefun
309
310 @comment fstab.h
311 @comment BSD
312 @deftypefun void endfsent (void)
313 This function makes sure that all resources acquired by a prior call to
314 @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are
315 freed.
316 @end deftypefun
317
318 @comment fstab.h
319 @comment BSD
320 @deftypefun {struct fstab *} getfsent (void)
321 This function returns the next entry of the @file{fstab} file.  If this
322 is the first call to any of the functions handling @file{fstab} since
323 program start or the last call of @code{endfsent}, the file will be
324 opened.
325
326 The function returns a pointer to an variable of type @code{struct
327 fstab}.  This variable is shared by all threads and therefore this
328 function is not thread-safe.  If an error occurred @code{getfsent}
329 returns a @code{NULL} pointer.
330 @end deftypefun
331
332 @comment fstab.h
333 @comment BSD
334 @deftypefun {struct fstab *} getfsspec (const char *@var{name})
335 This function returns the next entry of the @file{fstab} file which has
336 a string equal to @var{name} pointed to by the @code{fs_spec} element.
337 Since there is normally exactly one entry for each special device it
338 makes no sense to call this function more than once for the same
339 argument.  If this is the first call to any of the functions handling
340 @file{fstab} since program start or the last call of @code{endfsent},
341 the file will be opened.
342
343 The function returns a pointer to an variable of type @code{struct
344 fstab}.  This variable is shared by all threads and therefore this
345 function is not thread-safe.  If an error occurred @code{getfsent}
346 returns a @code{NULL} pointer.
347 @end deftypefun
348
349 @comment fstab.h
350 @comment BSD
351 @deftypefun {struct fstab *} getfsfile (const char *@var{name})
352 This function returns the next entry of the @file{fstab} file which has
353 a string equal to @var{name} pointed to by the @code{fs_file} element.
354 Since there is normally exactly one entry for each mount point it
355 makes no sense to call this function more than once for the same
356 argument.  If this is the first call to any of the functions handling
357 @file{fstab} since program start or the last call of @code{endfsent},
358 the file will be opened.
359
360 The function returns a pointer to an variable of type @code{struct
361 fstab}.  This variable is shared by all threads and therefore this
362 function is not thread-safe.  If an error occurred @code{getfsent}
363 returns a @code{NULL} pointer.
364 @end deftypefun
365
366 To access the @file{mtab} file there is a different set of functions and
367 also a different structure to describe the results.
368
369
370 @comment fstab.h
371 @comment BSD
372 @deftp {Data Type} {struct mntent}
373 This structure is used with the @code{getmntent}, @code{getmntent_t},
374 @code{addmntent}, and @code{hasmntopt} functions.
375
376 @table @code
377 @item char *mnt_fsname
378 This element contains a pointer to a string describing the name of the
379 special device from which the filesystem is mounted.  It corresponds to
380 the @code{fs_spec} element in @code{struct fstab}.
381
382 @item char *mnt_dir
383 This element points to a string describing the mount point of the
384 filesystem.  It corresponds to the @code{fs_file} element in
385 @code{struct fstab}.
386
387 @item char *mnt_type
388 @code{mnt_type} describes the filesystem type and is therefore
389 equivalent to @code{fs_vfstype} in @code{struct fstab}.  @file{mntent.h}
390 defines a few symbolic names for some of the value this string can have.
391 But since the kernel can support an arbitrary filesystems it does not
392 make much sense to give them symbolic names.  If one knows the symbol
393 name one also knows the filesystem name.  Nevertheless here follows the
394 list of the symbol provided in @file{mntent.h}.
395
396 @vtable @code
397 @item MNTTYPE_IGNORE
398 This symbol expands to @code{"ignore"}.  The value is sometime used in
399 @file{fstab} files to make sure entries are not used without removing them.
400 @item MNTTYPE_NFS
401 Expands to @code{"nfs"}.  Using this macro sometimes could make sense
402 since it names the default NFS implementation, in case both version 2
403 and 3 are supported.
404 @item MNTTYPE_SWAP
405 This symbol expands to @code{"swap"}.  It names the special @file{fstab}
406 entry which names one of the possibly multiple swap partitions.
407 @end vtable
408
409 @item char *mnt_opts
410 The element contains a string describing the options used while mounting
411 the filesystem.  As for the equivalent element @code{fs_mntops} of
412 @code{struct fstab} it is best to use the function @code{getsubopt}
413 (@pxref{Suboptions}) to access the parts of this string.
414
415 The @file{mntent.h} file defines a number of macros with string values
416 which correspond to some of the options understood by the kernel.  There
417 might be many more options which are possible so it makes not much sense
418 to rely on these macros but to be consistent here is the list:
419
420 @vtable @code
421 @item MNTOPT_DEFAULTS
422 Expands to @code{"defaults"}.  This option should be used alone since it
423 indicates all values for the custumizable values are chosen to be the
424 default.
425 @item MNTOPT_RO
426 Expands to @code{"ro"}.  See the @code{FSTAB_RO} value, it means the
427 filesystem is mounted read-only.
428 @item MNTOPT_RW
429 Expand to @code{"rw"}.  See the @code{FSTAB_RW} value, it means the
430 filesystem is mounted with read and write permissions.
431 @item MNTOPT_SUID
432 Expands to @code{"suid"}.  This means that the SUID bit (@pxref{How
433 Change Persona}) is respected when a program from the filesystem is
434 started.
435 @item MNTOPT_NOSUID
436 Expands to @code{"nosuid"}.  This is the opposite of @code{MNTOPT_SUID},
437 the SUID bit for all files from the filesystem is ignored.
438 @item MNTOPT_NOAUTO
439 Expands to @code{"noauto"}.  At startup time the @code{mount} program
440 will ignore this entry if it is started with the @code{-a} option to
441 mount all filesystems mentioned in the @file{fstab} file.
442 @end vtable
443
444 As for the @code{FSTAB_*} entries introduced above it is important to
445 use @code{strcmp} to check for equality.
446
447 @item mnt_freq
448 This elements corresponds to @code{fs_freq} and also specifies the
449 frequency in days in which dumps are made.
450
451 @item mnt_passno
452 This element is equivalent to @code{fs_passno} with the same meaning
453 which is uninteresting for all programs beside @code{dump}.
454 @end table
455 @end deftp
456
457 For accessing the @file{mtab} file there is again a set of three
458 functions to access all entries in a row.  Unlike the functions to
459 handle @file{fstab} these functions do not access a fixed file and there
460 is even a thread safe variant of the get function.  Beside this the GNU
461 libc contains functions to alter the file and test for specific options.
462
463 @comment mntent.h
464 @comment BSD
465 @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode})
466 The @code{setmntent} function prepares the file named @var{FILE} which
467 must be in the format of a @file{fstab} and @file{mtab} file for the
468 upcoming processing through the other functions of the family.  The
469 @var{mode} parameter can be chosen in the way the @var{opentype}
470 parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen.  If
471 the file is opened for writing the file is also allowed to be empty.
472
473 If the file was successfully opened @code{setmntent} returns a file
474 descriptor for future use.  Otherwise the return value is @code{NULL}
475 and @code{errno} is set accordingly.
476 @end deftypefun
477
478 @comment mntent.h
479 @comment BSD
480 @deftypefun int endmntent (FILE *@var{stream})
481 This function takes for the @var{stream} parameter a file handle which
482 previously was returned from the @code{setmntent} call.
483 @code{endmntent} closes the stream and frees all resources.
484
485 The return value is @math{1} unless an error occurred in which case it
486 is @math{0}.
487 @end deftypefun
488
489 @comment mntent.h
490 @comment BSD
491 @deftypefun {struct mntent *} getmntent (FILE *@var{stream})
492 The @code{getmntent} function takes as the parameter a file handle
493 previously returned by successful call to @code{setmntent}.  It returns
494 a pointer to a static variable of type @code{struct mntent} which is
495 filled with the information from the next entry from the file currently
496 read.
497
498 If there was an error or the end of the file is reached the return value
499 is @code{NULL}.
500
501 This function is not thread-safe since all calls to this function return
502 a pointer to the same static variable.  @code{getmntent_r} should be
503 used in situations where multiple threads access the file.
504 @end deftypefun
505
506 @comment mntent.h
507 @comment BSD
508 @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize})
509 The @code{getmntent_r} function is the reentrant variant of
510 @code{getmntent}.  It also returns the next entry from the file and
511 returns a pointer.  The actual variable the values are stored in is not
512 static, though.  Instead the function stores the values in the variable
513 pointed to by the @var{result} parameter.  Additional information (e.g.,
514 the strings pointed to by the elements of the result) are kept in the
515 buffer of size @var{bufsize} pointed to by @var{buffer}.
516
517 The function returns a @code{NULL} pointer in error cases.  Errors could be:
518 @itemize @bullet
519 @item
520 error while reading the file,
521 @item
522 end of file reached,
523 @item
524 @var{bufsize} is too small for reading a complete new entry.
525 @end itemize
526 @end deftypefun
527
528 @comment mntent.h
529 @comment BSD
530 @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt})
531 The @code{addmntent} function allows to add a new entry to the file
532 previously opened with @code{setmntent}.  The new entries are always
533 appended.  I.e., even if the position of the file descriptor is not at
534 the end of the file this function does not overwrite an existing entry
535 following the current position.
536
537 The implication of this is that to remove an entry from a file one has
538 to create a new file while leaving out the entry to be removed and after
539 closing the file remove the old one and rename the new file to the
540 chosen name.
541
542 This function returns @math{0} in case the operation was successful.
543 Otherwise the return value is @math{1} and @code{errno} is set
544 appropriately.
545 @end deftypefun
546
547 @comment mntent.h
548 @comment BSD
549 @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt})
550 This function can be used to check whether the string pointed to by the
551 @code{mnt_opts} element of the variable pointed to by @var{mnt} contains
552 the option @var{opt}.  If this is true a pointer to the beginning of the
553 option in the @code{mnt_opts} element is returned.  If no such option
554 exists the function returns @code{NULL}.
555
556 This function is useful to test whether a specific option is present but
557 when all options have to be processed one is better off with using the
558 @code{getsubopt} function to iterate over all options in the string.
559 @end deftypefun