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); 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 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). SEE ALSO malloc(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