]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>: | |
26 | .\" 'gethostname' is real system call on Linux/Alpha. | |
27 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
28 | .\" Modified 2000-06-04, 2001-12-15 by aeb | |
29 | .\" Modified 2004-06-17 by mtk | |
1f9fdf42 | 30 | .\" Modified 2008-11-27 by mtk |
fea681da | 31 | .\" |
5722c835 | 32 | .TH GETHOSTNAME 2 2015-07-23 "Linux" "Linux Programmer's Manual" |
fea681da | 33 | .SH NAME |
ddaec46d | 34 | gethostname, sethostname \- get/set hostname |
fea681da MK |
35 | .SH SYNOPSIS |
36 | .B #include <unistd.h> | |
37 | .sp | |
38 | .BI "int gethostname(char *" name ", size_t " len ); | |
39 | .br | |
40 | .BI "int sethostname(const char *" name ", size_t " len ); | |
cc4615cc MK |
41 | .sp |
42 | .in -4n | |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
46 | .sp | |
47 | .ad l | |
4833c277 | 48 | .PD 0 |
cc4615cc | 49 | .BR gethostname (): |
4833c277 | 50 | .RS 4 |
4833c277 | 51 | Since glibc 2.12: |
cc4615cc | 52 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 |
3ba63d80 MK |
53 | .br |
54 | || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200112L | |
4833c277 | 55 | .RE |
cc4615cc MK |
56 | .br |
57 | .BR sethostname (): | |
4833c277 | 58 | .RS 4 |
cc4615cc | 59 | _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) |
4833c277 MK |
60 | .RE |
61 | .PD | |
62 | .ad | |
fea681da | 63 | .SH DESCRIPTION |
ddaec46d | 64 | These system calls are used to access or to change the hostname of the |
fea681da | 65 | current processor. |
1f9fdf42 MK |
66 | |
67 | .BR sethostname () | |
68 | sets the hostname to the value given in the character array | |
69 | .IR name . | |
fea681da | 70 | The |
1f9fdf42 MK |
71 | .I len |
72 | argument specifies the number of bytes in | |
73 | .IR name . | |
74 | (Thus, | |
75 | .I name | |
76 | does not require a terminating null byte.) | |
77 | ||
63aa9df0 | 78 | .BR gethostname () |
1f9fdf42 MK |
79 | returns the null-terminated hostname in the character array |
80 | .IR name , | |
81 | which has a length of | |
82 | .I len | |
83 | bytes. | |
84 | If the null-terminated hostname is too large to fit, | |
85 | then the name is truncated, and no error is returned (but see NOTES below). | |
7ae2d975 | 86 | POSIX.1 says that if such truncation occurs, |
1f9fdf42 MK |
87 | then it is unspecified whether the returned buffer |
88 | includes a terminating null byte. | |
47297adb | 89 | .SH RETURN VALUE |
c13182ef MK |
90 | On success, zero is returned. |
91 | On error, \-1 is returned, and | |
fea681da MK |
92 | .I errno |
93 | is set appropriately. | |
94 | .SH ERRORS | |
95 | .TP | |
96 | .B EFAULT | |
97 | .I name | |
98 | is an invalid address. | |
99 | .TP | |
100 | .B EINVAL | |
101 | .I len | |
1f9fdf42 MK |
102 | is negative |
103 | .\" Can't occur for gethostbyname() wrapper, since 'len' has an | |
104 | .\" unsigned type; can occur for the underlying system call. | |
105 | or, for | |
e511ffb6 | 106 | .BR sethostname (), |
fea681da | 107 | .I len |
1f9fdf42 MK |
108 | is larger than the maximum allowed size. |
109 | .TP | |
110 | .B ENAMETOOLONG | |
111 | .RB "(glibc " gethostname ()) | |
fea681da MK |
112 | .I len |
113 | is smaller than the actual size. | |
1f9fdf42 MK |
114 | (Before version 2.1, glibc uses |
115 | .BR EINVAL | |
116 | for this case.) | |
fea681da MK |
117 | .TP |
118 | .B EPERM | |
119 | For | |
e511ffb6 | 120 | .BR sethostname (), |
fea681da MK |
121 | the caller did not have the |
122 | .B CAP_SYS_ADMIN | |
123 | capability. | |
47297adb | 124 | .SH CONFORMING TO |
bedd18e5 | 125 | SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). |
7ae2d975 | 126 | POSIX.1-2001 and POSIX.1-2008 specify |
e511ffb6 | 127 | .BR gethostname () |
fea681da | 128 | but not |
e511ffb6 | 129 | .BR sethostname (). |
fea681da | 130 | .SH NOTES |
2d986c92 | 131 | SUSv2 guarantees that "Host names are limited to 255 bytes". |
7ae2d975 | 132 | POSIX.1 guarantees that "Host names (not including |
682edefb | 133 | the terminating null byte) are limited to |
0daa9e92 | 134 | .B HOST_NAME_MAX |
2d986c92 | 135 | bytes". |
e8d2d05f MK |
136 | On Linux, |
137 | .B HOST_NAME_MAX | |
138 | is defined with the value 64, which has been the limit since Linux 1.0 | |
139 | (earlier kernels imposed a limit of 8 bytes). | |
0722a578 | 140 | .SS C library/kernel differences |
1f9fdf42 MK |
141 | The GNU C library does not employ the |
142 | .BR gethostname () | |
143 | system call; instead, it implements | |
c13182ef MK |
144 | .BR gethostname () |
145 | as a library function that calls | |
16055a24 | 146 | .BR uname (2) |
c13182ef | 147 | and copies up to |
16055a24 | 148 | .I len |
c13182ef MK |
149 | bytes from the returned |
150 | .I nodename | |
16055a24 MK |
151 | field into |
152 | .IR name . | |
153 | Having performed the copy, the function then checks if the length of the | |
154 | .I nodename | |
155 | was greater than or equal to | |
156 | .IR len , | |
c13182ef MK |
157 | and if it is, then the function returns \-1 with |
158 | .I errno | |
16055a24 | 159 | set to |
1f9fdf42 | 160 | .BR ENAMETOOLONG ; |
d185a510 | 161 | in this case, a terminating null byte is not included in the returned |
1f9fdf42 MK |
162 | .IR name . |
163 | ||
c13182ef | 164 | Versions of glibc before 2.2 |
16055a24 MK |
165 | .\" At least glibc 2.0 and 2.1, older versions not checked |
166 | handle the case where the length of the | |
167 | .I nodename | |
168 | was greater than or equal to | |
0daa9e92 | 169 | .I len |
c13182ef | 170 | differently: nothing is copied into |
16055a24 MK |
171 | .I name |
172 | and the function returns \-1 with | |
c13182ef | 173 | .I errno |
16055a24 MK |
174 | set to |
175 | .BR ENAMETOOLONG . | |
47297adb | 176 | .SH SEE ALSO |
fea681da MK |
177 | .BR getdomainname (2), |
178 | .BR setdomainname (2), | |
179 | .BR uname (2) |