stdio/FreeBSD/ungetwc.3.patch

   1 --- ungetwc.3.bsdnew    2009-11-11 13:33:18.000000000 -0800
   2 +++ ungetwc.3   2009-11-11 13:33:18.000000000 -0800
   3 @@ -38,7 +38,8 @@
   4  .Dt UNGETWC 3
   5  .Os
   6  .Sh NAME
   7 -.Nm ungetwc
   8 +.Nm ungetwc ,
   9 +.Nm ungetwc_l
  10  .Nd un-get wide character from input stream
  11  .Sh LIBRARY
  12  .Lb libc
  13 @@ -46,7 +47,19 @@
  14  .In stdio.h
  15  .In wchar.h
  16  .Ft wint_t
  17 -.Fn ungetwc "wint_t wc" "FILE *stream"
  18 +.Fo ungetwc
  19 +.Fa "wint_t wc"
  20 +.Fa "FILE *stream"
  21 +.Fc
  22 +.In stdio.h
  23 +.In wchar.h
  24 +.In xlocale.h
  25 +.Ft wint_t
  26 +.Fo ungetwc_l
  27 +.Fa "wint_t wc"
  28 +.Fa "FILE *stream"
  29 +.Fa "locale_t loc"
  30 +.Fc
  31  .Sh DESCRIPTION
  32  The
  33  .Fn ungetwc
  34 @@ -56,22 +69,31 @@ function pushes the wide character
  35  .Vt wchar_t )
  36  back onto the input stream pointed to by
  37  .Fa stream .
  38 -The pushed-backed wide characters will be returned by subsequent reads on the
  39 -stream (in reverse order).
  40 -A successful intervening call, using the same stream, to one of the file
  41 +The pushed-backed wide characters will be returned (in reverse order)
  42 +by subsequent reads on the stream.
  43 +A successful intervening call to one of the file
  44  positioning functions
  45  .Xr fseek 3 ,
  46  .Xr fsetpos 3 ,
  47  or
  48 -.Xr rewind 3
  49 -will discard the pushed back wide characters.
  50 +.Xr rewind 3 ,
  51 +using the same stream,
  52 +will discard the pushed-back wide characters.
  53  .Pp
  54 -One wide character of push-back is guaranteed,
  55 -but as long as there is
  56 -sufficient memory, an effectively infinite amount of pushback is allowed.
  57 +Only one wide character of push-back is guaranteed,
  58 +but as long as there is sufficient memory,
  59 +an effectively infinite amount of push-back is allowed.
  60  .Pp
  61  If a character is successfully pushed-back,
  62  the end-of-file indicator for the stream is cleared.
  63 +.Pp
  64 +Although the
  65 +.Fn ungetwc
  66 +function uses the current locale, the
  67 +.Fn ungetwc_l
  68 +function may be passed a locale directly. See
  69 +.Xr xlocale 3
  70 +for more information.
  71  .Sh RETURN VALUES
  72  The
  73  .Fn ungetwc
  74 @@ -87,7 +109,8 @@ character equals
  75  the operation will fail and the stream will remain unchanged.
  76  .Sh SEE ALSO
  77  .Xr fseek 3 ,
  78 -.Xr getwc 3
  79 +.Xr getwc 3 ,
  80 +.Xr xlocale 3
  81  .Sh STANDARDS
  82  The
  83  .Fn ungetwc