lib/libc/stdio/fgetwln.3

   1 .\"     $NetBSD: fgetwln.3,v 1.1 2005/05/14 23:51:02 christos Exp $
   2 .\"     $DragonFly: src/lib/libc/stdio/fgetwln.3,v 1.1 2005/07/25 00:37:41 joerg Exp $
   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.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)fgetln.3    8.3 (Berkeley) 4/19/94
  35 .\" $FreeBSD: src/lib/libc/stdio/fgetwln.3,v 1.1 2004/07/16 06:06:09 tjr Exp $
  36 .\"
  37 .Dd July 16, 2004
  38 .Dt FGETWLN 3
  39 .Os
  40 .Sh NAME
  41 .Nm fgetwln
  42 .Nd get a line of wide characters from a stream
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdio.h
  47 .In wchar.h
  48 .Ft wchar_t *
  49 .Fn fgetwln "FILE * restrict stream" "size_t * restrict len"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn fgetwln
  53 function
  54 returns a pointer to the next line from the stream referenced by
  55 .Fa stream .
  56 This line is
  57 .Em not
  58 a standard wide character string as it does not end with a terminating
  59 null wide character.
  60 The length of the line, including the final newline,
  61 is stored in the memory location to which
  62 .Fa len
  63 points.
  64 (Note, however, that if the line is the last
  65 in a file that does not end in a newline,
  66 the returned text will not contain a newline.)
  67 .Sh RETURN VALUES
  68 Upon successful completion a pointer is returned;
  69 this pointer becomes invalid after the next
  70 .Tn I/O
  71 operation on
  72 .Fa stream
  73 (whether successful or not)
  74 or as soon as the stream is closed.
  75 Otherwise,
  76 .Dv NULL
  77 is returned.
  78 The
  79 .Fn fgetwln
  80 function
  81 does not distinguish between end-of-file and error; the routines
  82 .Xr feof 3
  83 and
  84 .Xr ferror 3
  85 must be used
  86 to determine which occurred.
  87 If an error occurs, the global variable
  88 .Va errno
  89 is set to indicate the error.
  90 The end-of-file condition is remembered, even on a terminal, and all
  91 subsequent attempts to read will return
  92 .Dv NULL
  93 until the condition is
  94 cleared with
  95 .Xr clearerr 3 .
  96 .Pp
  97 The text to which the returned pointer points may be modified,
  98 provided that no changes are made beyond the returned size.
  99 These changes are lost as soon as the pointer becomes invalid.
 100 .Sh ERRORS
 101 .Bl -tag -width Er
 102 .It Bq Er EBADF
 103 The argument
 104 .Fa stream
 105 is not a stream open for reading.
 106 .El
 107 .Pp
 108 The
 109 .Fn fgetwln
 110 function
 111 may also fail and set
 112 .Va errno
 113 for any of the errors specified for the routines
 114 .Xr mbrtowc 3 ,
 115 .Xr realloc 3 ,
 116 or
 117 .Xr read 2 .
 118 .Sh SEE ALSO
 119 .Xr ferror 3 ,
 120 .Xr fgetln 3 ,
 121 .Xr fgetws 3 ,
 122 .Xr fopen 3