89 lines
3.8 KiB
Plaintext
89 lines
3.8 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3c.mbstring @(#)mbstring 41.3 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
'\"macro stdmacro
|
|
.if n .pH g3c.mbstring 'ident "@(#)ccsman:g3c/mbstring 1.1"'
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.nr X
|
|
.if \nX=0 .ds x} mbstring 3C "C Development Set" "\&"
|
|
.if \nX=1 .ds x} mbstring 3C "C Development Set"
|
|
.if \nX=2 .ds x} mbstring 3C "" "\&"
|
|
.if \nX=3 .ds x} mbstring "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4mbstring\f1: \f4mbstowcs\f1, \f4wcstombs\f1, \f4wcsxfrm\f1 \- multibyte
|
|
string functions
|
|
.SH SYNOPSIS
|
|
\f4#include <stdlib.h>\f1
|
|
.br
|
|
\f4size_t mbstowcs (wchar_t \(**pwcs, const char \(**s, size_t n);\f1
|
|
.br
|
|
\f4size_t wcstombs (char \(**s, const wchar_t \(**pwcs, size_t n);\f1
|
|
.PP
|
|
\f4#include <wchar.h>\f1
|
|
.br
|
|
\f4size_t wcsxfrm (wchar_t \(**ws1, const wchar_t \(**ws2, size_t n);\f1
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\f4mbstowcs\fP converts a sequence of multibyte characters from the
|
|
array pointed to by \f2s\f1 into a sequence of corresponding wide
|
|
character codes and stores these codes into the array pointed to by
|
|
\f2pwcs\f1, stopping after \f2n\f1 codes are stored or a code with value
|
|
zero (a converted
|
|
null
|
|
character) is stored. If \f2pwcs\f1 is a null pointer, \f4mbstowcs\fP returns
|
|
the length required to convert the entire array regardless of the value of
|
|
\f2n\f1, but no values are stored.
|
|
.PP
|
|
\f4wcstombs\fP converts a sequence of wide character codes from the array
|
|
pointed to by \f2pwcs\f1 into a sequence of multibyte characters and
|
|
stores these multibyte characters into the array pointed to by \f2s\f1,
|
|
stopping if a multibyte character would exceed the limit of \f2n\f1 total
|
|
bytes or if a
|
|
null
|
|
character is stored. If \f2s\f1 is a null pointer, \f4wcstombs\fP returns
|
|
the length required to convert the entire array regardless of the value of
|
|
\f2n\f1, but no values are stored. This function returns the number of bytes
|
|
required for the character array.
|
|
.PP
|
|
\f4wcsxfrm\fP transforms the wide character string pointed to by \f2ws2\f1
|
|
and places the resulting wide character string into the array pointed to by
|
|
\f2ws1\f1 . The transformation is such that if \f4wcscmp\f1 is applied to two
|
|
transformed wide strings, it returns a value greater than, equal to or less
|
|
than \f40\f1, corresponding to the result of \f4wcscoll\f1 applied to the
|
|
same two original wide character strings. No more than \f2n\f1 wide-character
|
|
codes are placed into the resulting array pointed to by \f2ws1\f1 , including
|
|
the terminating null wide-character code. If \f2n\f1 is \f40\f1, \f2ws1\f1 is
|
|
permitted to be a null pointer. If copying takes place between objects that
|
|
overlap, the behaviour is undefined. \f4wcsxfrm\f1 returns the length of the
|
|
transformed wide character string (not including the terminating null
|
|
wide-character code). If the value returned is \f2n\f1 or more, the contents
|
|
of the array pointed to by \f2ws1\f1 are indeterminate.
|
|
.SH "SEE ALSO"
|
|
\f4wchrtbl\fP(1M), \f4mbchar\fP(3C), \f4setlocale\fP(3C), \f4wcscmp\fP(3S),
|
|
\f4wcscoll\fP(3S), \f4environ\f1(5), \f4<wchar.h>\fP.
|
|
.SH DIAGNOSTICS
|
|
.PP
|
|
If an invalid multibyte character is encountered, \f4mbstowcs\fP returns
|
|
(\f4size_t\f1)\-1 with \f4errno\f1 set equal to \f4EILSEQ\f1.
|
|
Otherwise, \f4mbstowcs\fP returns
|
|
the number of array elements modified, not
|
|
including the terminating zero code, if any.
|
|
.PP
|
|
If a wide character code is
|
|
encountered that does not correspond to a valid multibyte character,
|
|
\f4wcstombs\fP returns (\f4size_t\f1)\-1 with \f4errno\f1 set equal
|
|
to \f4EILSEQ\f1.
|
|
Otherwise, \f4wcstombs\fP returns
|
|
the number of bytes modified, not including a terminating
|
|
null
|
|
character,
|
|
if any.
|
|
.PP
|
|
On error, \f4wcsxfrm\f1 returns \f4(size_t)\-1\f1 and sets \f4errno\f1 to
|
|
indicate the error. If the wide character string pointed to by \f2ws2\f1
|
|
contains wide-character codes outside the domain of the collating sequence,
|
|
then \f4errno\f1 is set to \f4EINVAL\f1.
|
|
.Ee
|