man3/fgetws.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .\"
   5 .\" References consulted:
   6 .\"   GNU glibc-2 source code and manual
   7 .\"   Dinkumware C library reference http://www.dinkumware.com/
   8 .\"   OpenGroup's Single UNIX specification
   9 .\"     http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon <moz@compsoc.man.ac.uk>
  13 .TH FGETWS 3  2021-03-22 "Linux man-pages (unreleased)"
  14 .SH NAME
  15 fgetws \- read a wide-character string from a FILE stream
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wchar.h>
  22 .PP
  23 .BI "wchar_t *fgetws(wchar_t *restrict " ws ", int " n \
  24 ", FILE *restrict " stream );
  25 .fi
  26 .SH DESCRIPTION
  27 The
  28 .BR fgetws ()
  29 function is the wide-character equivalent
  30 of the
  31 .BR fgets (3)
  32 function.
  33 It reads a string of at most \fIn\-1\fP wide characters into the
  34 wide-character array pointed to by \fIws\fP,
  35 and adds a terminating null wide character (L\(aq\e0\(aq).
  36 It stops reading wide characters after it has encountered and
  37 stored a newline wide character.
  38 It also stops when end of stream is reached.
  39 .PP
  40 The programmer must ensure that there is room for at least \fIn\fP wide
  41 characters at \fIws\fP.
  42 .PP
  43 For a nonlocking counterpart, see
  44 .BR unlocked_stdio (3).
  45 .SH RETURN VALUE
  46 The
  47 .BR fgetws ()
  48 function, if successful, returns \fIws\fP.
  49 If end of stream
  50 was already reached or if an error occurred, it returns NULL.
  51 .SH ATTRIBUTES
  52 For an explanation of the terms used in this section, see
  53 .BR attributes (7).
  54 .ad l
  55 .nh
  56 .TS
  57 allbox;
  58 lbx lb lb
  59 l l l.
  60 Interface       Attribute       Value
  61 T{
  62 .BR fgetws ()
  63 T}      Thread safety   MT-Safe
  64 .TE
  65 .hy
  66 .ad
  67 .sp 1
  68 .SH STANDARDS
  69 POSIX.1-2001, POSIX.1-2008, C99.
  70 .SH NOTES
  71 The behavior of
  72 .BR fgetws ()
  73 depends on the
  74 .B LC_CTYPE
  75 category of the
  76 current locale.
  77 .PP
  78 In the absence of additional information passed to the
  79 .BR fopen (3)
  80 call, it is
  81 reasonable to expect that
  82 .BR fgetws ()
  83 will actually read a multibyte string
  84 from the stream and then convert it to a wide-character string.
  85 .PP
  86 This function is unreliable,
  87 because it does not permit to deal properly with
  88 null wide characters that may be present in the input.
  89 .SH SEE ALSO
  90 .BR fgetwc (3),
  91 .BR unlocked_stdio (3)