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 2008-11-27 "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 .BR gethostname ():
  65 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
  66 .br
  67 .BR sethostname ():
  68 _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
  69 .ad b
  70 .\"O .SH DESCRIPTION
  71 .SH ÀâÌÀ
  72 .\"O These system calls are used to access or to change the hostname of the
  73 .\"O current processor.
  74 ¤³¤ì¤é¤Î¥·¥¹¥Æ¥à¥³¡¼¥ë¤Ï¡¢¸½ºß¤Î¥×¥í¥»¥Ã¥µ¤Î¥Û¥¹¥ÈÌ¾¤ò¼èÆÀ¡¦ÊÑ¹¹¤¹¤ë¤¿¤á¤Ë
  75 »ÈÍÑ¤µ¤ì¤ë¡£
  76
  77 .\"O .BR sethostname ()
  78 .\"O sets the hostname to the value given in the character array
  79 .\"O .IR name .
  80 .\"O The
  81 .\"O .I len
  82 .\"O argument specifies the number of bytes in
  83 .\"O .IR name .
  84 .\"O (Thus,
  85 .\"O .I name
  86 .\"O does not require a terminating null byte.)
  87 .BR sethostname ()
  88 ¤Ï¡¢¥Û¥¹¥ÈÌ¾¤ò¡¢Ê¸»úÇÛÎó
  89 .I name
  90 ¤Ç»ØÄê¤µ¤ì¤¿ÃÍ¤ËÀßÄê¤¹¤ë¡£
  91 °ú¤¿ô
  92 .I len
  93 ¤Ë¤Ï¡¢
  94 .I name
  95 ¤Î¥Ð¥¤¥È¿ô¤ò»ØÄê¤¹¤ë
  96 (¤½¤Î¤¿¤á¡¢
  97 .I name
  98 ¤Ç¤ÏÊ¸»úÎó½ªÃ¼¤Î NULL ¥Ð¥¤¥È¤ÏÉ¬Í×¤Ê¤¤)¡£
  99
 100 .\"O .BR gethostname ()
 101 .\"O returns the null-terminated hostname in the character array
 102 .\"O .IR name ,
 103 .\"O which has a length of
 104 .\"O .I len
 105 .\"O bytes.
 106 .\"O If the null-terminated hostname is too large to fit,
 107 .\"O then the name is truncated, and no error is returned (but see NOTES below).
 108 .\"O POSIX.1-2001 says that if such truncation occurs,
 109 .\"O then it is unspecified whether the returned buffer
 110 .\"O includes a terminating null byte.
 111 .BR gethostname ()
 112 ¤Ï¡¢NULL ½ªÃ¼¤µ¤ì¤¿¥Û¥¹¥ÈÌ¾¤ò¡¢
 113 .I len
 114 ¥Ð¥¤¥È¤ÎÄ¹¤µ¤ÎÊ¸»úÇÛÎó
 115 .I name
 116 ¤Ë³ÊÇ¼¤·¤ÆÊÖ¤¹¡£
 117 NULL ½ªÃ¼¤µ¤ì¤¿¥Û¥¹¥ÈÌ¾¤¬³ÊÇ¼Àè¤Î¥Ð¥Ã¥Õ¥¡¤è¤ê¤âÄ¹¤¤¾ì¹ç¤Ï¡¢
 118 ¥Û¥¹¥ÈÌ¾¤ÏÀÚ¤êµÍ¤á¤é¤ì¡¢¥¨¥é¡¼¤ÏÊÖ¤µ¤ì¤Ê¤¤ (²¼µ¤Î¡ÖÃí°Õ¡×¤ÎÀá¤ò»²¾È)¡£
 119 POSIX.1-2001 ¤Ç¤Ï¡¢·ë²Ì¤ÎÀÚ¤êµÍ¤á¤¬È¯À¸¤·¤¿¾ì¹ç¤Ë¡¢
 120 ÊÖ¤µ¤ì¤¿¥Ð¥Ã¥Õ¥¡¤Ë½ªÃ¼¤Î NULL ¥Ð¥¤¥È¤¬´Þ¤Þ¤ì¤Æ¤¤¤ë¤«¤É¤¦¤«¤Ï
 121 µ¬Äê¤µ¤ì¤Æ¤¤¤Ê¤¤¡£
 122 .\"O .SH "RETURN VALUE"
 123 .SH ÊÖ¤êÃÍ
 124 .\"O On success, zero is returned.
 125 .\"O On error, \-1 is returned, and
 126 .\"O .I errno
 127 .\"O is set appropriately.
 128 À®¸ù¤·¤¿¾ì¹ç 0 ¤¬ÊÖ¤ë¡£¼ºÇÔ¤·¤¿¾ì¹ç \-1 ¤¬ÊÖ¤ê¡¢
 129 .I errno
 130 ¤¬¥¨¥é¡¼¤ÎÆâÍÆ¤Ë½¾¤Ã¤ÆÀßÄê¤µ¤ì¤ë¡£
 131 .\"O .SH ERRORS
 132 .SH ¥¨¥é¡¼
 133 .TP
 134 .B EFAULT
 135 .\"O .I name
 136 .\"O is an invalid address.
 137 .I name
 138 ¤¬ÉÔÀµ¤Ê¥¢¥É¥ì¥¹¤Ç¤¢¤ë¡£
 139 .TP
 140 .B EINVAL
 141 .\"O .I len
 142 .\"O is negative
 143 .\"O .\" Can't occur for gethostbyname() wrapper, since 'len' has an
 144 .\"O .\" unsigned type; can occur for the underlying system call.
 145 .\"O or, for
 146 .\"O .BR sethostname (),
 147 .\"O .I len
 148 .\"O is larger than the maximum allowed size.
 149 .I len
 150 ¤¬Éé¤Ç¤¢¤ë¡£
 151 .\" gethostbyname() ¥é¥Ã¥Ñ¡¼´Ø¿ô¤Ç¤Ï¡¢'len' ¤Ï unsigned ·¿¤Ê¤Î¤Ç
 152 .\" ¤³¤Î¥¨¥é¡¼¤¬È¯À¸¤¹¤ë¤³¤È¤Ï¤Ê¤¤¡£
 153 .\" ¤½¤ÎÃæ¤Ç¸Æ¤Ð¤ì¤ë¥·¥¹¥Æ¥à¥³¡¼¥ë¤Ç¤ÏÈ¯À¸¤¹¤ë¤³¤È¤¬¤¢¤ë¡£
 154 .BR sethostname ()
 155 ¤Ë¤ª¤¤¤Æ
 156 .I len
 157 ¤¬µöÍÆ¤µ¤ì¤¿ºÇÂç¥µ¥¤¥º¤ò±Û¤¨¤Æ¤¤¤ë¡£
 158 .TP
 159 .B ENAMETOOLONG
 160 .\"O .RB "(glibc " gethostname ())
 161 .\"O .I len
 162 .\"O is smaller than the actual size.
 163 .\"O (Before version 2.1, glibc uses
 164 .\"O .BR EINVAL
 165 .\"O for this case.)
 166 .RB "(glibc " gethostname ()
 167 ¤Ç)
 168 .I len
 169 ¤¬¼ÂºÝ¤Î¥Û¥¹¥ÈÌ¾¤ÎÄ¹¤µ¤è¤ê¤â¾®¤µ¤¤
 170 (glibc ¥Ð¡¼¥¸¥ç¥ó 2.1 ¤è¤êÁ°¤Ç¤Ï¡¢¤³¤Î¾õ¶·¤Ç
 171 .B EINVAL
 172 ¤¬»ÈÍÑ¤µ¤ì¤ë)¡£
 173 .TP
 174 .B EPERM
 175 .\"O For
 176 .\"O .BR sethostname (),
 177 .\"O the caller did not have the
 178 .\"O .B CAP_SYS_ADMIN
 179 .\"O capability.
 180 .BR sethostname ()
 181 ¤Ë¤ª¤¤¤Æ¡¢¸Æ¤Ó½Ð¤·¤¿¿Í¤¬
 182 .B CAP_SYS_ADMIN
 183 ¥±¡¼¥Ñ¥Ó¥ê¥Æ¥£ (capability) ¤ò»ý¤Ã¤Æ¤¤¤Ê¤«¤Ã¤¿¡£
 184 .\"O .SH "CONFORMING TO"
 185 .SH ½àµò
 186 .\"O SVr4, 4.4BSD  (these interfaces first appeared in 4.2BSD).
 187 .\"O POSIX.1-2001 specifies
 188 .\"O .BR gethostname ()
 189 .\"O but not
 190 .\"O .BR sethostname ().
 191 SVr4, 4.4BSD  (¤³¤ì¤é¤Î¥¤¥ó¥¿¥Õ¥§¡¼¥¹¤Ï 4.2BSD ¤Ç½é¤á¤ÆÅÐ¾ì¤·¤¿)¡£
 192 POSIX.1-2001 ¤Ç¤Ï
 193 .BR gethostname ()
 194 ¤Ë¤Ä¤¤¤Æ¤Ïµ¬Äê¤·¤Æ¤¤¤ë¤¬¡¢
 195 .BR sethostname ()
 196 ¤Ïµ¬Äê¤·¤Æ¤¤¤Ê¤¤¡£
 197 .\"O .SH NOTES
 198 .SH Ãí°Õ
 199 .\"O SUSv2 guarantees that "Host names are limited to 255 bytes".
 200 .\"O POSIX.1-2001 guarantees that "Host names (not including
 201 .\"O the terminating null byte) are limited to
 202 .\"O .B HOST_NAME_MAX
 203 .\"O bytes".
 204 SUSv2 ¤Ç¤Ï¡Ö¥Û¥¹¥ÈÌ¾¤¬ 255 ¥Ð¥¤¥È¤ËÀ©¸Â¤µ¤ì¤ë¡×¤³¤È¤òÊÝ¾Ú¤·¤Æ¤¤¤ë¡£
 205 POSIX.1-2001 ¤Ç¤Ï¡Ö¥Û¥¹¥ÈÌ¾ (½ªÃ¼¤Î NULL ¥Ð¥¤¥È¤Ï´Þ¤Þ¤Ê¤¤) ¤¬
 206 .B HOST_NAME_MAX
 207 ¥Ð¥¤¥È¤ËÀ©¸Â¤µ¤ì¤ë¡×¤³¤È¤òÊÝ¾Ú¤·¤Æ¤¤¤ë¡£
 208 .\"O On Linux,
 209 .\"O .B HOST_NAME_MAX
 210 .\"O is defined with the value 64, which has been the limit since Linux 1.0
 211 .\"O (earlier kernels imposed a limit of 8 bytes).
 212 Linux ¤Ç¤Ï¡¢
 213 .B HOST_NAME_MAX
 214 ¤Ï 64 ¤ËÄêµÁ¤µ¤ì¤Æ¤ª¤ê¡¢
 215 Linux 1.0 °Ê¹ß¤Ç¤Ï¤³¤ì¤¬¾å¸Â¤È¤Ê¤Ã¤Æ¤¤¿
 216 (¤â¤Ã¤È¸Å¤¤¥«¡¼¥Í¥ë¤Ç¤Ï 8 ¥Ð¥¤¥È¤Î¾å¸Â¤¬Å¬ÍÑ¤µ¤ì¤Æ¤¤¤¿)¡£
 217 .\"O .SS Glibc Notes
 218 .SS "glibc ¤Ç¤ÎÃí°Õ"
 219 .\"O The GNU C library does not employ the
 220 .\"O .BR gethostname ()
 221 .\"O system call; instead, it implements
 222 .\"O .BR gethostname ()
 223 .\"O as a library function that calls
 224 .\"O .BR uname (2)
 225 .\"O and copies up to
 226 .\"O .I len
 227 .\"O bytes from the returned
 228 .\"O .I nodename
 229 .\"O field into
 230 .\"O .IR name .
 231 GNU C ¥é¥¤¥Ö¥é¥ê¤Ï¡¢
 232 .BR gethostname ()
 233 ¥·¥¹¥Æ¥à¥³¡¼¥ë¤òÍøÍÑ¤·¤Æ¤¤¤Ê¤¤¡£¤½¤ÎÂå¤ï¤ê¡¢
 234 .BR gethostname ()
 235 ¤ò¥é¥¤¥Ö¥é¥ê´Ø¿ô¤È¤·¤Æ¼ÂÁõ¤·¤Æ¤ª¤ê¡¢
 236 ¤³¤Î´Ø¿ô¤Ï
 237 .BR uname (2)
 238 ¤ò¸Æ¤Ó½Ð¤·¡¢
 239 .BR uname (2)
 240 ¤¬ÊÖ¤·¤¿
 241 .I nodename
 242 ¥Õ¥£¡¼¥ë¥É (¤ÎºÇÂç
 243 .I len
 244 ¥Ð¥¤¥È) ¤ò
 245 .I name
 246 ¤Ë¥³¥Ô¡¼¤¹¤ë¡£
 247 .\"O Having performed the copy, the function then checks if the length of the
 248 .\"O .I nodename
 249 .\"O was greater than or equal to
 250 .\"O .IR len ,
 251 .\"O and if it is, then the function returns \-1 with
 252 .\"O .I errno
 253 .\"O set to
 254 .\"O .BR ENAMETOOLONG ;
 255 .\"O in this case, no null-terminator is included in the returned
 256 .\"O .IR name .
 257 ¥³¥Ô¡¼¤ò¹Ô¤Ã¤¿ºÝ¤Ë¡¢¤³¤Î´Ø¿ô¤Ï
 258 .I nodename
 259 ¤ÎÄ¹¤µ¤¬
 260 .I len
 261 °Ê¾å¤«¤Î³ÎÇ§¤ò¹Ô¤¤¡¢
 262 .I len
 263 °Ê¾å¤Î¾ì¹ç¤Ë¤Ï \-1 ¤òÊÖ¤·¡¢
 264 .I errno
 265 ¤Ë
 266 .B ENAMETOOLONG
 267 ¤òÀßÄê¤¹¤ë¡£
 268 ¤³¤Î¾ì¹ç¡¢ÊÖ¤µ¤ì¤¿
 269 .I name
 270 ¤Ë¤Ï½ªÃ¼¤Î NULL ¥Ð¥¤¥È¤Ï´Þ¤Þ¤ì¤Ê¤¤¡£
 271
 272 .\"O Versions of glibc before 2.2
 273 .\"O .\" At least glibc 2.0 and 2.1, older versions not checked
 274 .\"O handle the case where the length of the
 275 .\"O .I nodename
 276 .\"O was greater than or equal to
 277 .\"O .I len
 278 .\"O differently: nothing is copied into
 279 .\"O .I name
 280 .\"O and the function returns \-1 with
 281 .\"O .I errno
 282 .\"O set to
 283 .\"O .BR ENAMETOOLONG .
 284 ¥Ð¡¼¥¸¥ç¥ó 2.2 ¤è¤êÁ°¤Î glibc
 285 .\" ¾¯¤Ê¤¯¤È¤â glibc 2.0 ¤È 2.1¡£¤½¤ì¤è¤ê¸Å¤¤¥Ð¡¼¥¸¥ç¥ó¤ÏÌ¤³ÎÇ§
 286 ¤Ç¤Ï¡¢
 287 .I nodename
 288 ¤ÎÄ¹¤µ¤¬
 289 .I len
 290 °Ê¾å¤Î¾ì¹ç¤Î°·¤¤¤¬°Û¤Ê¤ë;
 291 .I len
 292 °Ê¾å¤Î¾ì¹ç¤Ë¤Ï¡¢
 293 .I name
 294 ¤Ë¤Ï²¿¤â¥³¥Ô¡¼¤»¤º¡¢´Ø¿ô¤Ï \-1 ¤òÊÖ¤·¡¢
 295 .I errno
 296 ¤Ë
 297 .B ENAMETOOLONG
 298 ¤òÀßÄê¤¹¤ë¡£
 299 .\"O .SH "SEE ALSO"
 300 .SH ´ØÏ¢¹àÌÜ
 301 .BR getdomainname (2),
 302 .BR setdomainname (2),
 303 .BR uname (2)