stdio/FreeBSD/fgetws.3.patch

   1 --- fgetws.3.bsdnew     2009-11-11 13:33:05.000000000 -0800
   2 +++ fgetws.3    2009-11-11 13:33:05.000000000 -0800
   3 @@ -37,7 +37,8 @@
   4  .Dt FGETWS 3
   5  .Os
   6  .Sh NAME
   7 -.Nm fgetws
   8 +.Nm fgetws ,
   9 +.Nm fgetws_l
  10  .Nd get a line of wide characters from a stream
  11  .Sh LIBRARY
  12  .Lb libc
  13 @@ -45,7 +46,21 @@
  14  .In stdio.h
  15  .In wchar.h
  16  .Ft "wchar_t *"
  17 -.Fn fgetws "wchar_t * restrict ws" "int n" "FILE * restrict fp"
  18 +.Fo fgetws
  19 +.Fa "wchar_t *restrict ws"
  20 +.Fa "int n"
  21 +.Fa "FILE *restrict stream"
  22 +.Fc
  23 +.In stdio.h
  24 +.In wchar.h
  25 +.In xlocale.h
  26 +.Ft "wchar_t *"
  27 +.Fo fgetws_l
  28 +.Fa "wchar_t *restrict ws"
  29 +.Fa "int n"
  30 +.Fa "FILE *restrict stream"
  31 +.Fa "locale_t loc"
  32 +.Fc
  33  .Sh DESCRIPTION
  34  The
  35  .Fn fgetws
  36 @@ -53,7 +68,7 @@ function
  37  reads at most one less than the number of characters specified by
  38  .Fa n
  39  from the given
  40 -.Fa fp
  41 +.Fa stream
  42  and stores them in the wide character string
  43  .Fa ws .
  44  Reading stops when a newline character is found,
  45 @@ -62,6 +77,14 @@ The newline, if any, is retained.
  46  If any characters are read and there is no error, a
  47  .Ql \e0
  48  character is appended to end the string.
  49 +.Pp
  50 +While the
  51 +.Fn fgetws
  52 +function uses the current locale, the
  53 +.Fn fgetws_l
  54 +function may be passed a locale directly. See
  55 +.Xr xlocale 3
  56 +for more information.
  57  .Sh RETURN VALUES
  58  Upon successful completion,
  59  .Fn fgetws
  60 @@ -80,7 +103,8 @@ and the buffer contents are indeterminat
  61  The
  62  .Fn fgetws
  63  function
  64 -does not distinguish between end-of-file and error, and callers must use
  65 +does not distinguish between end-of-file and error;
  66 +callers must use
  67  .Xr feof 3
  68  and
  69  .Xr ferror 3
  70 @@ -92,7 +116,7 @@ function will fail if:
  71  .Bl -tag -width Er
  72  .It Bq Er EBADF
  73  The given
  74 -.Fa fp
  75 +.Fa stream
  76  argument is not a readable stream.
  77  .It Bq Er EILSEQ
  78  The data obtained from the input stream does not form a valid
  79 @@ -112,7 +136,8 @@ or
  80  .Sh SEE ALSO
  81  .Xr feof 3 ,
  82  .Xr ferror 3 ,
  83 -.Xr fgets 3
  84 +.Xr fgets 3 ,
  85 +.Xr xlocale 3
  86  .Sh STANDARDS
  87  The
  88  .Fn fgetws