Linux
2017-09-15
Aliases: sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2), sethostname(2)
man-pages-ru
Russian man pages from the Linux Documentation Project
manpages-dev
Manual pages about using GNU/Linux for development
man-pages
Linux kernel and C library user-space interface documentation
ИМЯ
gethostname, sethostname - получить/установить имя узла
ОБЗОР
#include <unistd.h>
sethostname():
int gethostname(char *name, size_t len);
int sethostname(const char *name, size_t len);
int sethostname(const char *name, size_t len);
Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):
gethostname():
Начиная с glibc 2.12: _BSD_SOURCE || _XOPEN_SOURCE >= 500
|| /* начиная с glibc 2.12: */ _POSIX_C_SOURCE >= 200112L
|| /* начиная с glibc 2.12: */ _POSIX_C_SOURCE >= 200112L
sethostname():
начиная с glibc 2.21: _DEFAULT_SOURCE в glibc 2.19 и 2.20: _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) до glibc 2.19, включительно: _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
ОПИСАНИЕ
Данные системные вызовы используются для получения или изменения имени узла системы. Точнее говоря, они работают с именем узла, связанным с пространством имён UTS вызывающего процесса.
Вызов sethostname() устанавливает имя узла равны значению, указанному в массиве символов name. Аргумент len определяет количество байт в name. (Таким образом, name не требует наличия завершающего байта с null.)
gethostname() возвращает имя узла с null на конце в массиве символов name длиной len байт. Если имя узла, оканчивающееся null, не помещается, то имя обрезается и ошибки не происходит (но смотрите ЗАМЕЧАНИЯ далее). В POSIX.1 сказано, что если обрезание произошло, то неясно, будет ли буфер содержать завершающий байт с null.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении возвращается 0. В случае ошибки возвращается -1, а errno устанавливается в соответствующее значение.
ОШИБКИ
EFAULT | name является неправильным адресом. |
EINVAL | len имеет отрицательное значение или для sethostname() длина len больше, чем максимально допустимое значение. |
ENAMETOOLONG | |
(gethostname() из glibc) len меньше чем реальный размер. (До версии 2.1, glibc возвращала в этом случае EINVAL.) | |
EPERM | Для работы с sethostname() у вызывающего нет мандата CAP_SYS_ADMIN в пользовательском пространстве имён, связанном с его пространством имён UTS (смотрите namespaces(7)). |
СООТВЕТСТВИЕ СТАНДАРТАМ
SVr4, 4.4BSD (данная функция впервые появилась в 4.2BSD). В POSIX.1-2001 и POSIX.1-2008 определена gethostname(), но нет sethostname().
ЗАМЕЧАНИЯ
SUSv2 гарантирует, что «Длина имени узла ограничена 255-ю байтами». POSIX.1 гарантирует, что «Длина имени узла (не включая завершающий нулевой символ) ограничена HOST_NAME_MAX байтами». В Linux значение HOST_NAME_MAX равно 64, которое было урезано начиная с Linux 1.0 (ранние версии имели предел в 8 байт).
Отличия между библиотекой C и ядром
Библиотека GNU C library не использует системный вызов gethostname(); вместо этого gethostname() в ней реализован в виде библиотечной функции, которая вызывает uname(2) и копирует до len байт в name из возвращаемого поля nodename. Выполнив копирование, функция проверяет, что длина nodename не больше или равна len, и если это обнаруживается, то функция возвращает -1, устанавливая значение errno равным ENAMETOOLONG; в этом случае в возвращаемое значение name завершающий null не добавляется.
Версии glibc до 2.2 обрабатывали случай превышения длины nodename по другому: ничего не копировалось в name и функция возвращала -1, устанавливая errno равным ENAMETOOLONG.