wcstring(3C) wcstring(3C)
NAME
wcscat(), wcsncat(), wcscmp(), wcsncmp(), wcscpy(), wcsncpy(), wcslen(), wcschr(), wcsrchr(), wcsstr(), wcspbrk(), wcsspn(), wcscspn(),
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 charac-
ters. 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 char-
acter 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 equality).
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 structure. If that structure contains sizeof(wchar_t) consecutive null
bytes, may not copy the entire structure. Use the function (see memory(3C)) to copy arbitrary binary data.
returns the number of wide characters in ws, not including the terminating 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 considered 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-char-
acter 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 sepa-
rator 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 unprint-
able 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,
corresponding to the result of applied to the same two original wide character 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
outside 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 implementations, 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 positions required for n wide characters in the wide string pointed to by
ws exceeds
AUTHOR
functions were developed by OSF and HP.
SEE ALSO
memory(3C), multibyte(3C), setlocale(3C), string(3C), wconv(3C), thread_safety(5), glossary(9).
STANDARDS CONFORMANCE
wcstring(3C)