Annotation of src/lib/libc/stdio/fgetln.3, Revision 1.14
1.14 ! drochner 1: .\" $NetBSD: fgetln.3,v 1.11 2003/08/07 16:43:23 agc Exp $
1.3 jtc 2: .\"
1.1 cgd 3: .\" Copyright (c) 1990, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.11 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.3 jtc 30: .\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94
1.1 cgd 31: .\"
1.13 wiz 32: .Dd April 21, 2004
1.1 cgd 33: .Dt FGETLN 3
34: .Os
35: .Sh NAME
36: .Nm fgetln
37: .Nd get a line from a stream
1.5 perry 38: .Sh LIBRARY
39: .Lb libc
1.1 cgd 40: .Sh SYNOPSIS
1.10 wiz 41: .In stdio.h
1.1 cgd 42: .Ft char *
1.6 kleink 43: .Fn fgetln "FILE * restrict stream" "size_t * restrict len"
1.1 cgd 44: .Sh DESCRIPTION
45: The
46: .Fn fgetln
47: function
48: returns a pointer to the next line from the stream referenced by
49: .Fa stream .
50: This line is
51: .Em not
52: a C string as it does not end with a terminating
53: .Dv NUL
54: character.
55: The length of the line, including the final newline,
56: is stored in the memory location to which
57: .Fa len
58: points.
59: (Note, however, that if the line is the last
60: in a file that does not end in a newline,
61: the returned text will not contain a newline.)
62: .Sh RETURN VALUES
63: Upon successful completion a pointer is returned;
64: this pointer becomes invalid after the next
65: .Tn I/O
66: operation on
67: .Fa stream
68: (whether successful or not)
69: or as soon as the stream is closed.
70: Otherwise,
71: .Dv NULL
72: is returned.
73: The
74: .Fn fgetln
75: function
76: does not distinguish between end-of-file and error; the routines
77: .Xr feof 3
78: and
79: .Xr ferror 3
80: must be used
81: to determine which occurred.
1.2 jtc 82: If an error occurs, the global variable
1.1 cgd 83: .Va errno
84: is set to indicate the error.
85: The end-of-file condition is remembered, even on a terminal, and all
86: subsequent attempts to read will return
87: .Dv NULL
88: until the condition is
89: cleared with
90: .Xr clearerr 3 .
91: .Pp
92: The text to which the returned pointer points may be modified,
93: provided that no changes are made beyond the returned size.
94: These changes are lost as soon as the pointer becomes invalid.
95: .Sh ERRORS
96: .Bl -tag -width [EBADF]
97: .It Bq Er EBADF
98: The argument
99: .Fa stream
100: is not a stream open for reading.
101: .El
102: .Pp
103: The
104: .Fn fgetln
105: function
106: may also fail and set
107: .Va errno
108: for any of the errors specified for the routines
109: .Xr fflush 3 ,
110: .Xr malloc 3 ,
111: .Xr read 2 ,
112: .Xr stat 2 ,
113: or
114: .Xr realloc 3 .
115: .Sh SEE ALSO
116: .Xr ferror 3 ,
117: .Xr fgets 3 ,
118: .Xr fopen 3 ,
119: .Xr putc 3
120: .Sh HISTORY
121: The
122: .Fn fgetln
1.4 perry 123: function first appeared in
124: .Bx 4.4 .
1.14 ! drochner 125: .Sh CAVEATS
! 126: Since the returned buffer is not a C string (it is not null terminated), a
! 127: common practice is to replace the newline character with
! 128: .Sq \e0 .
! 129: However, if the last line in a file does not contain a newline,
! 130: the returned text won't contain a newline either.
! 131: The following code demonstrates how to deal with this problem by allocating a
! 132: temporary buffer:
! 133: .Bd -literal
! 134: char *buf, *lbuf;
! 135: size_t len;
! 136:
! 137: lbuf = NULL;
! 138: while ((buf = fgetln(fp, &len))) {
! 139: if (buf[len - 1] == '\en')
! 140: buf[len - 1] = '\e0';
! 141: else {
! 142: if ((lbuf = (char *)malloc(len + 1)) == NULL)
! 143: err(1, NULL);
! 144: memcpy(lbuf, buf, len);
! 145: lbuf[len] = '\e0';
! 146: buf = lbuf;
! 147: }
! 148: printf("%s\en", buf);
! 149:
! 150: if (lbuf != NULL) {
! 151: free(lbuf);
! 152: lbuf = NULL;
! 153: }
! 154: }
! 155: .Ed
CVSweb <webmaster@jp.NetBSD.org>