gitweb.dragonflybsd.org Git - dragonfly.git/blame

Commit	Line	Data
ba2075d1 VS	1	.\" $NetBSD: efun.3,v 1.10 2010/05/03 05:40:37 jruoho Exp $
	2	.\"
	3	.\" Copyright (c) 2006 The NetBSD Foundation, Inc.
	4	.\" All rights reserved.
	5	.\"
	6	.\" This code is derived from software contributed to The NetBSD Foundation
	7	.\" by Christos Zoulas.
	8	.\"
	9	.\" Redistribution and use in source and binary forms, with or without
	10	.\" modification, are permitted provided that the following conditions
	11	.\" are met:
	12	.\" 1. Redistributions of source code must retain the above copyright
	13	.\" notice, this list of conditions and the following disclaimer.
	14	.\" 2. Redistributions in binary form must reproduce the above copyright
	15	.\" notice, this list of conditions and the following disclaimer in the
	16	.\" documentation and/or other materials provided with the distribution.
	17	.\"
	18	.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
	19	.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
	20	.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	21	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
	22	.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	23	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	24	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	25	.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	26	.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	27	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	28	.\" POSSIBILITY OF SUCH DAMAGE.
	29	.\"
	30	.Dd April 26, 2011
	31	.Dt EFUN 3
	32	.Os
	33	.Sh NAME
	34	.Nm esetfunc ,
	35	.Nm emalloc ,
	36	.Nm ecalloc ,
	37	.Nm erealloc ,
	38	.Nm estrdup ,
	39	.Nm estrndup ,
	40	.Nm estrlcat ,
	41	.Nm estrlcpy ,
feddbc59	42	.Nm easprintf
ba2075d1 VS	43	.Nd error-checked utility functions
	44	.Sh LIBRARY
	45	.Lb libutil
	46	.Sh SYNOPSIS
27ebe7f5	47	.In sys/types.h
ba2075d1 VS	48	.In libutil.h
	49	.Ft void ()(int, const char , ...)
	50	.Fn esetfunc "void ()(int, const char , ...)"
	51	.Ft void *
	52	.Fn ecalloc "size_t n" "size_t c"
	53	.Ft void *
	54	.Fn emalloc "size_t n"
	55	.Ft void *
	56	.Fn erealloc "void *p" "size_t n"
	57	.Ft char *
	58	.Fn estrdup "const char *s"
	59	.Ft char *
	60	.Fn estrndup "const char *s" "size_t len"
	61	.Ft size_t
	62	.Fn estrlcat "char dst" "const char src" "size_t len"
	63	.Ft size_t
	64	.Fn estrlcpy "char dst" "const char src" "size_t len"
	65	.Ft int
feddbc59	66	.Fn easprintf "char ** restrict str" "const char * restrict fmt" "..."
ba2075d1 VS	67	.Sh DESCRIPTION
	68	The
	69	.Fn ecalloc ,
	70	.Fn emalloc ,
	71	.Fn erealloc ,
	72	.Fn estrdup ,
	73	.Fn estrndup ,
	74	.Fn estrlcat ,
	75	.Fn estrlcpy ,
	76	and
feddbc59	77	.Fn easprintf
ba2075d1 VS	78	functions
	79	operate exactly as the corresponding functions that do not start with an
	80	.Sq e
	81	except that in case of an error, they call
	82	the installed error handler that can be configured with
	83	.Fn esetfunc .
	84	.Pp
	85	For the string handling functions, it is an error when the destination
	86	buffer is not large enough to hold the complete string.
	87	For functions that allocate memory or open a file, it is an error when
	88	they would return a null pointer.
	89	The default error handler is
	90	.Xr err 3 .
	91	The function
	92	.Fn esetfunc
	93	returns the previous error handler function.
	94	A
	95	.Dv NULL
	96	error handler will just call
	97	.Xr exit 3 .
ba2075d1 VS	98	.Sh SEE ALSO
	99	.Xr asprintf 3 ,
	100	.Xr calloc 3 ,
	101	.Xr err 3 ,
	102	.Xr exit 3 ,
	103	.Xr fopen 3 ,
	104	.Xr malloc 3 ,
	105	.Xr realloc 3 ,
	106	.Xr strdup 3 ,
	107	.Xr strlcat 3 ,
	108	.Xr strlcpy 3 ,
feddbc59 SW	109	.Xr strndup 3
feddbc59 SW	110	.\".Xr vasprintf 3
98eee0ee SW	111	.Sh HISTORY
	112	The error functions first appeared in
	113	.Dx 2.11 .
	114	They are originally from
	115	.Nx .