wcstring(3C)wcstring(3C)NAMEwcscat(), wcsncat(), wcscmp(), wcsncmp(), wcscpy(), wcsncpy(),
wcslen(), wcschr(), wcsrchr(), wcsstr(), wcspbrk(), wcsspn(), wcsc‐
spn(), wcswcs(), wcstok(), wcscoll(), wcwidth(), wcswidth(), wcsxfrm()
- wide character string operations
SYNOPSIS
Unix Standards Only
Unix Standards Only
Obsolescent Interface
Remarks
These functions are compliant with the XPG4 Worldwide Portability
Interface wide-character string handling functions. They parallel the
8 bit string functions defined in string(3C).
DESCRIPTION
The arguments ws1, ws2, and ws point to wide character strings (arrays
of type terminated by a null value).
appends a copy of wide string ws2 to the end of wide string ws1.
appends a maximum of n characters; fewer if ws2 is shorter than n char‐
acters. Each returns a pointer to the null-terminated result (the
value of ws1).
compares its arguments and returns an integer less than, equal to, or
greater than zero, depending on whether ws1 is lexicographically less
than, equal to, or greater than ws2. The comparison of corresponding
wide characters is done by comparing numeric values of the wide charac‐
ter codes. Null pointer values for ws1 and ws2 are treated the same as
pointers to empty wide strings. makes the same comparison but examines
a maximum of n characters (n less than or equal to zero yields equal‐
ity).
copies wide string ws2 to ws1, stopping after the null value has been
copied. copies up to n characters from ws2, adding null values to ws1
if necessary, until a total of n have been copied. The result is not
null-terminated if the length of ws2 is n or more. Each function
returns ws1. Note that should not be used to copy an arbitrary struc‐
ture. If that structure contains sizeof(wchar_t) consecutive null
bytes, may not copy the entire structure. Use the function (see mem‐
ory(3C)) to copy arbitrary binary data.
returns the number of wide characters in ws, not including the termi‐
nating null wide character.
returns a pointer to the first (last) occurrence of wide character wc
in wide string ws, or a null pointer if wc does not occur in the wide
string. The null wide character terminating a wide string is consid‐
ered to be part of the wide string.
locates the first occurrence in the wide-character string pointed to by
ws1 of the sequence of wide-characters (excluding the terminating null
wide-character) in the wide-character string pointed to by ws2. On
successful completion, returns a pointer to the located wide-character
string, or a null pointer if the wide-character string is not found.
If ws2 points to a wide-character string with zero length, the function
returns ws1.
returns a pointer to the first occurrence in wide string ws1 of any
wide character from wide string ws2, or a null pointer if no wide char‐
acter from ws2 exists in ws1.
returns the length of the maximum initial segment of wide string ws1,
which consists entirely of wide characters from (not from) wide string
ws2.
returns a pointer to the first occurrence of wide string ws2 in wide
string ws1, or a null pointer if ws2 does not occur in the wide string.
If ws2 points to a wide string of zero length, returns ws1.
considers the wide string ws1 to consist of a sequence of zero or more
text tokens separated by spans of one or more wide characters from the
separator wide string ws2. The first call (with a non-null pointer ws1
specified) returns a pointer to the first wide character of the first
token, and writes a null wide character into ws1 immediately following
the returned token. The function keeps track of its position in the
wide string ws1 between separate calls, so that subsequent calls made
with the first argument a null pointer work through the wide string
immediately following that token. In this way subsequent calls work
through the wide string ws1 until no tokens remain. The separator wide
string ws2 can be different from call to call. When no token remains
in ws1, a null pointer is returned.
The third argument is added for the environment. The third argument
ptr points to a caller-provided pointer into which stores information
necessary for it to continue scanning the same wide-character string.
returns an integer greater than, equal to, or less than zero, according
to whether the wide string pointed to by ws1 is greater than, equal to,
or less than the wide string pointed to by ws2. The comparison is
based on wide strings interpreted as appropriate to the program's
locale (see Locale below). In the "C" locale works like
returns the number of column positions required for the wide character
wc, or 0 if wc is a null wide character, or -1 if wc is an unprintable
wide character.
returns the number of column positions required for n wide characters
(or fewer than n wide characters if a null wide character is encoun‐
tered before n wide characters are exhausted) in the wide string
pointed to by ws. returns 0 if ws points to a null wide character.
returns -1 if ws contains an unprintable wide character, or if ws is a
NULL pointer; in either case errno is set.
transforms the wide character string pointed to by ws2 and places the
resulting wide character string into the array pointed to by ws1. The
transformation is such that if is applied to two transformed wide
strings, it returns a value greater than, equal to or less than 0, cor‐
responding to the result of applied to the same two original wide char‐
acter strings. No more than n wide-character codes are placed into the
resulting array pointed to by ws1 including the terminating null wide-
character. If n is 0, ws1 is permitted to be a null pointer. If copying
takes place between objects that overlap, the behavior is undefined.
returns the length of the transformed wide character string (not
including the terminating null wide-character code). If the value
returned is n or more, the contents of the array pointed to by ws1 are
indeterminate. On error, returns (size_t) -1, and sets to (if the wide
character string pointed to by ws2 contains wide-character codes out‐
side the domain of the collating sequence) or to (if the function is
not supported).
Definitions for these functions and the type are provided in header
file
Obsolescent Interface
performs wide character string operations.
APPLICATION USAGE
The "Unix Standards Only" prototypes are available to applications if
they are:
a. conformant.
b. Compiled with macro with a value >=500.
c. Compiled with macro with a value >= 200112.
To get the MSE behavior of the "Unix Standards Only" prototype of the
application MUST be compiled with the environment variable set to the
value 98 or above and exported.
EXTERNAL INFLUENCES
Environment Variables
The category determines the collation ordering used by the function.
The category determines how widths are calculated by the and functions.
ERRORS
fails if the following condition is encountered:
ws is NULL or if ws contains an unprintable wide
character.
fails under the following conditions:
ws2 points to a string containing wide character
codes outside the domain of the collating
sequence.
if the function
is not supported.
EXAMPLES
The following sample piece of code finds the tokens, separated by
blanks, that are in the string s (assuming that there are at most
tokens):
int i = 0;
wchar_t *ws, *wlast, *wtok[MAXTOK];
wtok[0] = wcstok_r(ws, L" ", &wlast);
while (wtok[++i] = wcstok_r(NULL, L" ", &wlast));
WARNINGS
The functions and alter the contents of the array to which ws1 points.
They do not check for overflow of the array.
Null pointers for destination wide strings cause undefined behavior.
Wide character movement is performed differently in different implemen‐
tations, so copying that involves overlapping source and destination
wide strings may yield unexpected results.
For the function, the results are undefined if the languages specified
by the and categories use different code sets.
is an obsolescent interface supported only for compatibility with
existing DCE applications. New multithreaded applications should use
will return an incorrect negative value if the number of column posi‐
tions required for n wide characters in the wide string pointed to by
ws exceeds
AUTHOR
functions were developed by OSF and HP.
SEE ALSOmemory(3C), multibyte(3C), setlocale(3C), string(3C), wconv(3C),
thread_safety(5), glossary(9).
STANDARDS CONFORMANCEwcstring(3C)