NAME

wcscat, wcscmp, wcscpy - Perform operations on wide-character strings

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <wchar.h>

wchar_t ∗wcscat(
wchar_t ∗wcstring1,
const wchar_t ∗wcstring2);

int wcscmp(
const wchar_t ∗wcstring1,
const wchar_t ∗wcstring2);

wchar_t ∗wcscpy(
wchar_t ∗wcstring1,
const wchar_t ∗wcstring2);

PARAMETERS

wcstring1Points to a location containing the first wide-character string. 

wcstring2Points to a location containing the second wide-character string. 

DESCRIPTION

The wcscat(), wcscmp(), and wcscpy() functions operate on null-terminated, wide-character strings. The string arguments to these functions are expected to contain a null wide character marking the end of the string. Boundary checking is not done when a copy or concatenation operation is performed. 

The wcscat() function appends a copy of the wide-character string pointed to by the wcstring2 parameter (including the terminating null wide-character code) to the end of the wide-character string pointed to by the wcstring1 parameter.  The initial wide-character code of wcstring2 overwrites the null wide-character code at the end of wcstring1. 

The wcscmp() function compares two wchar_t strings.  The wcscmp() function compares wide characters until it finds two wide characters that are not equal or until it has reached a terminating null wide character. 

The wcscmp() function compares strings based on the machine collating order. It does not use the locale-dependent sorting order.  Use the wcscoll() function for locale-dependent sorting. 

The wcscpy() function copies the contents of the wcstring2 parameter (including the ending wchar_t null character) into the wcstring1 parameter. If copying occurs between overlapping objects, the behavior of the wcscpy() function is undefined. 

RETURN VALUES

Upon successful completion, the wcscat() and wcscpy() functions return a pointer to the resulting string, wcstring1.  Otherwise, these functions return a null pointer. 

Upon successful completion, the wcscmp() function returns an integer whose value is greater than 0 (zero) if wcstring1 is greater than wcstring2, returns 0 (zero) if the strings are equivalent, and returns an integer whose value is less than 0 (zero) if wcstring1 is less than wcstring2.  When a successful comparison cannot be made, these functions return a value of 0 (zero).  The sign of a nonzero return value is determined by the sign of the difference between the values of the first pair of wide-character codes that differ in the objects being compared. 

RELATED INFORMATION

Functions: string(3)/strcat(3)/strcmp(3)/strcpy(3), wcschr(3), wcscoll(3), wcsncat(3), wcsspn(3).