United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# strrchr

> Returns the address of the last occurrence of a given character in a null-terminated string. The terminating null character is considered to be part of the string.

## Format

> #include <string.h>

> char *strrchr (const char *str, int character);

Function Variants This function also has variants named `_strrchr32` and `_strrchr64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### str

> A pointer to a null-terminated character string.

> ### character

> An object of type `int` .

## Description

> See also `strchr` in this section.

## Return Values

> x | The address of the last occurrence of the specified character.
> NULL | Indicates that the character does not occur in the string.

# strsep

> Separates strings.

## Format

> #include <string.h>

> char *strsep (char **stringp, char *delim);

Function Variants This function also has variants named `_strsep32` and `_strsep64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### stringp

> A pointer to a pointer to a character string.

> ### delim

> A pointer to a string containing characters to be used as delimeters.

## Description

> This function locates in stringp, the first occurrence of any character in delim (or the terminating '\0' character) and replaces it with a '\0'. The location of the next character after the delimiter character (or NULL, if the end of the string is reached) is stored in the stringp argument. The original value of the stringp argument is returned.

> You can detect an "empty" field; one caused by two adjacent delimiter characters, by comparing the location referenced by the pointer returned in the stringp argument to '\0'.

> The stringp argument is initially NULL, `strsep` returns NULL.

## Return Values

> x | The address of the string pointed to by stringp.
> NULL | Indicates that stringp is NULL.

## Example

> The following example uses `strsep` to parse a string, containing token delimited by white space, into an argument vector:

>     char **ap, **argv[10], *inputstring;

>     for (ap = argv; (*ap = strsep(&inputstring, " \t")) != NULL;)
>          if (**ap != '\0')
>              ++ap;

# strspn

> Returns the length of the prefix of a string that consists entirely of characters from a set of characters.

## Format

> #include <string.h>

> size_t strspn (const char *str, const char *charset);

## Arguments

> ### str

> A pointer to a character string. If this string is a null string, 0 is returned.

> ### charset

> A pointer to a character string containing the characters for which the function will search.

## Description

> This function scans the characters in the string, stops when it encounters a character not found in charset, and returns the length of the string's initial segment formed by characters found in charset.

## Return Value

> x | The length of the segment.

# strstr

> Locates the first occurrence in the string pointed to by s1 of the sequence of characters in the string pointed to by s2.

## Format

> #include <string.h>

> char *strstr (const char *s1, const char *s2);

Function Variants This function also has variants named `_strstr32` and `_strstr64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### s1, s2

> Pointers to character strings.

## Return Values

> Pointer | A pointer to the located string.
> NULL | Indicates that the string was not found.

## Example

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

>     main()
>     {
>         static char lookin[]="that this is a test was at the end";

>         putchar('\n');
>         printf("String: %s\n", &lookin[0] );
>         putchar('\n');
>         printf("Addr: %s\n", &lookin[0] );
>         printf("this: %s\n", strstr( &lookin[0] ,"this") );
>         printf("that: %s\n", strstr( &lookin[0] , "that" ) );
>         printf("NULL: %s\n", strstr( &lookin[0], "" ) );
>         printf("was: %s\n", strstr( &lookin[0], "was" ) );
>         printf("at: %s\n", strstr( &lookin[0], "at" ) );
>         printf("the end: %s\n", strstr( &lookin[0], "the end") );
>         putchar('\n');

>         exit(0);
>     }

This example produces the following results:

    $ RUN STRSTR_EXAMPLE
    String: that this is a test was at the end
    Addr: that this is a test was at the end
    this: this is a test was at the end
    that: that this is a test was at the end
    NULL: that this is a test was at the end
    was: was at the end
    at: at this is a test was at the end
    the end: the end
    $

# strtod

> Converts a given string to a double-precision number.

## Format

> #include <stdlib.h>

> double strtod (const char *nptr, char **endptr);

Function Variants This function also has variants named `_strtod32` and `_strtod64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### nptr

> A pointer to the character string to be converted to a double-precision number.

> ### endptr

> The address of an object where the function can store the address of the first unrecognized character that terminates the scan. If endptr is a NULL pointer, the address of the first unrecognized character is not retained.

## Description

> This function recognizes an optional sequence of white-space characters (as defined by `isspace` ), then an optional plus or minus sign, then a sequence of digits optionally containing a radix character, then an optional letter (e or E) followed by an optionally signed integer. The first unrecognized character ends the conversion.

> The string is interpreted by the same rules used to interpret floating constants.

> The radix character is defined the program's current locale (category LC_NUMERIC).

> This function returns the converted value. For `strtod` , overflows are accounted for in the following manner:

> - If the correct value causes an overflow, HUGE_VAL (with a plus or minus sign according to the sign of the value) is returned and `errno` is set to ERANGE.
> - If the correct value causes an underflow, 0 is returned and `errno` is set to ERANGE.

> If the string starts with an unrecognized character, then the conversion is not performed, *endptr is set to nptr, a 0 value is returned, and `errno` is set to EINVAL.)

## Return Values

> x | The converted string.
> 0 | Indicates the conversion could not be performed. `errno` is set to one of the following: EINVAL - No conversion could be performed. ERANGE - The value would cause an underflow. ENOMEM - Not enough memory available for internal conversion buffer.
> (+/-)HUGE_VAL | Indicates overflow. `errno` is set to ERANGE.

# strtok

> Locates text tokens in a given string. The text tokens are delimited by one or more characters from a separator string that you specify. This function keeps track of its position in the string between calls and, as successive calls are made, the function works through the string, identifying the text token following the one identified by the previous call.

## Format

> #include <string.h>

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

Function Variants This function also has variants named `_strtok32` and `_strtok64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### s1

> On the first call, a pointer to a string containing 0 or more text tokens. On all subsequent calls for that string, a NULL pointer.

> ### s2

> A pointer to a separator string consisting of one or more characters. The separator string may differ from call to call.

## Description

> A token in s1 starts at the first character that is not a character in the separator string s2 and ends either at the end of the string or at (but not including) a separator character.

> The first call to the `strtok` function returns a pointer to the first character in the first token and writes a null character into s1 immediately following the returned token. Each subsequent call (with the value of the first argument remaining NULL) returns a pointer to a subsequent token in the string originally pointed to by s1. When no tokens remain in the string, the `strtok` function returns a NULL pointer. (This can occur on the first call to `strtok` if the string is empty or contains only separator characters.)

> Since `strtok` inserts null characters into s1 to delimit tokens, s1 cannot be a `const` object.

## Return Values

> x | A pointer to the first character of a token.
> NULL | Indicates that there are no tokens remaining in s1.

##

### Examples

#1
    #include <stdio.h>
    #include <string.h>

    main()
    {
        static char str[] = "...ab..cd,,ef.hi";

        printf("|%s|\n", strtok(str, "."));
        printf("|%s|\n", strtok(NULL, ","));
        printf("|%s|\n", strtok(NULL, ",."));
        printf("|%s|\n", strtok(NULL, ",."));
    }

> Running this example program produces the following results:

>     $ RUN STRTOK_EXAMPLE1
>     |ab|
>     |.cd|
>     |ef|
>     |hi|
>     $

#2
    #include <stdio.h>
    #include <string.h>

    main()
    {
       char *ptr,
            string[30];

       /* The first character not in the string "-" is "A".  The   */
       /* token ends at "C.                                        */

        strcpy(string, "ABC");
        ptr = strtok(string, "-");
        printf("|%s|\n", ptr);

        /* Returns NULL because no characters not in separator      */
        /* string "-" were found (i.e.  only separator characters   */
        /* were found)                                              */

        strcpy(string, "-");
        ptr = strtok(string, "-");
        if (ptr == NULL)
            printf("ptr is NULL\n");

    }

> Running this example program produces the following results:

>     $ RUN STRTOK_EXAMPLE2
>     |abc|
>     ptr is NULL
>     $

# strtol

> Converts strings of ASCII characters to the appropriate numeric values.

## Format

> #include <stdlib.h>

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

Function Variants This function also has variants named `_strtol32` and `_strtol64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### nptr

> A pointer to the character string to be converted to a `long` .

> ### endptr

> The address of an object where the function can store a pointer to the first unrecognized character encountered in the conversion process (that is, the character that follows the last character in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.

> ### base

> The value, 2 through 36, to use as the base for the conversion.

## Description

> This function recognizes strings in various formats, depending on the value of the base. This function ignores any leading white-space characters (as defined by `isspace` in `<ctype.h>` ) in the given string. It recognizes an optional plus or minus sign, then a sequence of digits or letters that may represent an integer constant according to the value of the base. The first unrecognized character ends the conversion.

> Leading zeros after the optional sign are ignored, and 0x or 0X is ignored if the base is 16.

> If base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant: after the optional sign, a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and any other combination of leading characters indicates decimal conversion.

> Truncation from `long` to `int` can take place after assignment or by an explicit cast (arithmetic exceptions not withstanding). The function call `atol (str)` is equivalent to `strtol (str, (char**)NULL, 10)` .

## Return Values

> x | The converted value.
> LONG_MAX or LONG_MIN | Indicates that the converted value would cause an overflow.
> 0 | Indicates that the string starts with an unrecognized character or that the value for base is invalid. If the string starts with an unrecognized character, * endptr is set to nptr.

# strtoq, strtoll (ALPHA ONLY)

> Converts strings of ASCII characters to the appropriate numeric values. `strtoll` is a synonym for `strtoq` .

## Format

> #include <stdlib.h>

> __int64 strtoq (const char *nptr, char **endptr, int base);

> __int64 strtoll (const char *nptr, char **endptr, int base);

Function Variants This function also has variants named `_strtoq32` / `_strtoll32` and `_strtoq64` / `_strtoll64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### nptr

> A pointer to the character string to be converted to an `__int64` .

> ### endptr

> The address of an object where the function can store a pointer to the first unrecognized character encountered in the conversion process (that is, the character that follows the last character in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.

> ### base

> The value, 2 through 36, to use as the base for the conversion.

## Description

> This function recognizes strings in various formats, depending on the value of the base. This function ignores any leading white-space characters (as defined by `isspace` in `<ctype.h>` ) in the given string. It recognizes an optional plus or minus sign, then a sequence of digits or letters that may represent an integer constant according to the value of the base. The first unrecognized character ends the conversion.

> Leading zeros after the optional sign are ignored, and 0x or 0X is ignored if the base is 16.

> If base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant: after the optional sign, a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and any other combination of leading characters indicates decimal conversion.

> The function call `atoq (str)` is equivalent to `strtoq (str, (char**)NULL, 10)` .

## Return Values

> x | The converted value.
> __INT64_MAX or __INT64_MIN | Indicates that the converted value would cause an overflow.
> 0 | Indicates that the string starts with an unrecognized character or that the value for base is invalid. If the string starts with an unrecognized character, * endptr is set to nptr.

# strtoul

> Converts the initial portion of the string pointed to by nptr to an `unsigned long` integer.

## Format

> #include <stdlib.h>

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

Function Variants This function also has variants named `_strtoul32` and `_strtoul64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### nptr

> A pointer to the character string to be converted to an `unsigned long` .

> ### endptr

> The address of an object where the function can store a pointer to a pointer to the first unrecognized character encountered in the conversion process (that is, the character that follows the last character in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.

> ### base

> The value, 2 through 36, to use as the base for the conversion. Leading zeros after the optional sign are ignored, and 0x or 0X is ignored if the base is 16.

> If the base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant: after the optional sign, a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and any other combination of leading characters indicates decimal conversion.

## Return Values

> x | The converted value.
> 0 | Indicates that the string starts with an unrecognized character or that the value for base is invalid. If the string starts with an unrecognized character, * endptr is set to nptr.
> ULONG_MAX | Indicates that the converted value would cause an overflow.

# strtouq, strtoull (ALPHA ONLY)

> Converts the initial portion of the string pointed to by nptr to an `unsigned __int64` integer. `strtoull` is a synonym for `strtouq` .

## Format

> #include <stdlib.h>

> unsigned __int64 strtouq (const char *nptr, char **endptr, int base);

> unsigned __int64 strtoull (const char *nptr, char **endptr, int base);

Function Variants This function also has variants named `_strtouq32` / `_strtoull32` and `_strtouq64` / `_strtoull64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### nptr

> A pointer to the character string to be converted to an `unsigned __int64` .

> ### endptr

> The address of an object where the function can store a pointer to a pointer to the first unrecognized character encountered in the conversion process (that is, the character that follows the last character in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.

> ### base

> The value, 2 through 36, to use as the base for the conversion. Leading zeros after the optional sign are ignored, and 0x or 0X is ignored if the base is 16.

> If the base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant: after the optional sign, a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and any other combination of leading characters indicates decimal conversion.

## Return Values

> x | The converted value.
> 0 | Indicates that the string starts with an unrecognized character or that the value for base is invalid. If the string starts with an unrecognized character, * endptr is set to nptr.
> __UINT64_MAX | Indicates that the converted value would cause an overflow.

Previous | Next | Contents | Index

privacy and legal statement