GETHOSTNAME

Section: Linux Programmer's Manual (2)
Updated: 2019-10-10
Index JM Home Page

名前

gethostname, sethostname - ホスト名の取得・設定をする

書式

#include <unistd.h>

int gethostname(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

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)

説明

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.

sethostname() は、ホスト名を、文字配列 name で指定された値に設定する。引数 len には、 name のバイト数を指定する (そのため、 name では文字列終端のヌルバイトは必要ない)。

gethostname() は、NULL 終端されたホスト名を、 len バイトの長さの文字配列 name に格納して返す。ヌル終端されたホスト名が格納先のバッファーよりも長い場合は、ホスト名は切り詰められ、エラーは返されない (下記の「注意」の節を参照)。 POSIX.1 では、結果の切り詰めが発生した場合に、返されたバッファーに終端のヌルバイトが含まれているかどうかは規定されていない。

返り値

成功した場合は 0 が返される。エラーの場合は -1 が返され、 errno が適切に設定される。

エラー

EFAULT: name が不正なアドレスである。
EINVAL: len が負である。 sethostname() において len が許容された最大サイズを越えている。
ENAMETOOLONG: (glibc gethostname() で) len が実際のホスト名の長さよりも小さい (glibc バージョン 2.1 より前では、この状況で EINVAL が使用される)。
EPERM: For sethostname(), the caller did not have the CAP_SYS_ADMIN capability in the user namespace associated with its UTS namespace (see 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 ライブラリは、 gethostname() システムコールを利用していない。その代わり、 gethostname() をライブラリ関数として実装しており、この関数は uname(2) を呼び出し、 uname(2) が返した nodename フィールド (の最大 len バイト) を name にコピーする。コピーを行った際に、この関数は nodename の長さが len 以上かの確認を行い、 len 以上の場合には -1 を返し、 errno に ENAMETOOLONG を設定する。この場合、返された name には終端のヌルバイトは含まれない。

バージョン 2.2 より前の glibc では、 nodename の長さが len 以上の場合の扱いが異なる; len 以上の場合には、 name には何もコピーせず、関数は -1 を返し、 errno に ENAMETOOLONG を設定する。

この文書について

この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。

Linux マニュアル一覧

[man1] [man2] [man3] [man4] [man5] [man6] [man7] [man8]
[a] [b] [c] [d] [e] [f] [g] [h] [i] [j] [k] [l] [m] [n] [o] [p] [q] [r] [s] [t] [u] [v] [w] [x] [y] [z]