strxfrm()

Transform one string into another, to a given length

Synopsis:

#include <string.h>

size_t strxfrm( char* dst,
                const char* src,
                size_t n );

Arguments:

dst: The string that you want to transform.
src: The string that you want to place in dst.
n: The maximum number of characters to transform.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The strxfrm() function transforms, for no more than n characters, the string pointed to by src to the buffer pointed to by dst. The transformation uses the collating sequence selected by setlocale() so that two transformed strings compare identically (using the strncmp() function) to a comparison of the original two strings using strcoll().

If the collating sequence is selected from the "C" locale, strxfrm() is equivalent to strncpy(), except that strxfrm() doesn't pad the dst argument with null characters when the argument src is shorter than n characters.

Returns:

The length of the transformed string. If this length is more than n, the contents of the array pointed to by dst are indeterminate.

Note: If an error occurs, strxfrm() sets errno and returns 0. Since the function could also return zero on success, the only way to tell that an error has occurred is to set errno to 0 before calling strxfrm() and check errno afterward.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <locale.h>

char src[] = { "A sample STRING" };
char dst[20];

int main( void )
  {
    size_t len;

    setlocale( LC_ALL, "C" );
    printf( "%s\n", src );
    len = strxfrm( dst, src, 20 );
    printf( "%s (%u)\n", dst, len );
    return EXIT_SUCCESS;
  }

produces the output:

A sample STRING
A sample STRING (15)

Classification:

ANSI, POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	Yes
Signal handler	Yes
Thread	Yes