Watcom C Library : strtok, fstrtok, strtol, strtoul, strupr, _fstrupr, strxfrm, swab, system

 

 

Watcom C Library Reference : strtok, fstrtok, strtol, strtoul, strupr, _fstrupr, strxfrm, swab, system

 

 

 

 

strtok, fstrtok

 

Synopsis : #include <string.h> 

              char *strtok( char *s1, const char *s2 );

              char __far *_fstrtok( char __far *s1, const char __far *s2 );

 

Description : The strtok and _fstrtok functions are used to break the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2. The first call to strtok will return a pointer to the first token in the string pointed to by s1. Subsequent calls to strtok must pass a NULL pointer as the first argument, in order to get the next token in the string. The set of delimiters used in each of these calls to strtok can be different from one call to the next.

The first call in the sequence searches s1 for the first character that is not contained in the current delimiter string s2. If no such character is found, then there are no tokens in s1 and the strtok function returns a NULL pointer. If such a character is found, it is the start of the first token.

The strtok function then searches from there for a character that is contained in the current delimiter string. If no such character is found, the current token extends to the end of the string pointed to by s1. If such a character is found, it is overwritten by a null character, which terminates the current token. The strtok function saves a pointer to the following character, from which the next search for a token will start when the first argument is a NULL pointer.

Because strtok may modify the original string, that string should be duplicated if the string is to be re-used.

The _fstrtok function is a data model independent form of the strtok function. It accepts far pointer arguments and returns a far pointer. It is most useful in mixed memory model applications.

 

 

Returns : The strtok and _fstrtok functions return a pointer to the first character of a token or NULL if there is no token found.

 

 

See Also : strcspn, strpbrk

 

Example :

#include <stdio.h> 

#include <string.h>

void main( )

{
    char     *p;

    char     *buffer;

    char     *delims = { " .," };

    buffer = strdup( "Find words, all of them." );

    printf( "%s\n", buffer );

    p = strtok( buffer, delims );

 

    while( p != NULL) {
        printf( "word: %s\n", p );

        p = strtok( NULL, delims );

    }
    printf( "%s\n", buffer );

}

 

produces the following :
Find words, all of them. 

word: Find 

word: words 

word: all 

word: of 

word: them 

Find

 

Classification : strtok is ANSI, _fstrtok is not ANSI
Systems : strtok - All

             _fstrtok - All

 

 

 

 

 

 

 

strtol

 

Synopsis : #include <stdlib.h> 

              long int strtol( const char *ptr, char **endptr, int base );

 

Description : The strtol function converts the string pointed to by ptr to an object of type long int. The function recognizes a string containing:

• optional white space.

• an optional plus or minus sign.

• a sequence of digits and letters.

The conversion ends at the first unrecognized character. A pointer to that character will be stored in the object to which endptr points if endptr is not NULL.

 

If base is zero, the first characters after the optional sign determine the base used for the conversion. If the first characters are "0x" or "0X" the digits are treated as hexadecimal. If the first character is '0', the digits are treated as octal. Otherwise the digits are treated as decimal.

If base is not zero, it must have a value between 2 and 36. The letters a-z and A-Z represent the values 10 through 35. Only those letters whose designated values are less than base are permitted. If the value of base is 16, the characters "0x" or "0X" may optionally precede the sequence of letters and digits.

 

 

Returns : The strtol function returns the converted value. If the correct value would cause overflow, LONG_MAX or LONG_MIN is returned according to the sign, and errno is set to ERANGE. If base is out of range, zero is returned and errno is set to EDOM.

 

 

See Also : ltoa, strtoul

 

Example :

#include <stdlib.h>

void main( )

{
    long int v;

    v = strtol( "12345678", NULL, 10 );

}

 

Classification : ANSI
Systems : All

 

 

 

 

 

 

 

strtoul

 

Synopsis : #include <stdlib.h> 

              unsigned long int strtoul( const char *ptr, char **endptr, int base );

 

Description : The strtoul function converts the string pointed to by ptr to an unsigned long. The function recognizes a string containing optional white space, followed by a sequence of digits and letters. The conversion ends at the first unrecognized character. A pointer to that character will be stored in the object endptr points to if endptr is not NULL.


If base is zero, the first characters determine the base used for the conversion. If the first characters are "0x" or "0X" the digits are treated as hexadecimal. If the first character is '0', the digits are treated as octal. Otherwise the digits are treated as decimal.

If base is not zero, it must have a value of between 2 and 36. The letters a-z and A-Z represent the values 10 through 35. Only those letters whose designated values are less than base are permitted. If the value of base is 16, the characters "0x" or "0X" may optionally precede the sequence of letters and digits.

 

 

Returns : The strtoul function returns the converted value. If the correct value would cause overflow, ULONG_MAX is returned and errno is set to ERANGE. If base is out of range, zero is returned and errno is set to EDOM.

 

 

See Also : ltoa, strtol, ultoa

 

Example :

#include <stdlib.h>

void main( )

{
    unsigned long int v;

    v = strtoul( "12345678", NULL, 10 );

}

 

Classification : ANSI
Systems : All

 

 

 

 

 

 

 

strupr, _fstrupr

 

Synopsis : #include <string.h> 

              char *strupr( char *s1 );

              char __far *_fstrupr( char __far *s1 );

 

Description : The strupr and _fstrupr functions replace the string s1 with uppercase characters by invoking the toupper function for each character in the string.

The _fstrupr function is a data model independent form of the strupr function. It accepts far pointer arguments and returns a far pointer. It is most useful in mixed memory model applications.

 

 

Returns : The address of the original string s1 is returned.

 

 

See Also : strlwr

 

Example :

#include <stdio.h> 

#include <string.h>

char source[] = { "A mixed-case STRING" };

void main( )

{
    printf( "%s\n", source );

    printf( "%s\n", strupr( source ) );

    printf( "%s\n", source );

}

 

produces the following :
A mixed-case STRING 

A MIXED-CASE STRING 

A MIXED-CASE STRING

 

Classification : WATCOM
Systems : strupr - All

             _fstrupr - All

 

 

 

 

 

 

 

strxfrm

 

Synopsis : #include <string.h> 

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

 

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 the setlocale function so that two transformed strings will compare identically (using the strncmp function) to a comparison of the original two strings using the strcoll function.

 

The function will be equivalent to the strncpy function (except there is no padding of the dst argument with null characters when the argument src is shorter than n characters) when the collating sequence is selected from the "C" locale.

 

 

Returns : The strxfrm function returns the length of the transformed string. If this length is more than n, the  ontents of the array pointed to by dst are indeterminate.

 

 

See Also : setlocale, strcoll

 

Example :

#include <stdio.h> 

#include <string.h> 

#include <locale.h>

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

char     dst[20];

void main( )

{
    size_t    len;

    setlocale( LC_ALL, "C" );

    printf( "%s\n", src );

    len = strxfrm( dst, src, 20 );

    printf( "%s (%u) \n", dst, len );

}

 

produces the following :
A sample STRING 

A sample STRING (15)

 

Classification : ANSI
Systems : All

 

 

 

 

 

 

 

 

 

swab

 

Synopsis : #include <stdlib.h> 

              void swab( char *src, char *dest, int num );

 

Description : The swab function copies num bytes (which should be even) from src to dest swapping every pair of characters. This is useful for preparing binary data to be transferred to another machine that has a different byte ordering.

 

 

Returns : The swab function has no return value.

 

 

Example :

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h>

char *msg = "hTsim seasegi swspaep.d"; 

#define NBYTES 24

void main( )

{
    auto char buffer[80];

    printf( "%s\n", msg );

    memset( buffer, '\0', 80 );

    swab( msg, buffer, NBYTES );

    printf( "%s\n", buffer );

}

 

produces the following :
hTsim seasegi swspaep.d 

This message is swapped.

 

Classification : WATCOM
Systems : All

 

 

 

 

 

 

 

 

 

system

 

Synopsis : #include <stdlib.h> 

              int system( const char *command );

 

Description : If the value of command is NULL, then the system function determines whether or not a command processor is present (COMMAND.COM in DOS or CMD.EXE in OS/2).

Otherwise, the system function invokes a copy of the command processor, and passes the string command to it for processing. This function uses spawnl to load a copy of the command processor identified by the COMSPEC environment variable.

This means that any command that can be entered to DOS can be executed, including programs, DOS commands and batch files. The exec... and spawn... functions can only cause programs to be executed.

 

 

Returns : If the value of command is NULL, then the system function returns zero if the command processor is not present, a non-zero value if the command processor is present.

Otherwise, the system function returns the result of invoking a copy of the command processor. A non-zero value is returned if the command processor could not be loaded; otherwise, zero is returned. When an error has occurred, errno contains a value indicating the type of error that has been detected.

 

 

See Also : abort, atexit, _bget cmd, exec Functions, exit, _exit, getcmd, getenv, main, onexit, putenv, spawn Functions

 

Example :

#include <stdlib.h> 

#include <stdio.h>

void main( )

{
    int     rc;
   

    rc = system( "dir" );

    if( rc != 0 ) {
        printf( "shell could not be run\n" );

    }

}

 

Classification : ANSI, POSIX 1003.2
Systems : All

 

 

 

 

 

 

 

 

This manual describes the WATCOM C library for DOS, Windows, and OS/2, It includes the Standard C Library (as defined in the ANSI C Standard).

 

WATCOM C Language Reference manual describes the ANSI C Programming language and extensions to it which are supported by WATCOM C/C++ (32bit)