]>
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 | .\" |
867c9b34 | 32 | .TH GETHOSTNAME 2 2019-10-10 "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> | |
68e4db0a | 37 | .PP |
fea681da MK |
38 | .BI "int gethostname(char *" name ", size_t " len ); |
39 | .br | |
40 | .BI "int sethostname(const char *" name ", size_t " len ); | |
68e4db0a | 41 | .PP |
cc4615cc MK |
42 | .in -4n |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
68e4db0a | 46 | .PP |
cc4615cc | 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 (): | |
d0544534 MK |
58 | .nf |
59 | Since glibc 2.21: | |
60 | .\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 | |
61 | _DEFAULT_SOURCE | |
62 | In glibc 2.19 and 2.20: | |
63 | _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) | |
64 | Up to and including glibc 2.19: | |
65 | _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) | |
66 | .fi | |
4833c277 MK |
67 | .PD |
68 | .ad | |
fea681da | 69 | .SH DESCRIPTION |
79ea6883 MK |
70 | These system calls are used to access or to change the system hostname. |
71 | More precisely, they operate on the hostname associated with the calling | |
72 | process's UTS namespace. | |
efeece04 | 73 | .PP |
1f9fdf42 MK |
74 | .BR sethostname () |
75 | sets the hostname to the value given in the character array | |
76 | .IR name . | |
fea681da | 77 | The |
1f9fdf42 MK |
78 | .I len |
79 | argument specifies the number of bytes in | |
80 | .IR name . | |
81 | (Thus, | |
82 | .I name | |
83 | does not require a terminating null byte.) | |
efeece04 | 84 | .PP |
63aa9df0 | 85 | .BR gethostname () |
1f9fdf42 MK |
86 | returns the null-terminated hostname in the character array |
87 | .IR name , | |
88 | which has a length of | |
89 | .I len | |
90 | bytes. | |
91 | If the null-terminated hostname is too large to fit, | |
92 | then the name is truncated, and no error is returned (but see NOTES below). | |
7ae2d975 | 93 | POSIX.1 says that if such truncation occurs, |
1f9fdf42 MK |
94 | then it is unspecified whether the returned buffer |
95 | includes a terminating null byte. | |
47297adb | 96 | .SH RETURN VALUE |
c13182ef MK |
97 | On success, zero is returned. |
98 | On error, \-1 is returned, and | |
fea681da MK |
99 | .I errno |
100 | is set appropriately. | |
101 | .SH ERRORS | |
102 | .TP | |
103 | .B EFAULT | |
104 | .I name | |
105 | is an invalid address. | |
106 | .TP | |
107 | .B EINVAL | |
108 | .I len | |
1f9fdf42 MK |
109 | is negative |
110 | .\" Can't occur for gethostbyname() wrapper, since 'len' has an | |
111 | .\" unsigned type; can occur for the underlying system call. | |
112 | or, for | |
e511ffb6 | 113 | .BR sethostname (), |
fea681da | 114 | .I len |
1f9fdf42 MK |
115 | is larger than the maximum allowed size. |
116 | .TP | |
117 | .B ENAMETOOLONG | |
118 | .RB "(glibc " gethostname ()) | |
fea681da MK |
119 | .I len |
120 | is smaller than the actual size. | |
1f9fdf42 MK |
121 | (Before version 2.1, glibc uses |
122 | .BR EINVAL | |
123 | for this case.) | |
fea681da MK |
124 | .TP |
125 | .B EPERM | |
126 | For | |
e511ffb6 | 127 | .BR sethostname (), |
fea681da MK |
128 | the caller did not have the |
129 | .B CAP_SYS_ADMIN | |
6e87fb0b MK |
130 | capability in the user namespace associated with its UTS namespace (see |
131 | .BR namespaces (7)). | |
47297adb | 132 | .SH CONFORMING TO |
bedd18e5 | 133 | SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). |
7ae2d975 | 134 | POSIX.1-2001 and POSIX.1-2008 specify |
e511ffb6 | 135 | .BR gethostname () |
fea681da | 136 | but not |
e511ffb6 | 137 | .BR sethostname (). |
fea681da | 138 | .SH NOTES |
2d986c92 | 139 | SUSv2 guarantees that "Host names are limited to 255 bytes". |
7ae2d975 | 140 | POSIX.1 guarantees that "Host names (not including |
682edefb | 141 | the terminating null byte) are limited to |
0daa9e92 | 142 | .B HOST_NAME_MAX |
2d986c92 | 143 | bytes". |
e8d2d05f MK |
144 | On Linux, |
145 | .B HOST_NAME_MAX | |
146 | is defined with the value 64, which has been the limit since Linux 1.0 | |
147 | (earlier kernels imposed a limit of 8 bytes). | |
0722a578 | 148 | .SS C library/kernel differences |
1f9fdf42 MK |
149 | The GNU C library does not employ the |
150 | .BR gethostname () | |
151 | system call; instead, it implements | |
c13182ef MK |
152 | .BR gethostname () |
153 | as a library function that calls | |
16055a24 | 154 | .BR uname (2) |
c13182ef | 155 | and copies up to |
16055a24 | 156 | .I len |
c13182ef MK |
157 | bytes from the returned |
158 | .I nodename | |
16055a24 MK |
159 | field into |
160 | .IR name . | |
161 | Having performed the copy, the function then checks if the length of the | |
162 | .I nodename | |
163 | was greater than or equal to | |
164 | .IR len , | |
c13182ef MK |
165 | and if it is, then the function returns \-1 with |
166 | .I errno | |
16055a24 | 167 | set to |
1f9fdf42 | 168 | .BR ENAMETOOLONG ; |
d185a510 | 169 | in this case, a terminating null byte is not included in the returned |
1f9fdf42 | 170 | .IR name . |
efeece04 | 171 | .PP |
c13182ef | 172 | Versions of glibc before 2.2 |
16055a24 MK |
173 | .\" At least glibc 2.0 and 2.1, older versions not checked |
174 | handle the case where the length of the | |
175 | .I nodename | |
176 | was greater than or equal to | |
0daa9e92 | 177 | .I len |
c13182ef | 178 | differently: nothing is copied into |
16055a24 MK |
179 | .I name |
180 | and the function returns \-1 with | |
c13182ef | 181 | .I errno |
16055a24 MK |
182 | set to |
183 | .BR ENAMETOOLONG . | |
47297adb | 184 | .SH SEE ALSO |
792f20ea | 185 | .BR hostname (1), |
fea681da MK |
186 | .BR getdomainname (2), |
187 | .BR setdomainname (2), | |
79ea6883 MK |
188 | .BR uname (2), |
189 | .BR uts_namespaces (7) |