[apple/libc.git] / string / strerror.3

.\" 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.12 2001/10/01 16:09:00 ru Exp $
.\"
.Dd June 9, 1993
.Dt STRERROR 3
.Os
.Sh NAME
.Nm perror ,
.Nm strerror ,
.Nm sys_errlist ,
.Nm sys_nerr
.Nd system error messages
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.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"
.Sh DESCRIPTION
The
.Fn strerror
and
.Fn perror
functions look up the error message string corresponding to an
error number.
.Pp
The
.Fn strerror
function accepts an error number argument
.Fa errnum
and
returns a pointer to the corresponding
message string.
.Pp
The
.Fn perror
function finds the error message corresponding to the current
value of the global variable
.Va errno
.Pq Xr intro 2
and writes it, followed by a newline, to the
standard error file descriptor.
If the argument
.Fa string
is
.Pf non- Dv NULL
and does not point to the null character,
this string is prepended to the message
string and separated from it by
a colon and space
.Pq Ql \&:\ \& ;
otherwise, only the error message string is printed.
.Pp
If
.Fa errnum
is not a recognized error number,
the error message string will contain
.Dq Li "Unknown error:\ "
followed by the error number in decimal.
.Pp
The message strings can be accessed directly using the external
array
.Va sys_errlist .
The external value
.Va sys_nerr
contains a count of the messages in
.Va sys_errlist .
The use of these variables is deprecated;
.Fn strerror
should be used instead.
.Sh SEE ALSO
.Xr intro 2 ,
.Xr psignal 3
.Sh HISTORY
The
.Fn strerror
and
.Fn perror
functions first appeared in
.Bx 4.4 .
.Sh BUGS
For unknown error numbers, the
.Fn strerror
function will return its result in a static buffer which
may be overwritten by subsequent calls.
.Pp
Programs that use the deprecated
.Va sys_errlist
variable often fail to compile because they declare it
inconsistently.
Commit	Line	Data
5b2abdfb A	1	.\" Copyright (c) 1980, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" the American National Standards Committee X3, on Information
	6	.\" Processing Systems.
	7	.\"
	8	.\" Redistribution and use in source and binary forms, with or without
	9	.\" modification, are permitted provided that the following conditions
	10	.\" are met:
	11	.\" 1. Redistributions of source code must retain the above copyright
	12	.\" notice, this list of conditions and the following disclaimer.
	13	.\" 2. Redistributions in binary form must reproduce the above copyright
	14	.\" notice, this list of conditions and the following disclaimer in the
	15	.\" documentation and/or other materials provided with the distribution.
	16	.\" 3. All advertising materials mentioning features or use of this software
	17	.\" must display the following acknowledgement:
	18	.\" This product includes software developed by the University of
	19	.\" California, Berkeley and its contributors.
	20	.\" 4. Neither the name of the University nor the names of its contributors
	21	.\" may be used to endorse or promote products derived from this software
	22	.\" without specific prior written permission.
	23	.\"
	24	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	25	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	26	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	27	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	28	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	29	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	30	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	31	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	32	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	33	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	34	.\" SUCH DAMAGE.
	35	.\"
	36	.\" @(#)strerror.3 8.1 (Berkeley) 6/9/93
	37	.\" $FreeBSD: src/lib/libc/string/strerror.3,v 1.12 2001/10/01 16:09:00 ru Exp $
	38	.\"
	39	.Dd June 9, 1993
	40	.Dt STRERROR 3
	41	.Os
	42	.Sh NAME
	43	.Nm perror ,
	44	.Nm strerror ,
	45	.Nm sys_errlist ,
	46	.Nm sys_nerr
	47	.Nd system error messages
	48	.Sh LIBRARY
	49	.Lb libc
	50	.Sh SYNOPSIS
	51	.In stdio.h
	52	.Ft void
	53	.Fn perror "const char *string"
	54	.Vt extern const char * const sys_errlist[] ;
	55	.Vt extern const int sys_nerr ;
	56	.In string.h
	57	.Ft char *
	58	.Fn strerror "int errnum"
	59	.Sh DESCRIPTION
	60	The
	61	.Fn strerror
	62	and
	63	.Fn perror
	64	functions look up the error message string corresponding to an
65	error number.
66	.Pp
67	The
68	.Fn strerror
69	function accepts an error number argument
70	.Fa errnum
71	and
72	returns a pointer to the corresponding
73	message string.
74	.Pp
75	The
76	.Fn perror
77	function finds the error message corresponding to the current
78	value of the global variable
79	.Va errno
80	.Pq Xr intro 2
81	and writes it, followed by a newline, to the
82	standard error file descriptor.
83	If the argument
84	.Fa string
85	is
86	.Pf non- Dv NULL
87	and does not point to the null character,
88	this string is prepended to the message
89	string and separated from it by
90	a colon and space
91	.Pq Ql \&:\ \& ;
92	otherwise, only the error message string is printed.
93	.Pp
94	If
95	.Fa errnum
96	is not a recognized error number,
97	the error message string will contain
98	.Dq Li "Unknown error:\ "
99	followed by the error number in decimal.
100	.Pp
101	The message strings can be accessed directly using the external
102	array
103	.Va sys_errlist .
104	The external value
105	.Va sys_nerr
106	contains a count of the messages in
107	.Va sys_errlist .
108	The use of these variables is deprecated;
109	.Fn strerror
110	should be used instead.
111	.Sh SEE ALSO
112	.Xr intro 2 ,
113	.Xr psignal 3
114	.Sh HISTORY
115	The
116	.Fn strerror
117	and
118	.Fn perror
119	functions first appeared in
120	.Bx 4.4 .
121	.Sh BUGS
122	For unknown error numbers, the
123	.Fn strerror
124	function will return its result in a static buffer which
125	may be overwritten by subsequent calls.
126	.Pp
127	Programs that use the deprecated
128	.Va sys_errlist
129	variable often fail to compile because they declare it
130	inconsistently.