manual/LDP_man-pages/draft/man2/gethostname.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>:
  27 .\"   'gethostname' is real system call on Linux/Alpha.
  28 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  29 .\" Modified 2000-06-04, 2001-12-15 by aeb
  30 .\" Modified 2004-06-17 by mtk
  31 .\" Modified 2008-11-27 by mtk
  32 .\"
  33 .\" Japanese Version Copyright (c) 1997 SUTO, Mitsuaki
  34 .\"         all rights reserved.
  35 .\" Translated 1997-06-27, SUTO, Mitsuaki <suto@av.crl.sony.co.jp>
  36 .\" Updated 2000-09-30, Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
  37 .\" Updated & Modified 2002-01-14, Yuichi SATO <ysato@h4.dion.ne.jp>
  38 .\" Updated & Modified 2004-12-30, Yuichi SATO <ysato444@yahoo.co.jp>
  39 .\" Updated & Modified 2006-01-31, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  40 .\" Updated 2008-12-26, Akihiro MOTOKI, LDP v3.15
  41 .\"
  42 .TH GETHOSTNAME 2 2010-09-26 "Linux" "Linux Programmer's Manual"
  43 .\"O .SH NAME
  44 .SH 名前
  45 .\"O gethostname, sethostname \- get/set hostname
  46 gethostname, sethostname \- ホスト名の取得・設定をする
  47 .\"O .SH SYNOPSIS
  48 .SH 書式
  49 .B #include <unistd.h>
  50 .sp
  51 .BI "int gethostname(char *" name ", size_t " len );
  52 .br
  53 .BI "int sethostname(const char *" name ", size_t " len );
  54 .sp
  55 .in -4n
  56 .\"O Feature Test Macro Requirements for glibc (see
  57 .\"O .BR feature_test_macros (7)):
  58 glibc 向けの機能検査マクロの要件
  59 .RB ( feature_test_macros (7)
  60 参照):
  61 .in
  62 .sp
  63 .ad l
  64 .PD 0
  65 .BR gethostname ():
  66 .RS 4
  67 .\"O Since glibc 2.12:
  68 glibc 2.12 以降:
  69 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
  70 .br
  71 .\"O || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200112L
  72 || /* glibc 2.12 以降: */ _POSIX_C_SOURCE\ >=\ 200112L
  73 .RE
  74 .br
  75 .BR sethostname ():
  76 .RS 4
  77 _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
  78 .RE
  79 .PD
  80 .ad
  81 .\"O .SH DESCRIPTION
  82 .SH 説明
  83 .\"O These system calls are used to access or to change the hostname of the
  84 .\"O current processor.
  85 これらのシステムコールは、現在のプロセッサのホスト名を取得・変更するために
  86 使用される。
  87
  88 .\"O .BR sethostname ()
  89 .\"O sets the hostname to the value given in the character array
  90 .\"O .IR name .
  91 .\"O The
  92 .\"O .I len
  93 .\"O argument specifies the number of bytes in
  94 .\"O .IR name .
  95 .\"O (Thus,
  96 .\"O .I name
  97 .\"O does not require a terminating null byte.)
  98 .BR sethostname ()
  99 は、ホスト名を、文字配列
 100 .I name
 101 で指定された値に設定する。
 102 引き数
 103 .I len
 104 には、
 105 .I name
 106 のバイト数を指定する
 107 (そのため、
 108 .I name
 109 では文字列終端の NULL バイトは必要ない)。
 110
 111 .\"O .BR gethostname ()
 112 .\"O returns the null-terminated hostname in the character array
 113 .\"O .IR name ,
 114 .\"O which has a length of
 115 .\"O .I len
 116 .\"O bytes.
 117 .\"O If the null-terminated hostname is too large to fit,
 118 .\"O then the name is truncated, and no error is returned (but see NOTES below).
 119 .\"O POSIX.1-2001 says that if such truncation occurs,
 120 .\"O then it is unspecified whether the returned buffer
 121 .\"O includes a terminating null byte.
 122 .BR gethostname ()
 123 は、NULL 終端されたホスト名を、
 124 .I len
 125 バイトの長さの文字配列
 126 .I name
 127 に格納して返す。
 128 NULL 終端されたホスト名が格納先のバッファよりも長い場合は、
 129 ホスト名は切り詰められ、エラーは返されない (下記の「注意」の節を参照)。
 130 POSIX.1-2001 では、結果の切り詰めが発生した場合に、
 131 返されたバッファに終端の NULL バイトが含まれているかどうかは
 132 規定されていない。
 133 .\"O .SH "RETURN VALUE"
 134 .SH 返り値
 135 .\"O On success, zero is returned.
 136 .\"O On error, \-1 is returned, and
 137 .\"O .I errno
 138 .\"O is set appropriately.
 139 成功した場合 0 が返る。失敗した場合 \-1 が返り、
 140 .I errno
 141 がエラーの内容に従って設定される。
 142 .\"O .SH ERRORS
 143 .SH エラー
 144 .TP
 145 .B EFAULT
 146 .\"O .I name
 147 .\"O is an invalid address.
 148 .I name
 149 が不正なアドレスである。
 150 .TP
 151 .B EINVAL
 152 .\"O .I len
 153 .\"O is negative
 154 .\"O .\" Can't occur for gethostbyname() wrapper, since 'len' has an
 155 .\"O .\" unsigned type; can occur for the underlying system call.
 156 .\"O or, for
 157 .\"O .BR sethostname (),
 158 .\"O .I len
 159 .\"O is larger than the maximum allowed size.
 160 .I len
 161 が負である。
 162 .\" gethostbyname() ラッパー関数では、'len' は unsigned 型なので
 163 .\" このエラーが発生することはない。
 164 .\" その中で呼ばれるシステムコールでは発生することがある。
 165 .BR sethostname ()
 166 において
 167 .I len
 168 が許容された最大サイズを越えている。
 169 .TP
 170 .B ENAMETOOLONG
 171 .\"O .RB "(glibc " gethostname ())
 172 .\"O .I len
 173 .\"O is smaller than the actual size.
 174 .\"O (Before version 2.1, glibc uses
 175 .\"O .BR EINVAL
 176 .\"O for this case.)
 177 .RB "(glibc " gethostname ()
 178 で)
 179 .I len
 180 が実際のホスト名の長さよりも小さい
 181 (glibc バージョン 2.1 より前では、この状況で
 182 .B EINVAL
 183 が使用される)。
 184 .TP
 185 .B EPERM
 186 .\"O For
 187 .\"O .BR sethostname (),
 188 .\"O the caller did not have the
 189 .\"O .B CAP_SYS_ADMIN
 190 .\"O capability.
 191 .BR sethostname ()
 192 において、呼び出した人が
 193 .B CAP_SYS_ADMIN
 194 ケーパビリティ (capability) を持っていなかった。
 195 .\"O .SH "CONFORMING TO"
 196 .SH 準拠
 197 .\"O SVr4, 4.4BSD  (these interfaces first appeared in 4.2BSD).
 198 .\"O POSIX.1-2001 specifies
 199 .\"O .BR gethostname ()
 200 .\"O but not
 201 .\"O .BR sethostname ().
 202 SVr4, 4.4BSD  (これらのインタフェースは 4.2BSD で初めて登場した)。
 203 POSIX.1-2001 では
 204 .BR gethostname ()
 205 については規定しているが、
 206 .BR sethostname ()
 207 は規定していない。
 208 .\"O .SH NOTES
 209 .SH 注意
 210 .\"O SUSv2 guarantees that "Host names are limited to 255 bytes".
 211 .\"O POSIX.1-2001 guarantees that "Host names (not including
 212 .\"O the terminating null byte) are limited to
 213 .\"O .B HOST_NAME_MAX
 214 .\"O bytes".
 215 SUSv2 では「ホスト名が 255 バイトに制限される」ことを保証している。
 216 POSIX.1-2001 では「ホスト名 (終端の NULL バイトは含まない) が
 217 .B HOST_NAME_MAX
 218 バイトに制限される」ことを保証している。
 219 .\"O On Linux,
 220 .\"O .B HOST_NAME_MAX
 221 .\"O is defined with the value 64, which has been the limit since Linux 1.0
 222 .\"O (earlier kernels imposed a limit of 8 bytes).
 223 Linux では、
 224 .B HOST_NAME_MAX
 225 は 64 に定義されており、
 226 Linux 1.0 以降ではこれが上限となってきた
 227 (もっと古いカーネルでは 8 バイトの上限が適用されていた)。
 228 .\"O .SS Glibc Notes
 229 .SS "glibc での注意"
 230 .\"O The GNU C library does not employ the
 231 .\"O .BR gethostname ()
 232 .\"O system call; instead, it implements
 233 .\"O .BR gethostname ()
 234 .\"O as a library function that calls
 235 .\"O .BR uname (2)
 236 .\"O and copies up to
 237 .\"O .I len
 238 .\"O bytes from the returned
 239 .\"O .I nodename
 240 .\"O field into
 241 .\"O .IR name .
 242 GNU C ライブラリは、
 243 .BR gethostname ()
 244 システムコールを利用していない。その代わり、
 245 .BR gethostname ()
 246 をライブラリ関数として実装しており、
 247 この関数は
 248 .BR uname (2)
 249 を呼び出し、
 250 .BR uname (2)
 251 が返した
 252 .I nodename
 253 フィールド (の最大
 254 .I len
 255 バイト) を
 256 .I name
 257 にコピーする。
 258 .\"O Having performed the copy, the function then checks if the length of the
 259 .\"O .I nodename
 260 .\"O was greater than or equal to
 261 .\"O .IR len ,
 262 .\"O and if it is, then the function returns \-1 with
 263 .\"O .I errno
 264 .\"O set to
 265 .\"O .BR ENAMETOOLONG ;
 266 .\"O in this case, a terminating null byte is not included in the returned
 267 .\"O .IR name .
 268 コピーを行った際に、この関数は
 269 .I nodename
 270 の長さが
 271 .I len
 272 以上かの確認を行い、
 273 .I len
 274 以上の場合には \-1 を返し、
 275 .I errno
 276 に
 277 .B ENAMETOOLONG
 278 を設定する。
 279 この場合、返された
 280 .I name
 281 には終端の NULL バイトは含まれない。
 282
 283 .\"O Versions of glibc before 2.2
 284 .\"O .\" At least glibc 2.0 and 2.1, older versions not checked
 285 .\"O handle the case where the length of the
 286 .\"O .I nodename
 287 .\"O was greater than or equal to
 288 .\"O .I len
 289 .\"O differently: nothing is copied into
 290 .\"O .I name
 291 .\"O and the function returns \-1 with
 292 .\"O .I errno
 293 .\"O set to
 294 .\"O .BR ENAMETOOLONG .
 295 バージョン 2.2 より前の glibc
 296 .\" 少なくとも glibc 2.0 と 2.1。それより古いバージョンは未確認
 297 では、
 298 .I nodename
 299 の長さが
 300 .I len
 301 以上の場合の扱いが異なる;
 302 .I len
 303 以上の場合には、
 304 .I name
 305 には何もコピーせず、関数は \-1 を返し、
 306 .I errno
 307 に
 308 .B ENAMETOOLONG
 309 を設定する。
 310 .\"O .SH "SEE ALSO"
 311 .SH 関連項目
 312 .BR getdomainname (2),
 313 .BR setdomainname (2),
 314 .BR uname (2)