Local rewriting.
[kopensolaris-gnu/glibc.git] / manual / sysinfo.texi
1 @node System Information, System Configuration Limits, 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.
39
40 @pindex sys/param.h
41 On some systems, there is a symbol for the maximum possible host name
42 length: @code{MAXHOSTNAMELENGTH}.  It is defined in @file{sys/param.h}.
43 But you can't count on this to exist, and it is cleaner to handle
44 failure and try again.
45 @end deftypefun
46
47 @comment unistd.h
48 @comment BSD
49 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
50 The @code{sethostname} function sets the name of the host machine to
51 @var{name}, a string with length @var{length}.  Only privileged
52 processes are allowed to do this.  Usually it happens just once, at
53 system boot time.
54
55 The return value is @code{0} on success and @code{-1} on failure.
56 @end deftypefun
57
58 @comment unistd.h
59 @comment BSD
60 @deftypefun {long int} gethostid ()
61 This function returns the Internet address of the machine the program is
62 running on.
63 @end deftypefun
64
65 @comment unistd.h
66 @comment BSD
67 @deftypefun int sethostid (long int @var{id})
68 The @code{sethostid} function sets the address of the host machine to
69 @var{id}.  Only privileged processes are allowed to do this.  Usually it
70 happens just once, at system boot time.
71
72 @strong{Incomplete:}  Is the return type from this function really 
73 @code{void}?  The BSD man page does not document a return value.
74 @end deftypefun
75
76
77 @node Hardware/Software Type ID
78 @section Hardware/Software Type Identification
79
80 You can use the @code{uname} function to find out some information about
81 the type of computer your program is running on.  This function and the
82 associated data type are declared in the header file
83 @file{sys/utsname.h}.
84 @pindex sys/utsname.h
85
86 @comment sys/utsname.h
87 @comment POSIX.1
88 @deftp {Data Type} {struct utsname}
89 The @code{utsname} structure is used to hold information returned
90 by the @code{uname} function.  It has the following members:
91
92 @table @code
93 @item char sysname[]
94 This is the name of the operating system implementation.  In the
95 GNU library, the value is the string @code{"GNU C Library"}.
96 @strong{Incomplete:} That had better not be true.
97
98 @item char nodename[]
99 This is the network name of this particular computer.  In the GNU
100 library, the value is the same as that returned by @code{gethostname};
101 see @ref{Host Identification}.
102
103 @item char release[]
104 This is the current release level of the operating system implementation.
105
106 @item char version[]
107 This is the current version level within the release of the operating
108 system.
109
110 @item char machine[]
111 This is a description of the hardware type that the operating system
112 is running on.
113
114 The possible values for the GNU C library are as follows:
115
116 @quotation
117 @code{"i386"}, @code{"m68k"}, @code{"sparc"}
118 @end quotation
119
120 We try to keep these strings' contents the same as the symbols that the
121 GNU C compiler defines to indicate the type of machine.
122 @end table
123 @end deftp
124
125 @comment sys/utsname.h
126 @comment POSIX.1
127 @deftypefun int uname (struct utsname *@var{info})
128 The @code{uname} function fills in the structure pointed to by
129 @var{info} with information about the operating system and host machine.
130 A non-negative value indicates that the data was successfully stored.
131 @code{-1} as the value indicates an error.
132
133 @strong{Incomplete:} What can cause an error in this function?
134 @end deftypefun
135
136
137
138