.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)strerror.3	8.1 (Berkeley) 6/9/93
.\" %FreeBSD: src/lib/libc/string/strerror.3,v 1.7.2.6 2001/12/20 06:31:26 wes Exp %
.\"
.\" $FreeBSD$
.\"
.Dd Nov 26, 2001
.Dt STRERROR 3
.Os
.Sh 名称
.Nm perror ,
.Nm strerror ,
.Nm strerror_r ,
.Nm sys_errlist ,
.Nm sys_nerr
.Nd システムのエラーメッセージ
.Sh ライブラリ
.Lb libc
.Sh 書式
.In stdio.h
.Ft void
.Fn perror "const char *string"
.Vt extern const char * const sys_errlist[] ;
.Vt extern const int sys_nerr ;
.In string.h
.Ft char *
.Fn strerror "int errnum"
.Ft int
.Fn strerror_r "int errnum" "char * strerrbuf" "size_t buflen"
.Sh 解説
.Fn strerror ,
.Fn strerror_r
および
.Fn perror
関数は、エラー番号に対応するエラーメッセージ文字列を探し出します。
.Pp
.Fn strerror
関数は、エラー番号の引数
.Fa errnum
を受け取って、それに対応するメッセージ文字列へのポインタを返します。
.Pp
.Fn strerror_r
関数は、
同じ結果を
最大
.Fa buflen
文字数の
.Fa strerrbuf
に直し、
成功した場合は 0 を返します。
.Pp
.Fn perror
関数は、大域変数
.Va errno
.Pq Xr intro 2
の現在の値に対応するエラーメッセージを探して、
それに改行をつけて標準エラーファイル記述子に書込みます。引数
.Fa string
が
.Dv ヌル
以外であり、ヌル文字を指さない場合は、
この文字列はメッセージ文字列の前にコロンとスペース
.Pq Ql \&:\ \& ;
で区切って追加されます。
それ以外の場合は、エラーメッセージ文字列のみが印字されます。
.Pp
.Fa errnum
がエラー番号として認識できない場合は、
.Fn strerror
は、
.Dq Li "Unknown error:\ "
のエラーメッセージ文字列の後に、
10 進数のエラー番号を返し、
.Va errno
に
.Er EINVAL
をセットします。
.Fn strerror_r
は、
.Fa strerrbuf
を変更せずに
.Er EINVAL
を返します。
エラー番号が
0 <=
.Fa errnum
<
.Fa sys_nerr
内の実装では、認識できません。
.Pp
エラー文字列を含む
(
.Fa buflen
で指定されているより)
.Fa strerrbuf
が不十分な領域の場合、
.Fn strerror_r
は
.Er ERANGE
を返し、
.Fa strerrbuf
には、
.Fa buflen
で指定された
ヌル文字で終了する長さの
切り捨てたエラーメッセージが入ります。
.Pp
メッセージ文字列には、外部配列
.Va sys_errlist
を使って直接アクセスすることができます。外部値
.Va sys_nerr
には
.Va sys_errlist
の中にあるメッセージのカウントが入っています。
これらの変数を使用することには賛成できません。代わりに、
.Fn strerror
または
.Fn strerror_r
を使った方がよいでしょう。
.Sh 関連項目
.Xr intro 2 ,
.Xr psignal 3
.Sh 歴史
.Fn strerror
および
.Fn perror
関数は、
.Bx 4.4
ではじめて登場しました。
.Fn strerror_r
関数は、
.An Wes Peters
.Aq wes@freebsd.org .
によって
.Fx 4.4
で実装されました。
.Sh バグ
認識できないエラー番号に対しては、
.Fn strerror
関数はその結果を静的バッファに返し、
それは以降の呼び出しによって上書きされる可能性があります。
.Pp
.Va sys_errlist
変数を使用している好ましくないプログラムは、
その変数を一貫性なく宣言するために失敗することがしばしばあります。