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

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 2009 David Schultz <das@FreeBSD.org>
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/lib/libc/stdio/getline.3,v 1.2 2009/04/06 13:50:04 das Exp $
	26	.\"
	27	.Dd March 29, 2009
	28	.Dt GETLINE 3
	29	.Os
	30	.Sh NAME
	31	.Nm getdelim ,
	32	.Nm getline
	33	.Nd get a line from a stream
	34	.Sh LIBRARY
	35	.Lb libc
	36	.Sh SYNOPSIS
	37	.Fd "#define _WITH_GETLINE"
	38	.In stdio.h
	39	.Ft ssize_t
	40	.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
	41	.Ft ssize_t
	42	.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
	43	.Sh DESCRIPTION
	44	The
	45	.Fn getdelim
	46	function reads a line from
	47	.Fa stream ,
	48	delimited by the character
	49	.Fa delimiter .
	50	The
	51	.Fn getline
	52	function is equivalent to
	53	.Fn getdelim
	54	with the newline character as the delimiter.
	55	The delimiter character is included as part of the line, unless
	56	the end of the file is reached.
	57	The caller may provide a pointer to a malloc buffer for the line in
	58	.Fa *linep ,
	59	and the capacity of that buffer in
	60	.Fa *linecapp ;
	61	if
	62	.Fa *linecapp
	63	is 0, then
	64	.Fa *linep
	65	is treated as
	66	.Dv NULL .
	67	These functions may expand the buffer as needed, as if via
	68	.Fn realloc ,
	69	and update
	70	.Fa *linep
	71	and
	72	.Fa *linecapp
	73	accordingly.
	74	.Sh RETURN VALUES
	75	The
	76	.Fn getdelim
	77	and
	78	.Fn getline
	79	functions return the number of characters written, excluding the
	80	terminating
	81	.Dv NULL .
	82	The value \-1 is returned if an error occurs, or if end-of-file is reached.
	83	.Sh EXAMPLES
	84	The following code fragment reads lines from a file and
	85	writes them to standard output.
	86	The
	87	.Fn fwrite
	88	function is used in case the line contains embedded
	89	.Dv NUL
	90	characters.
	91	.Bd -literal -offset indent
	92	char *line = NULL;
	93	size_t linecap = 0;
	94	ssize_t linelen;
	95	while ((linelen = getline(&line, &linecap, fp)) > 0)
	96	fwrite(line, linelen, 1, stdout);
	97	.Ed
	98	.Sh COMPATIBILITY
	99	Many application writers used the name
	100	.Va getline
	101	before the
	102	.Fn getline
	103	function was introduced in
	104	.St -p1003.1 ,
	105	so a prototype is not provided by default in order to avoid
	106	compatibility problems.
	107	Applications that wish to use the
	108	.Fn getline
	109	function described herein should either request a strict
	110	.St -p1003.1-2008
	111	environment by defining the macro
	112	.Dv _POSIX_C_SOURCE
	113	to the value 200809 or greater, or by defining the macro
	114	.Dv _WITH_GETLINE ,
	115	prior to the inclusion of
	116	.In stdio.h .
	117	For compatibility with GNU libc, defining either
	118	.Dv _BSD_SOURCE
	119	or
	120	.Dv _GNU_SOURCE
	121	prior to the inclusion of
	122	.In stdio.h
	123	will also make
	124	.Fn getline
	125	available.
	126	.Sh ERRORS
	127	These functions may fail if:
	128	.Bl -tag -width Er
	129	.It Bq Er EINVAL
	130	Either
	131	.Fa linep
	132	or
	133	.Fa linecapp
	134	is
	135	.Dv NULL .
	136	.It Bq Er EOVERFLOW
	137	No delimiter was found in the first
	138	.Dv SSIZE_MAX
	139	characters.
	140	.El
	141	.Pp
	142	These functions may also fail for any of the errors specified for
	143	.Fn fgets
	144	and
	145	.Fn malloc .
	146	.Sh SEE ALSO
	147	.Xr fgetln 3 ,
	148	.Xr fgets 3 ,
	149	.Xr malloc 3
	150	.Sh STANDARDS
	151	The
	152	.Fn getdelim
	153	and
	154	.Fn getline
	155	functions conform to
	156	.St -p1003.1-2008 .
	157	.Sh HISTORY
	158	These routines first appeared in
	159	.Fx 8.0 .
	160	.Sh BUGS
	161	There are no wide character versions of
	162	.Fn getdelim
	163	or
	164	.Fn getline .