strcat, strncat, strxfrm, strxfrm_l, strcpy, strncpy, stpcpy, stpncpy, strdup or strndup Subroutines

Purpose

Copies and appends strings in memory.

Library

Standard C Library (libc.a)

Syntax

#include <string.h>

char * strcat ( String1,  String2) char *String1;  const char *String2;

char * strncat (String1, String2,  Number) char *String1; const char *String2; size_t Number;

size_t  strxfrm (String1, String2, Number) char *String1;  const char *String2; size_t Number;

size_t strxfrm_l (String1, String2, Number,Locale) char *String1; const char *String2; size_t Number; locale_t Locale;

char * strcpy (String1, String2) char *String1; const char *String2;

char * strncpy (String1, String2, Number) char *String1;  const char *String2; size_t Number;

char * stpcpy (String1, String2) char *String1; const char *String2;

char * stpncpy (String1, String2, size) char *String1; const char *String2; size_t size;

char * strdup (String1) const char *String1;

char * strndup (String1, size) const char *String1; size_t size;

Description

The strcat, strncat, strxfrm, strcpy, strxfrm_l, strncpy, stpcpy, stpncpy, strdup, and strndup subroutines copy and append strings in memory.

The String1 and String2 parameters point to strings. A string is an array of characters terminated by a null character. The strcat, strncat, strcpy, and strncpy subroutines all alter the string in the String1 parameter. However, they do not check for overflow of the array to which the String1 parameter points. String movement is performed on a character-by-character basis and starts at the left. Overlapping moves toward the left work as expected, but overlapping moves to the right may give unexpected results. All of these subroutines are declared in the string.h file.

The strcat subroutine adds a copy of the string pointed to by the String2 parameter to the end of the string pointed to by the String1 parameter. The strcat subroutine returns a pointer to the null-terminated result.

The strncat subroutine copies a number of bytes specified by the Number parameter from the String2 parameter to the end of the string pointed to by the String1 parameter. The subroutine stops copying before the end of the number of bytes specified by the Number parameter if it encounters a null character in the String2 parameter's string. The strncat subroutine returns a pointer to the null-terminated result. The strncat subroutine returns the value of the String1 parameter.

The strxfrm subroutine transforms the string pointed to by the String2 parameter and places it in the array pointed to by the String1 parameter. The strxfrm subroutine transforms the entire string if possible, but places no more than the number of bytes specified by the Number parameter in the array pointed to by the String1 parameter. Consequently, if the Number parameter has a value of 0, the String1 parameter can be a null pointer. The strxfrm subroutine returns the length of the transformed string, not including the terminating null byte. If the returned value is equal to or more than that of the Number parameter, the contents of the array pointed to by the String1 parameter are indeterminable. If the number of bytes specified by the Number parameter is 0, the strxfrm subroutine returns the length required to store the transformed string, not including the terminating null byte. The strxfrm subroutine is determined by the LC_COLLATE category.

The strxfrm_l() function is equivalent to the strxfrm() function, except that the locale data used is from the locale represented by Locale.

The strcpy and stpcpy subroutines copy the string pointed to by the String2 parameter to the character array pointed to by the String1 parameter. Copying stops after the null character is copied. The strcpy subroutine returns the value of the String1 parameter, if successful. Otherwise, a null pointer is returned.

The stpcpy subroutines returns a pointer to the terminating NULL character copied into the String1 parameter, if successful. Otherwise, a null pointer is returned.

The strncpy and stpncpy subroutines copy the number of bytes specified by the Number parameter from the string pointed to by the String2 parameter to the character array pointed to by the String1 parameter. If the String2 parameter value is less than the specified number of characters, then the strncpy subroutine pads the String1 parameter with trailing null characters to a number of bytes equaling the value of the Number parameter. If the String2 parameter is exactly the specified number of characters or more, then only the number of characters specified by the Number parameter are copied and the result is not terminated with a null byte. The strncpy subroutine returns the value of the String1 parameter.

If a null character is written to the destination, the stpncpy function returns the address of the first such null character. Otherwise, it returns &String1[Number].

The strdup subroutine returns a pointer to a new string, which is a duplicate of the string pointed to by the String1 parameter. Space for the new string is obtained by using the malloc subroutine. A null pointer is returned if the new string cannot be created.

The strndup subroutine is equivalent to the strdup subroutine, except that it copies at most size plus one byte into the newly allocated memory, terminating the new string with a null character. If the length of String1 is larger than size, only size bytes is duplicated. If size is larger than the length of String1, all bytes in String1 shall be copied into the new memory buffer, including the terminating NULL character

Parameters

Error Codes

The strcat, strncat, strxfrm, strxfrm_l, strcpy, strncpy, stpcpy, stpncpy,strdup, and strndup subroutines fail if the following occurs:

In addition, the strxfrm, and strxfrm_l subroutine fails if:

The strdup and strndup functions fails if: