From 772773c74cfb910591ec5c32c82b458f8ec23909 Mon Sep 17 00:00:00 2001 From: tjr Date: Mon, 12 Aug 2002 13:23:12 +0000 Subject: Manual pages for fwide(), getwc(), fgetwc(), getwchar(), putwc(), fputwc(), putwchar(), ungetwc() from NetBSD and Citrus Project, unmodified except for the addition of $FreeBSD$. Obtained from: NetBSD, Citrus Project --- lib/libc/stdio/fwide.3 | 95 ++++++++++++++++++++++++++++++++++++++ lib/libc/stdio/getwc.3 | 117 +++++++++++++++++++++++++++++++++++++++++++++++ lib/libc/stdio/putwc.3 | 105 ++++++++++++++++++++++++++++++++++++++++++ lib/libc/stdio/ungetwc.3 | 100 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 417 insertions(+) create mode 100644 lib/libc/stdio/fwide.3 create mode 100644 lib/libc/stdio/getwc.3 create mode 100644 lib/libc/stdio/putwc.3 create mode 100644 lib/libc/stdio/ungetwc.3 diff --git a/lib/libc/stdio/fwide.3 b/lib/libc/stdio/fwide.3 new file mode 100644 index 0000000..7629852 --- /dev/null +++ b/lib/libc/stdio/fwide.3 @@ -0,0 +1,95 @@ +.\" $NetBSD: fwide.3,v 1.3 2002/02/07 07:00:25 ross Exp $ +.\" +.\" Copyright (c)2001 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Citrus: xpg4dl/FreeBSD/lib/libc/stdio/fwide.3,v 1.2 2001/12/07 04:47:08 yamt Exp $ +.\" $FreeBSD$ +.\" +.Dd October 24, 2001 +.Dt FWIDE 3 +.Os +.Sh NAME +.Nm fwide +.Nd get/set orientation of a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Fd #include \*[Lt]stdio.h\*[Gt] +.Fd #include \*[Lt]wchar.h\*[Gt] +.Ft int +.Fn fwide "FILE *stream" "int mode" +.Sh DESCRIPTION +The +.Fn fwide +function +determines the orientation of the stream pointed at by +.Fa stream . +.Pp +If the orientation of +.Fa stream +has already been determined, +.Fn fwide +leaves it unchanged. +Otherwise, +.Fn fwide +sets the orientation of +.Fa stream +according to +.Fa mode . +.Pp +If +.Fa mode +is less than zero, +.Fa stream +is set to byte-oriented. +If it is greater than zero, +.Fa stream +is set to wide-oriented. +Otherwise, +.Fa mode +is zero, and +.Fa stream +is unchanged. +.Sh RETURN VALUES +.Fn fwide +returns a value according to orientation after the call of +.Fn fwide ; +a value less than zero if byte-oriented, a value greater than zero +if wide-oriented, and zero if the stream has no orientation. +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fgetc 3 , +.Xr fgetwc 3 , +.Xr fopen 3 , +.Xr fputc 3 , +.Xr fputwc 3 , +.Xr freopen 3 , +.Xr stdio 3 +.Sh STANDARDS +The +.Fn fwide +function +conforms to +.St -isoC99 . diff --git a/lib/libc/stdio/getwc.3 b/lib/libc/stdio/getwc.3 new file mode 100644 index 0000000..b585bac --- /dev/null +++ b/lib/libc/stdio/getwc.3 @@ -0,0 +1,117 @@ +.\" $NetBSD: getwc.3,v 1.3 2002/02/07 07:00:26 ross Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getc.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd October 24, 2001 +.Dt GETWC 3 +.Os +.Sh NAME +.Nm fgetwc , +.Nm getwc , +.Nm getwchar , +.Nd get next wide-character from input stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Fd #include \*[Lt]stdio.h\*[Gt] +.Fd #include \*[Lt]wchar.h\*[Gt] +.Ft wint_t +.Fn fgetwc "FILE *stream" +.Ft wint_t +.Fn getwc "FILE *stream" +.Ft wint_t +.Fn getwchar +.Sh DESCRIPTION +The +.Fn fgetwc +function +obtains the next input wide-character (if present) from the stream pointed at by +.Fa stream , +or the next character pushed back on the stream via +.Xr ungetwc 3 . +.Pp +The +.Fn getwc +function +acts essentially identically to +.Fn fgetwc , +but is a macro that expands in-line. +.Pp +The +.Fn getwchar +function +is equivalent to +.Fn getwc +with the argument stdin. +.Sh RETURN VALUES +If successful, these routines return the next wide-character +from the +.Fa stream . +If the stream is at end-of-file or a read error occurs, +the routines return +.Dv WEOF . +The routines +.Xr feof 3 +and +.Xr ferror 3 +must be used to distinguish between end-of-file and error. +If an error occurs, the global variable +.Va errno +is set to indicate the error. +The end-of-file condition is remembered, even on a terminal, and all +subsequent attempts to read will return +.Dv WEOF +until the condition is cleared with +.Xr clearerr 3 . +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fopen 3 , +.Xr fread 3 , +.Xr putwc 3 , +.Xr stdio 3 , +.Xr ungetwc 3 +.Sh STANDARDS +The +.Fn fgetwc , +.Fn getwc +and +.Fn getwchar +functions +conform to +.St -isoC99 . diff --git a/lib/libc/stdio/putwc.3 b/lib/libc/stdio/putwc.3 new file mode 100644 index 0000000..0043399 --- /dev/null +++ b/lib/libc/stdio/putwc.3 @@ -0,0 +1,105 @@ +.\" $NetBSD: putwc.3,v 1.2 2002/02/07 07:00:26 ross Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)putc.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd October 20, 2001 +.Dt PUTWC 3 +.Os +.Sh NAME +.Nm fputwc , +.Nm putwc , +.Nm putwchar , +.Nd output a wide-character to a stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Fd #include \*[Lt]stdio.h\*[Gt] +.Fd #include \*[Lt]wchar.h\*[Gt] +.Ft wint_t +.Fn fputwc "wchar_t wc" "FILE *stream" +.Ft wint_t +.Fn putwc "wchar_t wc" "FILE *stream" +.Ft wint_t +.Fn putwchar "wchar_t wc" +.Sh DESCRIPTION +The +.Fn fputwc +function +writes the wide-character +.Fa wc +to the output stream pointed to by +.Fa stream . +.Pp +.Fn putwc +acts essentially identically to +.Fn fputwc , +but is a macro that expands in-line. It may evaluate +.Fa stream +more than once, so arguments given to +.Fn putwc +should not be expressions with potential side effects. +.Pp +.Fn putwchar +is identical to +.Fn putwc +with an output stream of +.Em stdout . +.Sh RETURN VALUES +The functions, +.Fn fputwc , +.Fn putwc +and +.Fn putwchar +return the wide-character written. +If an error occurs, the value +.Dv WEOF +is returned. +.Sh SEE ALSO +.Xr ferror 3 , +.Xr fopen 3 , +.Xr getwc 3 , +.Xr stdio 3 +.Sh STANDARDS +The functions +.Fn fputwc , +.Fn putwc , +and +.Fn putwchar , +conform to +.St -isoC99 . diff --git a/lib/libc/stdio/ungetwc.3 b/lib/libc/stdio/ungetwc.3 new file mode 100644 index 0000000..8a4098d --- /dev/null +++ b/lib/libc/stdio/ungetwc.3 @@ -0,0 +1,100 @@ +.\" $NetBSD: ungetwc.3,v 1.3 2002/02/07 07:00:27 ross Exp $ +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ungetc.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd October 24, 2001 +.Dt UNGETWC 3 +.Os +.Sh NAME +.Nm ungetwc +.Nd un-get wide-character from input stream +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.Fd #include \*[Lt]stdio.h\*[Gt] +.Fd #include \*[Lt]wchar.h\*[Gt] +.Ft wint_t +.Fn ungetwc "wint_t wc" "FILE *stream" +.Sh DESCRIPTION +The +.Fn ungetwc +function pushes the wide-character +.Fa wc +(converted to an wchar_t) +back onto the input stream pointed to by +.Fa stream . +The pushed-backed wide-characters will be returned by subsequent reads on the +stream (in reverse order). +A successful intervening call, using the same stream, to one of the file +positioning functions +.Xr fseek 3 , +.Xr fsetpos 3 , +or +.Xr rewind 3 +will discard the pushed back wide-characters. +.Pp +One wide-character of push-back is guaranteed, +but as long as there is +sufficient memory, an effectively infinite amount of pushback is allowed. +.Pp +If a character is successfully pushed-back, +the end-of-file indicator for the stream is cleared. +.Sh RETURN VALUES +The +.Fn ungetwc +function +returns +the wide-character pushed-back after the conversion, or +.Dv WEOF +if the operation fails. +If the value of the argument +.Fa c +character equals +.Dv WEOF , +the operation will fail and the stream will remain unchanged. +.Sh SEE ALSO +.Xr fseek 3 , +.Xr getwc 3 +.Sh STANDARDS +The +.Fn ungetwc +function conforms to +.St -isoC99 . +.Sh BUGS +The current implementation uses a fixed sized ungetwc-buffer. -- cgit v1.1