218 lines
9.1 KiB
Plaintext
218 lines
9.1 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3s.wcstring @(#)wcstring 41.4 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} wcstring 3S "" "\&"
|
|
.if \nX=1 .ds x} wcstring 3S ""
|
|
.if \nX=2 .ds x} wcstring 3S "" "\&"
|
|
.if \nX=3 .ds x} wcstring "" "" "\&"
|
|
.if \nX=9 .ds x} wcstring 3S "SVR4 MNLS" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4wcstring: wcscat, wscat, wcsncat, wsncat, wcscmp, wscmp, wcsncmp, wsncmp,
|
|
wcscoll, wcscpy, wscpy, wcsncpy, wsncpy, wcslen, wslen, wcschr, wschr,
|
|
wcsrchr, wsrchr, wcspbrk, wspbrk, wcsspn, wsspn, wscspn, wcstok, wstostr,
|
|
wcswcs, wcswidth, wcwidth \fP \- \f4wchar_t\fP string operations and type
|
|
transformation
|
|
.SH SYNOPSIS
|
|
.ft 4
|
|
#include <wchar.h>
|
|
.sp .5
|
|
wchar_t \(**wcscat(wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wscat(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wcsncat(wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^, size_t \f2n\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wsncat(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^, int \f2n\fP\^);
|
|
.sp .5
|
|
int wcscmp(wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
int wscmp(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
int wcsncmp(const wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^, size_t \f2n\fP\^);
|
|
.sp .5
|
|
int wsncmp(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^, int \f2n\fP\^);
|
|
.sp .5
|
|
int wcscoll(const wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp
|
|
wchar_t \(**wcscpy(wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wscpy(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wcsncpy(wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^, size_t \f2n\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wsncpy(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^, int \f2n\fP\^);
|
|
.sp .5
|
|
size_t wcslen(const wchar_t \(**\f2s\fP\^);
|
|
.sp .5
|
|
int wslen(wchar_t \(**\f2s\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wcschr(const wchar_t \(**\f2s\fP\^, wchar_t \f2c\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wschr(wchar_t \(**\f2s\fP\^, int \f2c\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wcsrchr(const wchar_t \(**\f2s\fP\^, int \f2c\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wsrchr(wchar_t \(**\f2s\fP\^, int \f2c\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wcspbrk(const wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
wchar_t \(**wspbrk(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.sp .5
|
|
int wcsspn(const wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.br
|
|
int wsspn(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.br
|
|
int wscspn(wchar_t \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.sp
|
|
wchar_t \(**wcstok(wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp
|
|
char \(**wstostr(char \(**\f2s1\fP\^, wchar_t \(**\f2s2\fP\^);
|
|
.sp
|
|
wchar_t \(**wcswcs(const wchar_t \(**\f2s1\fP\^, const wchar_t \(**\f2s2\fP\^);
|
|
.sp
|
|
int wcswidth(const wchar_t \(**\f2s\fP\^, size_t \f2n\fP\^);
|
|
.br
|
|
int wcwidth(wchar_t \f2wc\fP\^);
|
|
.ft 1
|
|
.SH DESCRIPTION (International Functions)
|
|
The arguments \f2s1\fP, \f2s2\fP, and \f2s\fP
|
|
point to \f4wchar_t\fP strings (that is, arrays of
|
|
\f4wchar_t\fP characters terminated by a \f4wchar_t\fP null character).
|
|
The functions \f4wcscat\fP, \f4wscat\fP, \f4wcsncat\fP, \f4wsncat\fP,
|
|
\f4wcscpy\fP, \f4wscpy\fP, \f4wcsncpy\fP and \f4wsncpy\f1 all modify \f2s1\fP.
|
|
These functions do not check for an overflow condition
|
|
of the array pointed to by \f2s1\fP.
|
|
.P
|
|
\f4wcscat\fP and \f4wscat\fP append a copy of the \f4wchar_t\fP string
|
|
\f2s2\fP to the end of the \f4wchar_t\fP string \f2s1\fP.
|
|
\f4wcsncat\fP and \f4wsncat\fP append at most \f2n\fP \f4wchar_t\fP characters.
|
|
Each function returns \f2s1\fP.
|
|
.P
|
|
\f4wcscmp\fP and \f4wscmp\fP compare its arguments and returns an integer
|
|
less than, equal to, or greater than \f40\fP,
|
|
depending on whether \f2s1\fP is less than, equal
|
|
to, or greater than \f2s2\fP.
|
|
\f4wcsncmp\fP and \f4wsncmp\fP make the same comparison but
|
|
look at most at \f2n\fP \f4wchar_t\fP characters.
|
|
.P
|
|
\f4wcscpy\fP and \f4wscpy\fP copy \f4wchar_t\fP string \f2s2\fP to \f2s1\fP,
|
|
stopping after the \f4wchar_t\fP
|
|
null character has been copied.
|
|
\f4wcsncpy\fP and \f4wsncpy\fP copy exactly \f2n\fP \f4wchar_t\fP
|
|
characters, truncating \f2s2\fP or adding \f4wchar_t\fP
|
|
null characters to \f2s1\fP, if necessary.
|
|
The result will not be \f4wchar_t\fP null-terminated if
|
|
the length of \f2s2\fP is \f2n\fP or more.
|
|
Each function returns \f2s1\fP.
|
|
.P
|
|
\f4wcslen\f1 and \f4wslen\f1 return the number of
|
|
\f4wchar_t\fP characters in \f2s\fP, not including
|
|
the terminating \f4wchar_t\fP null character.
|
|
.P
|
|
\f4wcschr\fP, \f4wschr\fP, \f4wcsrchr\fP and \f4wsrchr\fP
|
|
return a pointer to the first and last occurrence, respectively,
|
|
of \f4wchar_t\fP character \f2c\fP in \f4wchar_t\fP string \f2s\fP,
|
|
or a null pointer, if \f2c\fP does not occur in the string.
|
|
The \f4wchar_t\fP null character
|
|
terminating a string is considered to be part of the string.
|
|
.P
|
|
\f4wcspbrk\fP and \f4wspbrk\fP return a pointer to
|
|
the first occurrence in \f4wchar_t\fP
|
|
string \f2s1\fP of any \f4wchar_t\fP character
|
|
from \f4wchar_t\fP string \f2s2\fP, or a
|
|
null pointer if there is no \f4wchar_t\fP character
|
|
from \f2s2\fP in \f2s1\fP.
|
|
.P
|
|
\f4wcsspn\fP and \f4wsspn\fP
|
|
return the length of the initial segment of
|
|
\f4wchar_t\fP string \f2s1\fP, which consists
|
|
entirely of \f4wchar_t\fP characters
|
|
from \f4wchar_t\fP string \f2s2\fP.
|
|
\f4wscspn\fP
|
|
returns the length of the initial segment of
|
|
\f4wchar_t\fP string \f2s1\fP, which does not consist
|
|
entirely of \f4wchar_t\fP characters
|
|
from \f4wchar_t\fP string \f2s2\fP.
|
|
.P
|
|
\f4wcstok\f1 treats the \f4wchar_t\fP
|
|
string \f2s1\fP as a sequence of
|
|
zero or more text tokens,
|
|
separated by spans of one or more
|
|
\f4wchar_t\fP characters from the separator
|
|
\f4wchar_t\fP string \f2s2\fP.
|
|
The first call (with the pointer \f2s1\fP specified)
|
|
returns a pointer to the
|
|
first \f4wchar_t\fP character of the first token,
|
|
and writes a \f4wchar_t\fP null character into \f2s1\fP
|
|
immediately following the returned token.
|
|
The function keeps track of its position in the
|
|
\f4wchar_t\fP string between separate calls,
|
|
so that subsequent calls
|
|
(which must be made with the first argument a null pointer) will
|
|
progress through the \f4wchar_t\fP string \f2s1\fP immediately
|
|
following that token.
|
|
Similarly, subsequent calls will progress through the \f4wchar_t\fP
|
|
string \f2s1\fP until no tokens remain.
|
|
The \f4wchar_t\fP separator
|
|
string \f2s2\fP may be different from call to call.
|
|
A null pointer is returned
|
|
when no token remains in \f2s1\fP.
|
|
.P
|
|
\f4wstostr\f1 transforms \f4wchar_t\fP
|
|
characters in \f4wchar_t\fP string \f2s2\fP into
|
|
\s-1EUC\s+1, and transfers them to
|
|
character string \f2s1\fP, stopping
|
|
after the \f4wchar_t\fP null character has been processed.
|
|
.P
|
|
\f4wcscoll\f1 compares the wide character string pointed to by \f2s1\fP
|
|
to the wide character string pointed to by \f2s2\fP, both interpreted as
|
|
appropriate to the LC_COLLATE category of the current locale. Upon
|
|
successful completion, \f4wcscoll\f1 returns an integer greater than, equal
|
|
to or less than zero, according to whether the wide character string pointed
|
|
to by \f2s1\fP is greater than, equal to or less than the wide character
|
|
string pointed to by \f2s2\fP, when both are intrepreted as appropriate to the
|
|
current locale. On error, \f4wcscoll\f1 may set \f2errno\f1, but no return
|
|
value is reserved to indicate an error. If \f2errno\f1 is set to EINVAL, then
|
|
the \f2s1\fP or \f2s2\fP arguments contain wide character codes outside the
|
|
domain of the collating sequence.
|
|
.P
|
|
\f4wcswcs\f1 locates the first occurence in the wide character string pointed
|
|
to by \f2s1\fP of the sequence of wide-character codes (excluding the
|
|
terminating null wide-character code) in the wide character string pointed to
|
|
by \f2s2\fP. Upon successful completion, \f4wcswcs\f1 returns a pointer to
|
|
the located wide character string or a null pointer if the wide character
|
|
string is not found. If \f2s2\fP points to a wide character string with
|
|
zero length, the function returns \f2s1\fP.
|
|
.P
|
|
\f4wcswidth\f1 determines the number of column positions required for \f2n\fP
|
|
wide-character codes (or fewer than \f2n\fP wide-character codes if a null
|
|
wide-character code is encountered before \f2n\fP wide-character codes are
|
|
exhausted) in the string pointed to by \f2s\fP. \f4wcswidth\f1 either returns
|
|
\f20\fP (if \f2s\fP points to a null wide-character code), or returns the
|
|
number of column positions to be occupied by the wide character string pointed
|
|
to by \f2s\fP, or returns \f2-1\fP (if any of the first \f2n\fP wide-character
|
|
codes in the wide character string pointed to by \f2s\fP is not a printing
|
|
wide-character code).
|
|
.P
|
|
\f4wcwidth\f1 determines the number of column positions required for the wide
|
|
character \f2wc\fP. The value of \f2wc\fP must be a character representable
|
|
as a \f4wchar_t\fP, and must be a wide-character code corresponding to a
|
|
valid character in the current locale. \f4wcwidth\f1 either returns \f20\fP
|
|
(if \f2wc\fP is a null wide-character code), or returns the number of column
|
|
positions to be occupied by the wide-character code \f2wc\fP, or returns
|
|
\f2-1\fP (if \f2wc\fP does not correspond to a prinable wide-character code).
|
|
.SH SEE ALSO
|
|
.na
|
|
\f4malloc\fP(3C),
|
|
\f4widec\fP(3S),
|
|
\f4malloc\fP(3X).
|
|
.ad
|
|
.SH DIAGNOSTICS
|
|
On success, \f4wstostr\fP
|
|
returns \f2s1\fP.
|
|
If an illegal byte sequence is detected, a null pointer is
|
|
returned and \f4errno\fP is set to \f4\s-1EILSEQ\s+1\f1.
|