diff options
Diffstat (limited to 'man3/wcrtomb.3')
| -rw-r--r-- | man3/wcrtomb.3 | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/man3/wcrtomb.3 b/man3/wcrtomb.3 new file mode 100644 index 000000000..fdac276d8 --- /dev/null +++ b/man3/wcrtomb.3 @@ -0,0 +1,58 @@ +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" This is free documentation; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2 of +.\" the License, or (at your option) any later version. +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH WCRTOMB 3 1999-07-25 "GNU" "Linux Programmer's Manual" +.SH NAME +wcrtomb \- convert a wide character to a multibyte sequence +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.sp +.BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The main case for this function is when \fIs\fP is not NULL and \fIwc\fP is not +L'\\0'. +In this case, the \fBwcrtomb\fP function converts the wide character \fIwc\fP +to its multibyte representation and stores it at the beginning of the character +array pointed to by \fIs\fP. It updates the shift state \fI*ps\fP, and +returns the length of said multibyte representation, i.e. the number of bytes +written at \fIs\fP. +.PP +A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. In this +case the \fBwcrtomb\fP function stores at the character array pointed to by +\fIs\fP the shift sequence needed to bring \fI*ps\fP back to the initial state, +followed by a '\\0' byte. It updates the shift state \fI*ps\fP (i.e. brings +it into the initial state), and returns the length of the shift sequence plus +one, i.e. the number of bytes written at \fIs\fP. +.PP +A third case is when \fIs\fP is NULL. In this case \fIwc\fP is ignored, +and the function effectively returns wcrtomb(buf,L'\\0',\fIps\fP) where +buf is an internal anonymous buffer. +.PP +In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous +state only known to the wcrtomb function is used instead. +.SH "RETURN VALUE" +The \fBwcrtomb\fP function returns the number of bytes that have been or would +have been written to the byte array at \fIs\fP. If \fIwc\fP can not be +represented as a multibyte sequence (according to the current locale), +(size_t)(-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP. +.SH "CONFORMING TO" +ISO/ANSI C, UNIX98 +.SH "SEE ALSO" +.BR wcsrtombs (3) +.SH NOTES +The behaviour of \fBwcrtomb\fP depends on the LC_CTYPE category of the +current locale. +.PP +Passing NULL as \fIps\fP is not multi-thread safe. |