draft/man3/strerror.3

   1 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright (C) 2005, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .\" References consulted:
  25 .\"     Linux libc source code
  26 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  27 .\"     386BSD man pages
  28 .\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith <faith@cs.unc.edu>
  29 .\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer <aeb@cwi.nl>
  30 .\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer <aeb@cwi.nl>
  31 .\" Modified Mon Oct 15 21:16:25 2001 by John Levon <moz@compsoc.man.ac.uk>
  32 .\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer <aeb@cwi.nl>
  33 .\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer <aeb@cwi.nl>
  34 .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description
  35 .\"         Addition of extra material on portability and standards.
  36 .\"
  37 .\" Japanese Version Copyright (c) 1997 YOSHINO Takashi
  38 .\"       all rights reserved.
  39 .\" Translated 1997-01-20, YOSHINO Takashi <yoshino@civil.jcn.nihon-u.ac.jp>
  40 .\" Updated & Modified 2001-11-03, Yuichi SATO <ysato@h4.dion.ne.jp>
  41 .\" Updated 2005-12-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  42 .\" Updated 2007-09-06, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.64
  43 .\"
  44 .\"WORD         GNU-specific            GNU 仕様の
  45 .\"WORD         XSI-compliant           XSI 準拠の
  46 .\"
  47 .TH STRERROR 3  2009-03-30 "" "Linux Programmer's Manual"
  48 .\"O .SH NAME
  49 .SH 名前
  50 .\"O strerror, strerror_r \- return string describing error number
  51 strerror, strerror_r \- エラー番号を説明する文字列を返す。
  52 .\"O .SH SYNOPSIS
  53 .SH 書式
  54 .nf
  55 .B #include <string.h>
  56 .sp
  57 .BI "char *strerror(int " errnum );
  58 .sp
  59 .BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen );
  60 .fi
  61 .sp
  62 .in -4n
  63 .\"O Feature Test Macro Requirements for glibc (see
  64 .\"O .BR feature_test_macros (7)):
  65 glibc 向けの機能検査マクロの要件
  66 .RB ( feature_test_macros (7)
  67 参照):
  68 .in
  69 .sp
  70 .\"O The XSI-compliant version of
  71 .\"O .BR strerror_r ()
  72 .\"O is provided if:
  73 次の場合には
  74 XSI 準拠のバージョンの
  75 .BR strerror_r ()
  76 が提供される:
  77 .br
  78 (_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600) && !\ _GNU_SOURCE
  79 .fi
  80 .\"O .SH DESCRIPTION
  81 .\"O The
  82 .\"O .BR strerror ()
  83 .\"O function returns a pointer to a string that describes the error
  84 .\"O code passed in the argument \fIerrnum\fP, possibly using the
  85 .\"O .B LC_MESSAGES
  86 .\"O part of the current locale to select the appropriate language.
  87 .\"O This string must not be modified by the application, but may be
  88 .\"O modified by a subsequent call to \fBperror\fP(3) or
  89 .\"O .BR strerror ().
  90 .\"O No library function will modify this string.
  91 .SH 説明
  92 .BR strerror ()
  93 関数は、引き数 \fIerrnum\fP で渡されたエラーコードについての
  94 説明が入った文字列へのポインタを返す。
  95 可能であるならば、適切な言語を選択するために、
  96 現在のロケールの
  97 .B LC_MESSAGES
  98 を使う。
  99 この文字列は、アプリケーションで変更してはならないが、
 100 その後に起こる
 101 .BR perror (3)
 102 や
 103 .BR strerror ()
 104 の呼び出しで
 105 変更されても構わない。
 106 この文字列を変更するライブラリ関数はない。
 107
 108 .\"O The
 109 .\"O .BR strerror_r ()
 110 .\"O function is similar to
 111 .\"O .BR strerror (),
 112 .\"O but is
 113 .\"O thread safe.
 114 .\"O This function is available in two versions:
 115 .\"O an XSI-compliant version specified in POSIX.1-2001
 116 .\"O (available since glibc 2.3.4),
 117 .\"O and a GNU-specific version (available since glibc 2.0).
 118 .\"O The XSI-compliant version is provided with the feature test macros
 119 .\"O settings shown in the SYNOPSIS;
 120 .\"O otherwise the GNU-specific version is provided.
 121 .BR strerror_r ()
 122 関数は
 123 .BR strerror ()
 124 と似ているが、
 125 スレッドセーフである。
 126 この関数には二種類のバージョンが存在し、
 127 POSIX.1-2001 で規定された XSI 準拠のバージョン
 128 (glibc 2.3.4 以降で利用可能) と、
 129 GNU 仕様のバージョン (glibc 2.0 以降で利用可能) である。
 130 「書式」の節に記載された機能検査マクロの場合には、
 131 XSI 準拠のバージョンが提供される。
 132 それ以外の場合には GNU 仕様のバージョンが提供される。
 133 .\"O If no feature test macros are explicitly defined,
 134 .\"O then (since glibc 2.4)
 135 .\"O .B _POSIX_SOURCE
 136 .\"O is defined by default with the value
 137 .\"O 200112L, so that the XSI-compliant version of
 138 .\"O .BR strerror_r ()
 139 .\"O is provided by default.
 140 機能検査マクロが一つも明示的に定義されない場合、
 141 (glibc 2.4 以降では) デフォルトで
 142 .B _POSIX_SOURCE
 143 は値 200112l で定義され、その結果
 144 XSI 準拠のバージョンの
 145 .BR strerror_r ()
 146 がデフォルトで提供される。
 147
 148 .\"O The XSI-compliant
 149 .\"O .BR strerror_r ()
 150 .\"O is preferred for portable applications.
 151 .\"O It returns the error string in the user-supplied buffer
 152 .\"O .I buf
 153 .\"O of length
 154 .\"O .IR buflen .
 155 移植性が必要なアプリケーションでは、
 156 XSI 準拠の
 157 .BR strerror_r ()
 158 を使う方がよい。
 159 この関数は、ユーザーから提供される長さ
 160 .I buflen
 161 のバッファ
 162 .I buf
 163 にエラー文字列を返す。
 164
 165 .\"O The GNU-specific
 166 .\"O .BR strerror_r ()
 167 .\"O returns a pointer to a string containing the error message.
 168 .\"O This may be either a pointer to a string that the function stores in
 169 .\"O .IR buf ,
 170 .\"O or a pointer to some (immutable) static string
 171 .\"O (in which case
 172 .\"O .I buf
 173 .\"O is unused).
 174 .\"O If the function stores a string in
 175 .\"O .IR buf ,
 176 .\"O then at most
 177 .\"O .I buflen
 178 .\"O bytes are stored (the string may be truncated if
 179 .\"O .I buflen
 180 .\"O is too small) and the string always includes a terminating null byte.
 181 GNU 仕様の
 182 .BR strerror_r ()
 183 は、エラーメッセージを格納した文字列へのポインタを返す。
 184 返り値は、この関数が
 185 .I buf
 186 に格納した文字列へのポインタか、
 187 何らかの (不変な) 静的な文字列へのポインタ、のいずれかとなる
 188 (後者の場合は
 189 .I buf
 190 は使用されない)。
 191 .I buf
 192 に文字列が格納される場合は、
 193 最大で
 194 .I buflen
 195 バイトが格納され
 196 .RI ( buflen
 197 が小さ過ぎたときには文字列は切り詰められる)、
 198 文字列には必ず終端ヌル文字が含まれる。
 199 .\"O .SH "RETURN VALUE"
 200 .SH 返り値
 201 .\"O The
 202 .\"O .BR strerror ()
 203 .\"O and
 204 .\"O .BR strerror_r ()
 205 .\"O functions return
 206 .\"O the appropriate error description string,
 207 .\"O or an "Unknown error nnn" message if the error number is unknown.
 208 .BR strerror ()
 209 と
 210 .BR strerror_r ()
 211 はエラー内容を説明する
 212 文字列を返す。エラー番号が未知の場合は "Unknown error nnn" という
 213 メッセージを返す。
 214
 215 .\"O The XSI-compliant
 216 .\"O .BR strerror_r ()
 217 .\"O function returns 0 on success;
 218 .\"O on error, \-1 is returned and
 219 .\"O .I errno
 220 .\"O is set to indicate the error.
 221 XSI 準拠の
 222 .BR strerror_r ()
 223 関数は成功すると 0 を返す。
 224 エラーの場合には、 \-1 を返し、
 225 .I errno
 226 にエラー内容を示す値をセットする。
 227 .\"O .SH ERRORS
 228 .SH エラー
 229 .TP
 230 .B EINVAL
 231 .\"O The value of
 232 .\"O .I errnum
 233 .\"O is not a valid error number.
 234 .I errnum
 235 の値が有効なエラー番号ではない。
 236 .TP
 237 .B ERANGE
 238 .\"O Insufficient storage was supplied to contain the error description string.
 239 エラーコードを説明する文字列のために、充分な領域が確保できなかった。
 240 .\"O .SH "CONFORMING TO"
 241 .SH 準拠
 242 .\"O .BR strerror ()
 243 .\"O is specified by POSIX.1-2001, C89, C99.
 244 .\"O .BR strerror_r ()
 245 .\"O is specified by POSIX.1-2001.
 246 .BR strerror ()
 247 は POSIX.1-2001, C89, C99 で規定されている。
 248 .BR strerror_r ()
 249 は POSIX.1-2001 で規定されている。
 250
 251 .\"O The GNU-specific
 252 .\"O .BR strerror_r ()
 253 .\"O function is a nonstandard extension.
 254 GNU 仕様の
 255 .BR strerror_r ()
 256 関数は非標準の拡張である。
 257
 258 .\"O POSIX.1-2001 permits
 259 .\"O .BR strerror ()
 260 .\"O to set
 261 .\"O .I errno
 262 .\"O if the call encounters an error, but does not specify what
 263 .\"O value should be returned as the function result in the event of an error.
 264 .\"O On some systems,
 265 .\"O .\" e.g., Solaris 8, HP-UX 11
 266 .\"O .BR strerror ()
 267 .\"O returns NULL if the error number is unknown.
 268 .\"O On other systems,
 269 .\"O .\" e.g., FreeBSD 5.4, Tru64 5.1B
 270 .\"O .BR strerror ()
 271 .\"O returns a string something like "Error nnn occurred" and sets
 272 .\"O .I errno
 273 .\"O to
 274 .\"O .B EINVAL
 275 .\"O if the error number is unknown.
 276 POSIX.1-2001 は、
 277 .BR strerror ()
 278 がエラーに遭遇した場合に
 279 .I errno
 280 をセットすることを認めているが、エラー発生時に関数の結果として
 281 どんな値を返すべきかを規定してない。
 282 あるシステムでは、
 283 .\" 例えば Solaris 8, HP-UX 11
 284 エラー番号が未知の場合、
 285 .BR strerror ()
 286 は NULL を返す。
 287 他のシステムでは、
 288 .\" 例えば FreeBSD 5.4, Tru64 5.1B
 289 エラー番号が未知の場合、
 290 .BR strerror ()
 291 は "Error nnn occurred" といった文字列を返し、
 292 .I errno
 293 に
 294 .B EINVAL
 295 をセットする。
 296 .\"O .SH "SEE ALSO"
 297 .SH 関連項目
 298 .BR err (3),
 299 .BR errno (3),
 300 .BR error (3),
 301 .BR perror (3),
 302 .BR strsignal (3)