[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

strcat, strncat, strxfrm, strcpy, strncpy, or strdup Subroutine

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;

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

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

char * strdup (String1)
const char *String1;

Description

The strcat, strncat, strxfrm, strcpy, strncpy, and strdup 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 strcpy subroutine copies 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 strncpy subroutine copies 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.

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.

Parameters

Number Specifies the number of bytes in a string to be copied or transformed.
String1 Points to a string to which the specified data is copied or appended.
String2 Points to a string which contains the data to be copied, appended, or transformed.

Error Codes

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

EFAULT A string parameter is an invalid address.

In addition, the strxfrm subroutine fails if:

EINVAL A string parameter contains characters outside the domain of the collating sequence.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The memccpy, memchr, memcmp, memcpy, or memmove subroutine, setlocale subroutine, strcmp, strncmp, strcasecmp, strncasecmp, or strcoll subroutine, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, or strtok subroutine, swab subroutine.

National Language Support Overview for Programming, Understanding Multibyte and Wide Character String Collation Subroutines, Understanding Multibyte and Wide Character String Comparison Subroutines, Subroutines Overview, List of String Manipulation Services in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]