wcstring(3S)wcstring(3S)NAME
wcstring: 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 - wchar_t string operations and type
transformation
SYNOPSIS
#include <wchar.h>
wchar_t *wcscat(wchar_t *s1, const wchar_t *s2);
wchar_t *wscat(wchar_t *s1, wchar_t *s2);
wchar_t *wcsncat(wchar_t *s1, const wchar_t *s2, size_t n);
wchar_t *wsncat(wchar_t *s1, wchar_t *s2, int n);
int wcscmp(wchar_t *s1, const wchar_t *s2);
int wscmp(wchar_t *s1, wchar_t *s2);
int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);
int wsncmp(wchar_t *s1, wchar_t *s2, int n);
int wcscoll(const wchar_t *s1, const wchar_t *s2);
wchar_t *wcscpy(wchar_t *s1, const wchar_t *s2);
wchar_t *wscpy(wchar_t *s1, wchar_t *s2);
wchar_t *wcsncpy(wchar_t *s1, const wchar_t *s2, size_t n);
wchar_t *wsncpy(wchar_t *s1, wchar_t *s2, int n);
size_t wcslen(const wchar_t *s);
int wslen(wchar_t *s);
wchar_t *wcschr(const wchar_t *s, wchar_t c);
wchar_t *wschr(wchar_t *s, int c);
wchar_t *wcsrchr(const wchar_t *s, int c);
wchar_t *wsrchr(wchar_t *s, int c);
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
wchar_t *wspbrk(wchar_t *s1, wchar_t *s2);
int wcsspn(const wchar_t *s1, const wchar_t *s2);
int wsspn(wchar_t *s1, wchar_t *s2);
int wscspn(wchar_t *s1, wchar_t *s2);
XPG4
wchar_t *wcstok(wchar_t *s1, const wchar_t *s2);
XPG5
wchar_t *wcstok(wchar_t *s1, const wchar_t *s2, wchar_t **ptr);
char *wstostr(char *s1, wchar_t *s2);
Page 1
wcstring(3S)wcstring(3S)
wchar_t *wcswcs(const wchar_t *s1, const wchar_t *s2);
int wcswidth(const wchar_t *s, size_t n);
int wcwidth(wchar_t wc);
DESCRIPTION (International Functions)
The arguments s1, s2, and s point to wchar_t strings (that is, arrays of
wchar_t characters terminated by a wchar_t null character). The
functions wcscat, wscat, wcsncat, wsncat, wcscpy, wscpy, wcsncpy and
wsncpy all modify s1. These functions do not check for an overflow
condition of the array pointed to by s1.
wcscat and wscat append a copy of the wchar_t string s2 to the end of the
wchar_t string s1. wcsncat and wsncat append at most n wchar_t
characters. Each function returns s1.
wcscmp and wscmp compare its arguments and returns an integer less than,
equal to, or greater than 0, depending on whether s1 is less than, equal
to, or greater than s2. wcsncmp and wsncmp make the same comparison but
look at most at n wchar_t characters.
wcscpy and wscpy copy wchar_t string s2 to s1, stopping after the wchar_t
null character has been copied. wcsncpy and wsncpy copy exactly n
wchar_t characters, truncating s2 or adding wchar_t null characters to
s1, if necessary. The result will not be wchar_t null-terminated if the
length of s2 is n or more. Each function returns s1.
wcslen and wslen return the number of wchar_t characters in s, not
including the terminating wchar_t null character.
wcschr, wschr, wcsrchr and wsrchr return a pointer to the first and last
occurrence, respectively, of wchar_t character c in wchar_t string s, or
a null pointer, if c does not occur in the string. The wchar_t null
character terminating a string is considered to be part of the string.
wcspbrk and wspbrk return a pointer to the first occurrence in wchar_t
string s1 of any wchar_t character from wchar_t string s2, or a null
pointer if there is no wchar_t character from s2 in s1.
wcsspn and wsspn return the length of the initial segment of wchar_t
string s1, which consists entirely of wchar_t characters from wchar_t
string s2. wscspn returns the length of the initial segment of wchar_t
string s1, which does not consist entirely of wchar_t characters from
wchar_t string s2.
wcstok treats the wchar_t string s1 as a sequence of zero or more text
tokens, separated by spans of one or more wchar_t characters from the
separator wchar_t string s2. The first call (with the pointer s1
specified) returns a pointer to the first wchar_t character of the first
token, and writes a wchar_t null character into s1 immediately following
the returned token. The function keeps track of its position in the
wchar_t string between separate calls, so that subsequent calls (which
Page 2
wcstring(3S)wcstring(3S)
must be made with the first argument a null pointer) will progress
through the wchar_t string s1 immediately following that token.
Similarly, subsequent calls will progress through the wchar_t string s1
until no tokens remain. The wchar_t separator string s2 may be different
from call to call. A null pointer is returned when no token remains in
s1. For XPG5 type wcstok function, there is an additional argument ptr
which points to a wchar_t pointer into which the function stores
information necessary for it to continue processing the same wide
character string.
wstostr transforms wchar_t characters in wchar_t string s2 into EUC, and
transfers them to character string s1, stopping after the wchar_t null
character has been processed.
wcscoll compares the wide character string pointed to by s1 to the wide
character string pointed to by s2, both interpreted as appropriate to the
LC_COLLATE category of the current locale. Upon successful completion,
wcscoll returns an integer greater than, equal to or less than zero,
according to whether the wide character string pointed to by s1 is
greater than, equal to or less than the wide character string pointed to
by s2, when both are interpreted as appropriate to the current locale.
On error, wcscoll may set errno, but no return value is reserved to
indicate an error. If errno is set to EINVAL, then the s1 or s2
arguments contain wide character codes outside the domain of the
collating sequence.
wcswcs locates the first occurrence in the wide character string pointed
to by s1 of the sequence of wide-character codes (excluding the
terminating null wide-character code) in the wide character string
pointed to by s2. Upon successful completion, wcswcs returns a pointer
to the located wide character string or a null pointer if the wide
character string is not found. If s2 points to a wide character string
with zero length, the function returns s1.
wcswidth determines the number of column positions required for n wide-
character codes (or fewer than n wide-character codes if a null wide-
character code is encountered before n wide-character codes are
exhausted) in the string pointed to by s. wcswidth either returns 0 (if
s 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 s, or
returns -1 (if any of the first n wide-character codes in the wide
character string pointed to by s is not a printing wide-character code).
wcwidth determines the number of column positions required for the wide
character wc. The value of wc must be a character representable as a
wchar_t, and must be a wide-character code corresponding to a valid
character in the current locale. wcwidth either returns 0 (if wc is a
null wide-character code), or returns the number of column positions to
be occupied by the wide-character code wc, or returns -1 (if wc does not
correspond to a prinable wide-character code).
Page 3
wcstring(3S)wcstring(3S)SEE ALSOmalloc(3C), widec(3S), malloc(3X).
DIAGNOSTICS
On success, wstostr returns s1. If an illegal byte sequence is detected,
a null pointer is returned and errno is set to EILSEQ.
NOTES
There are two types of wcstok functions in n32 and 64 bit C libraries for
IRIX 6.5.17 and later versions. One is XPG4 type which has been in C
library, and another is XPG5 type function. The difference is an
additonal third argument type in XPG5 type of the function, which is
wchar_t **ptr. Old programs calling wcstok function have XPG4 behavior of
the function for backward compatibility. When XPG5 behavior is required,
new programs must be compiled with the wchar.h header file and
_XOPEN_SOURCE set to 500. XPG5 type function is not supported in o32 C
library.
The XPG5 type wcstok function is actually defined as a static inline
function in wchar_core.h, and it calls a new function _xpg5_wcstok which
is specific to IRIX 6.5.17 and later. Therefore applications that call
XPG5 type wcstok should check the existence of the new symbol.
#include <wchar.h>
#include <optional_sym.h>
if (_MIPS_SYMBOL_PRESENT(_xpg5_wcstok)) {
wcstok(s1, s2, &ptr);
} else {
...
}
Because the static inline function is defined in each source file that
includes wchar.h, these static functions will have different addresses in
any cases that inline expansion is not performed. This may cause problems
if the address of the function is examined in programs. To avoid this
problem, use -D_XPG5_WCSTOK_USER_DEFINED compile option to disable the
static inline definition in wchar_core.h, and define a user defined
function with below definition:
wchar_t *
wcstok(wchar_t * _ws1, const wchar_t * _ws2, wchar_t ** _pws)
{
return(_xpg5_wcstok(_ws1, _ws2, _pws));
}
Use the compile option always, when a user defined XPG5 wcstok function
is required.
Page 4
