]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>: | |
6 | .\" 'gethostname' is real system call on Linux/Alpha. | |
7 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
8 | .\" Modified 2000-06-04, 2001-12-15 by aeb | |
9 | .\" Modified 2004-06-17 by mtk | |
1f9fdf42 | 10 | .\" Modified 2008-11-27 by mtk |
fea681da | 11 | .\" |
1d767b55 | 12 | .TH GETHOSTNAME 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da | 13 | .SH NAME |
ddaec46d | 14 | gethostname, sethostname \- get/set hostname |
59704a01 AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da | 18 | .SH SYNOPSIS |
4653ec6e | 19 | .nf |
fea681da | 20 | .B #include <unistd.h> |
68e4db0a | 21 | .PP |
fea681da | 22 | .BI "int gethostname(char *" name ", size_t " len ); |
fea681da | 23 | .BI "int sethostname(const char *" name ", size_t " len ); |
4653ec6e | 24 | .fi |
68e4db0a | 25 | .PP |
d39ad78f | 26 | .RS -4 |
cc4615cc MK |
27 | Feature Test Macro Requirements for glibc (see |
28 | .BR feature_test_macros (7)): | |
d39ad78f | 29 | .RE |
68e4db0a | 30 | .PP |
cc4615cc | 31 | .BR gethostname (): |
9d2adbae | 32 | .nf |
5c10d2c5 | 33 | _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L |
58a6844d | 34 | || /* Glibc 2.19 and earlier */ _BSD_SOURCE |
6e5cd0d9 MK |
35 | .\" The above is something of a simplification |
36 | .\" also in glibc before 2.3 there was a bit churn | |
9d2adbae | 37 | .fi |
98c9347c | 38 | .PP |
cc4615cc | 39 | .BR sethostname (): |
d0544534 MK |
40 | .nf |
41 | Since glibc 2.21: | |
42 | .\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 | |
43 | _DEFAULT_SOURCE | |
44 | In glibc 2.19 and 2.20: | |
5c10d2c5 | 45 | _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) |
d0544534 | 46 | Up to and including glibc 2.19: |
5c10d2c5 | 47 | _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) |
d0544534 | 48 | .fi |
fea681da | 49 | .SH DESCRIPTION |
79ea6883 MK |
50 | These system calls are used to access or to change the system hostname. |
51 | More precisely, they operate on the hostname associated with the calling | |
52 | process's UTS namespace. | |
efeece04 | 53 | .PP |
1f9fdf42 MK |
54 | .BR sethostname () |
55 | sets the hostname to the value given in the character array | |
56 | .IR name . | |
fea681da | 57 | The |
1f9fdf42 MK |
58 | .I len |
59 | argument specifies the number of bytes in | |
60 | .IR name . | |
61 | (Thus, | |
62 | .I name | |
63 | does not require a terminating null byte.) | |
efeece04 | 64 | .PP |
63aa9df0 | 65 | .BR gethostname () |
1f9fdf42 MK |
66 | returns the null-terminated hostname in the character array |
67 | .IR name , | |
68 | which has a length of | |
69 | .I len | |
70 | bytes. | |
71 | If the null-terminated hostname is too large to fit, | |
72 | then the name is truncated, and no error is returned (but see NOTES below). | |
7ae2d975 | 73 | POSIX.1 says that if such truncation occurs, |
1f9fdf42 MK |
74 | then it is unspecified whether the returned buffer |
75 | includes a terminating null byte. | |
47297adb | 76 | .SH RETURN VALUE |
c13182ef MK |
77 | On success, zero is returned. |
78 | On error, \-1 is returned, and | |
fea681da | 79 | .I errno |
f6a4078b | 80 | is set to indicate the error. |
fea681da MK |
81 | .SH ERRORS |
82 | .TP | |
83 | .B EFAULT | |
84 | .I name | |
85 | is an invalid address. | |
86 | .TP | |
87 | .B EINVAL | |
88 | .I len | |
1f9fdf42 MK |
89 | is negative |
90 | .\" Can't occur for gethostbyname() wrapper, since 'len' has an | |
91 | .\" unsigned type; can occur for the underlying system call. | |
92 | or, for | |
e511ffb6 | 93 | .BR sethostname (), |
fea681da | 94 | .I len |
1f9fdf42 MK |
95 | is larger than the maximum allowed size. |
96 | .TP | |
97 | .B ENAMETOOLONG | |
98 | .RB "(glibc " gethostname ()) | |
fea681da MK |
99 | .I len |
100 | is smaller than the actual size. | |
1f9fdf42 | 101 | (Before version 2.1, glibc uses |
1ae6b2c7 | 102 | .B EINVAL |
1f9fdf42 | 103 | for this case.) |
fea681da MK |
104 | .TP |
105 | .B EPERM | |
106 | For | |
e511ffb6 | 107 | .BR sethostname (), |
fea681da MK |
108 | the caller did not have the |
109 | .B CAP_SYS_ADMIN | |
6e87fb0b MK |
110 | capability in the user namespace associated with its UTS namespace (see |
111 | .BR namespaces (7)). | |
47297adb | 112 | .SH CONFORMING TO |
bedd18e5 | 113 | SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). |
7ae2d975 | 114 | POSIX.1-2001 and POSIX.1-2008 specify |
e511ffb6 | 115 | .BR gethostname () |
fea681da | 116 | but not |
e511ffb6 | 117 | .BR sethostname (). |
fea681da | 118 | .SH NOTES |
2d986c92 | 119 | SUSv2 guarantees that "Host names are limited to 255 bytes". |
7ae2d975 | 120 | POSIX.1 guarantees that "Host names (not including |
682edefb | 121 | the terminating null byte) are limited to |
0daa9e92 | 122 | .B HOST_NAME_MAX |
2d986c92 | 123 | bytes". |
e8d2d05f MK |
124 | On Linux, |
125 | .B HOST_NAME_MAX | |
126 | is defined with the value 64, which has been the limit since Linux 1.0 | |
127 | (earlier kernels imposed a limit of 8 bytes). | |
0722a578 | 128 | .SS C library/kernel differences |
1f9fdf42 MK |
129 | The GNU C library does not employ the |
130 | .BR gethostname () | |
131 | system call; instead, it implements | |
c13182ef MK |
132 | .BR gethostname () |
133 | as a library function that calls | |
16055a24 | 134 | .BR uname (2) |
c13182ef | 135 | and copies up to |
16055a24 | 136 | .I len |
c13182ef MK |
137 | bytes from the returned |
138 | .I nodename | |
16055a24 MK |
139 | field into |
140 | .IR name . | |
141 | Having performed the copy, the function then checks if the length of the | |
142 | .I nodename | |
143 | was greater than or equal to | |
144 | .IR len , | |
c13182ef MK |
145 | and if it is, then the function returns \-1 with |
146 | .I errno | |
16055a24 | 147 | set to |
1f9fdf42 | 148 | .BR ENAMETOOLONG ; |
d185a510 | 149 | in this case, a terminating null byte is not included in the returned |
1f9fdf42 | 150 | .IR name . |
efeece04 | 151 | .PP |
c13182ef | 152 | Versions of glibc before 2.2 |
16055a24 MK |
153 | .\" At least glibc 2.0 and 2.1, older versions not checked |
154 | handle the case where the length of the | |
155 | .I nodename | |
156 | was greater than or equal to | |
0daa9e92 | 157 | .I len |
c13182ef | 158 | differently: nothing is copied into |
16055a24 MK |
159 | .I name |
160 | and the function returns \-1 with | |
c13182ef | 161 | .I errno |
16055a24 MK |
162 | set to |
163 | .BR ENAMETOOLONG . | |
47297adb | 164 | .SH SEE ALSO |
792f20ea | 165 | .BR hostname (1), |
fea681da MK |
166 | .BR getdomainname (2), |
167 | .BR setdomainname (2), | |
79ea6883 MK |
168 | .BR uname (2), |
169 | .BR uts_namespaces (7) |