diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-04-26 15:06:49 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-05-02 01:24:19 +0200 |
| commit | dcde2f70372b49ec43efc5db864c9ff585d0a2dd (patch) | |
| tree | 78b9b7425130e4a5858e4c01a524d802423879ed /man/man2/gethostname.2 | |
| parent | 12aca537ce78a41bbcdaf485209691e10f8002d7 (diff) | |
| download | man-pages-dcde2f70372b49ec43efc5db864c9ff585d0a2dd.tar.gz | |
man/, share/mk/: Move man*/ to man/
This is a scripted change:
$ mkdir man/;
$ mv man* man/;
$ ln -st . man/man*;
$ find share/mk/ -type f \
| xargs grep -l '^MANDIR *:=' \
| xargs sed -i '/^MANDIR *:=/s,$,/man,';
$ find share/mk/dist/ -type f \
| xargs grep -l man \
| xargs sed -i 's,man%,man/%,g';
Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/>
Cc: Petr Vorel <pvorel@suse.cz>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man/man2/gethostname.2')
| -rw-r--r-- | man/man2/gethostname.2 | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/man/man2/gethostname.2 b/man/man2/gethostname.2 new file mode 100644 index 0000000000..1a9fc0d2fc --- /dev/null +++ b/man/man2/gethostname.2 @@ -0,0 +1,176 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>: +.\" 'gethostname' is real system call on Linux/Alpha. +.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 2000-06-04, 2001-12-15 by aeb +.\" Modified 2004-06-17 by mtk +.\" Modified 2008-11-27 by mtk +.\" +.TH gethostname 2 (date) "Linux man-pages (unreleased)" +.SH NAME +gethostname, sethostname \- get/set hostname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int gethostname(char *" name ", size_t " len ); +.BI "int sethostname(const char *" name ", size_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gethostname (): +.nf + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L + || /* glibc 2.19 and earlier */ _BSD_SOURCE +.\" The above is something of a simplification +.\" also before glibc 2.3 there was a bit churn +.fi +.P +.BR sethostname (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +These system calls are used to access or to change the system hostname. +More precisely, they operate on the hostname associated with the calling +process's UTS namespace. +.P +.BR sethostname () +sets the hostname to the value given in the character array +.IR name . +The +.I len +argument specifies the number of bytes in +.IR name . +(Thus, +.I name +does not require a terminating null byte.) +.P +.BR gethostname () +returns the null-terminated hostname in the character array +.IR name , +which has a length of +.I len +bytes. +If the null-terminated hostname is too large to fit, +then the name is truncated, and no error is returned (but see NOTES below). +POSIX.1 says that if such truncation occurs, +then it is unspecified whether the returned buffer +includes a terminating null byte. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I name +is an invalid address. +.TP +.B EINVAL +.I len +is negative +.\" Can't occur for gethostbyname() wrapper, since 'len' has an +.\" unsigned type; can occur for the underlying system call. +or, for +.BR sethostname (), +.I len +is larger than the maximum allowed size. +.TP +.B ENAMETOOLONG +.RB "(glibc " gethostname ()) +.I len +is smaller than the actual size. +(Before glibc 2.1, glibc uses +.B EINVAL +for this case.) +.TP +.B EPERM +For +.BR sethostname (), +the caller did not have the +.B CAP_SYS_ADMIN +capability in the user namespace associated with its UTS namespace (see +.BR namespaces (7)). +.SH VERSIONS +SUSv2 guarantees that "Host names are limited to 255 bytes". +POSIX.1 guarantees that "Host names (not including +the terminating null byte) are limited to +.B HOST_NAME_MAX +bytes". +On Linux, +.B HOST_NAME_MAX +is defined with the value 64, which has been the limit since Linux 1.0 +(earlier kernels imposed a limit of 8 bytes). +.SS C library/kernel differences +The GNU C library does not employ the +.BR gethostname () +system call; instead, it implements +.BR gethostname () +as a library function that calls +.BR uname (2) +and copies up to +.I len +bytes from the returned +.I nodename +field into +.IR name . +Having performed the copy, the function then checks if the length of the +.I nodename +was greater than or equal to +.IR len , +and if it is, then the function returns \-1 with +.I errno +set to +.BR ENAMETOOLONG ; +in this case, a terminating null byte is not included in the returned +.IR name . +.SH STANDARDS +.TP +.BR gethostname () +POSIX.1-2008. +.TP +.BR sethostname () +None. +.SH HISTORY +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +POSIX.1-2001 and POSIX.1-2008 specify +.BR gethostname () +but not +.BR sethostname (). +.P +Versions of glibc before glibc 2.2 +.\" At least glibc 2.0 and glibc 2.1, older versions not checked +handle the case where the length of the +.I nodename +was greater than or equal to +.I len +differently: nothing is copied into +.I name +and the function returns \-1 with +.I errno +set to +.BR ENAMETOOLONG . +.SH SEE ALSO +.BR hostname (1), +.BR getdomainname (2), +.BR setdomainname (2), +.BR uname (2), +.BR uts_namespaces (7) |