[BACK]Return to fgetln.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / stdio

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>