git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	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	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)strerror.3 8.1 (Berkeley) 6/9/93
	33	.\" $FreeBSD: src/lib/libc/string/strerror.3,v 1.24 2007/01/09 00:28:12 imp Exp $
	34	.\"
	35	.Dd October 12, 2004
	36	.Dt STRERROR 3
	37	.Os
	38	.Sh NAME
	39	.Nm perror ,
	40	.Nm strerror ,
	41	.Nm strerror_r ,
	42	.Nm sys_errlist ,
	43	.Nm sys_nerr
	44	.Nd system error messages
	45	.Sh LIBRARY
	46	.Lb libc
	47	.Sh SYNOPSIS
	48	.In stdio.h
	49	.Ft void
	50	.Fo perror
	51	.Fa "const char *s"
	52	.Fc
	53	.Vt extern const char * const sys_errlist[] ;
	54	.Vt extern const int sys_nerr ;
	55	.In string.h
	56	.Ft "char *"
	57	.Fo strerror
	58	.Fa "int errnum"
	59	.Fc
	60	.Ft int
	61	.Fo strerror_r
	62	.Fa "int errnum"
	63	.Fa "char *strerrbuf"
	64	.Fa "size_t buflen"
	65	.Fc
	66	.Sh DESCRIPTION
	67	The
	68	.Fn strerror ,
	69	.Fn strerror_r ,
	70	and
	71	.Fn perror
	72	functions look up the error message string corresponding to an
	73	error number.
	74	.Pp
	75	The
	76	.Fn strerror
	77	function accepts an error number argument
	78	.Fa errnum
	79	and returns a pointer to the corresponding
	80	message string.
	81	.Pp
	82	The
	83	.Fn strerror_r
	84	function renders the same result into
	85	.Fa strerrbuf
	86	for a maximum of
	87	.Fa buflen
	88	characters and returns 0 upon success.
	89	.Pp
	90	The
	91	.Fn perror
	92	function finds the error message corresponding to the current
	93	value of the global variable
	94	.Va errno
	95	.Pq Xr intro 2
	96	and writes it, followed by a newline, to the
	97	standard error file descriptor.
	98	If the argument
	99	.Fa s
	100	is
	101	.Pf non- Dv NULL
	102	and does not point to the null character,
	103	this string is prepended to the message
	104	string and separated from it by
	105	a colon and space
	106	.Pq Dq Li ":\ " ;
	107	otherwise, only the error message string is printed.
	108	.Pp
	109	If the error number is not recognized, these functions return an error message
	110	string containing
	111	.Dq Li "Unknown error:\ "
	112	followed by the error number in decimal.
	113	The
	114	.Fn strerror
	115	and
	116	.Fn strerror_r
	117	functions return
	118	.Er EINVAL
	119	as a warning.
	120	Error numbers recognized by this implementation fall in
	121	the range 0 <=
	122	.Fa errnum
	123	<
	124	.Fa sys_nerr .
	125	.Pp
	126	If insufficient storage is provided in
	127	.Fa strerrbuf
	128	(as specified in
	129	.Fa buflen )
	130	to contain the error string,
	131	.Fn strerror_r
	132	returns
	133	.Er ERANGE
	134	and
	135	.Fa strerrbuf
	136	will contain an error message that has been truncated and
	137	.Dv NUL
	138	terminated to fit the length specified by
	139	.Fa buflen .
	140	.Pp
	141	The message strings can be accessed directly using the external
	142	array
	143	.Va sys_errlist .
	144	The external value
	145	.Va sys_nerr
	146	contains a count of the messages in
	147	.Va sys_errlist .
	148	The use of these variables is deprecated;
	149	.Fn strerror
	150	or
	151	.Fn strerror_r
	152	should be used instead.
	153	.Sh SEE ALSO
	154	.Xr intro 2 ,
	155	.Xr psignal 3
	156	.Sh STANDARDS
	157	The
	158	.Fn perror
	159	and
	160	.Fn strerror
	161	functions conform to
	162	.St -isoC-99 .
	163	The
	164	.Fn strerror_r
	165	function conforms to
	166	.St -p1003.1-2001 .
	167	.Sh HISTORY
	168	The
	169	.Fn strerror
	170	and
	171	.Fn perror
	172	functions first appeared in
	173	.Bx 4.4 .
	174	The
	175	.Fn strerror_r
	176	function was implemented in
	177	.Fx 4.4
	178	by
	179	.An Wes Peters Aq wes@FreeBSD.org .
	180	.Sh BUGS
	181	For unknown error numbers, the
	182	.Fn strerror
	183	function will return its result in a static buffer which
	184	may be overwritten by subsequent calls.
	185	.Pp
	186	The return type for
	187	.Fn strerror
	188	is missing a type-qualifier; it should actually be
	189	.Vt const char * .
	190	.Pp
	191	Programs that use the deprecated
	192	.Va sys_errlist
	193	variable often fail to compile because they declare it
	194	inconsistently.