Initial revision
[kopensolaris-gnu/glibc.git] / manual / sysinfo.texi
1 @node System Information
2 @chapter System Information
3
4 This chapter contains information about functions that return 
5 information about the particular machine a program is running on.
6
7 @menu
8 * Host Identification::                         Determining the name of the
9                                                  machine.
10 * Hardware/Software Type Identification::       Determining the hardware type
11                                                  of the machine and what
12                                                  operating system it is
13                                                  running.
14 @end menu
15
16
17 @node Host Identification
18 @section Host Identification
19
20 The functions listed in this section access information to identify the
21 particular machine that a program is running on.  In the GNU system,
22 this information is the default Internet host name and host address of
23 the machine; @pxref{The Internet Domain}.  These functions are the
24 primitives for the @code{hostname} and @code{hostid} shell commands.
25
26 Prototypes for these functions appear in @file{<unistd.h>}.
27
28 @comment unistd.h
29 @comment BSD
30 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
31 This function returns the name of the host machine in the array
32 @var{name}.  The @var{size} argument specifies the size of this array,
33 in bytes.
34
35 @strong{Incomplete:}  The size of the host name is limited by a parameter
36 @code{MAXHOSTNAMELENGTH}, declared in @file{<sys/param.h>}.
37
38 The return value is @code{0} on success and @code{-1} on failure.
39 @end deftypefun
40
41 @comment unistd.h
42 @comment BSD
43 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
44 The @code{sethostname} function sets the name of the host machine to
45 @var{name}, a string with length @var{length}.  This function can only
46 be called by the superuser, and is usually used only at system boot
47 time.
48
49 The return value is @code{0} on success and @code{-1} on failure.
50 @end deftypefun
51
52 @comment unistd.h
53 @comment BSD
54 @deftypefun {long int} gethostid (void)
55 This function returns the address of the host machine.
56 @end deftypefun
57
58 @comment unistd.h
59 @comment BSD
60 @deftypefun int sethostid (long int @var{id})
61 The @code{sethostid} function sets the address of the host machine
62 to @var{id}.  This function can only be called by the superuser, and
63 is usually used only at system boot time.
64
65 @strong{Incomplete:}  Is the return type from this function really 
66 @code{void}?  The BSD man page does not document a return value.
67 @end deftypefun
68
69
70 @node Hardware/Software Type Identification
71 @section Hardware/Software Type Identification
72
73 You can use the @code{uname} function to find out some information about
74 the computer system your program is running on.  This function and the
75 associated data type are declared in the header file
76 @file{<sys/utsname.h>}.
77
78 @comment sys/utsname.h
79 @comment POSIX.1
80 @deftp {Data Type} {struct utsname}
81 The @code{utsname} structure is used to hold information returned
82 by the @code{uname} function.  It has the following members:
83
84 @table @code
85 @item {char sysname[]}
86 This is the name of the operating system implementation.  In the
87 GNU Library, the value is the string @code{"GNU C Library"}.
88 @item {char nodename[]}
89 This is the name of this node within a communications network.  In the
90 GNU Library, the value is the same as that returned by
91 @code{gethostname}; @pxref{Host Identification}.
92 @item {char release[]}
93 This is the current release level of the operating system implementation.
94 @item {char version[]}
95 This is the current version level within the release of the operating
96 system.
97 @item {char machine[]}
98 This is a description of the hardware type that the operating system
99 is running on.
100 @end table
101 @end deftp
102
103
104 @comment sys/utsname.h
105 @comment POSIX.1
106 @deftypefun int uname (struct utsname *@var{info})
107 The @code{uname} function fills in the structure pointed to by
108 @var{info} with information about the operating system and host machine.
109 A non-negative value is returned on successful completion; in the event
110 of an error, @code{-1} is returned.
111 @end deftypefun
112
113
114
115