United States    
COMPAQ STORE | PRODUCTS |
SERVICES | SUPPORT | CONTACT US | SEARCH
Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


#include <stdlib.h> 
#include <stdio.h> 
#include <time.h> 
#include <locale.h> 
#include <errno.h> 
 
#define NUM_OF_DATES  7 
#define BUF_SIZE 256 
 
/* This program formats a number of different dates, once using  */ 
/* the C locale and then using the fr_FR.ISO8859-1 locale.  Date */ 
/* and time formatting is done using strftime().                 */ 
 
main() 
{ 
    int count, 
        i; 
    char buffer[BUF_SIZE]; 
    struct tm *tm_ptr; 
    time_t time_list[NUM_OF_DATES] = 
    {500, 68200000, 694223999, 694224000, 
     704900000, 705000000, 705900000}; 
 
    /* Display dates using the C locale */ 
    printf("\nUsing the C locale:\n\n"); 
 
    setlocale(LC_ALL, "C"); 
 
    for (i = 0; i < NUM_OF_DATES; i++) { 
        /* Convert to a tm structure */ 
        tm_ptr = localtime(&time_list[i]); 
 
        /* Format the date and time */ 
        count = strftime(buffer, BUF_SIZE, 
                         "Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr); 
        if (count == 0) { 
            perror("strftime"); 
            exit(EXIT_FAILURE); 
        } 
 
        /* Print the result */ 
       printf(buffer); 
    } 
 
    /* Display dates using the fr_FR.ISO8859-1 locale */ 
    printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n"); 
 
    setlocale(LC_ALL, "fr_FR.ISO8859-1"); 
 
    for (i = 0; i < NUM_OF_DATES; i++) { 
        /* Convert to a tm structure */ 
        tm_ptr = localtime(&time_list[i]); 
 
        /* Format the date and time */ 
        count = strftime(buffer, BUF_SIZE, 
                         "Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr); 
        if (count == 0) { 
            perror("strftime"); 
            exit(EXIT_FAILURE); 
        } 
 
        /* Print the result */ 
        printf(buffer); 
    } 
} 

Running the example program produces the following result:


Using the C locale: 
 
Date: Thursday 01 January 1970 
Time: 00:08:20 
 
Date: Tuesday 29 February 1972 
Time: 08:26:40 
 
Date: Tuesday 31 December 1991 
Time: 23:59:59 
 
Date: Wednesday 01 January 1992 
Time: 00:00:00 
 
Date: Sunday 03 May 1992 
Time: 13:33:20 
 
Date: Monday 04 May 1992 
Time: 17:20:00 
 
Date: Friday 15 May 1992 
Time: 03:20:00 
 
 
Using the fr_FR.ISO8859-1 locale: 
 
Date: jeudi 01 janvier 1970 
Time: 00:08:20 
 
Date: mardi 29 février 1972 
Time: 08:26:40 
 
Date: mardi 31 décembre 1991 
Time: 23:59:59 
 
Date: mercredi 01 janvier 1992 
Time: 00:00:00 
 
Date: dimanche 03 mai 1992 
Time: 13:33:20 
 
Date: lundi 04 mai 1992 
Time: 17:20:00 
 
Date: vendredi 15 mai 1992 
Time: 03:20:00 


strlen

Returns the length of a string of ASCII characters. The returned length does not include the terminating null character (\0).

Format

#include <string.h>

size_t strlen (const char *str);


Argument

str

A pointer to the character string.

Return Value

x The length of the string.

strncasecmp

Does a case-insensitive comparison between two 7-bit ASCII strings.

Format

#include <strings.h>

int strncasecmp (const char *s1, const char *s2, size_t n);


Arguments

s1

The first of two strings to compare.

s2

The second of two strings to compare.

n

The maximum number of bytes in a string to compare.

Description

This function is case-insensitive. The returned lexicographic difference reflects a conversion to lowercase. The strncasecmp function is similar to the strcasecmp function, but also compares size. If the size specified by n is read before a NULL, the comparison stops.

The strcasecmp function works for 7-bit ASCII compares only. Do not use this function for internationalized applications.


Return Values

n An integer value greater than, equal to, or less than 0 (zero), depending on whether s1 is greater than, equal to, or less than s2.

strncat

Appends not more than maxchar characters from str_2 to the end of str_1.

Format

#include <string.h>

char *strncat (char *str_1, const char *str_2, size_t maxchar);

Function Variants This function also has variants named _strncat32 and _strncat64 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_1, str_2

Pointers to null-terminated character strings.

maxchar

The number of characters to concatenate from str_2, unless strncat first encounters a null terminator in str_2. If maxchar is 0, no characters are copied from str_2.

Description

A null character is always appended to the result of the strncat function. If strncat reaches the specified maximum, it sets the next byte in str_1 to the null character.

Return Value

x The address of the first argument, str_1, which is assumed to be large enough to hold the concatenated result.

strncmp

Compares not more than maxchar characters of two ASCII character strings and returns a negative, 0, or positive integer, indicating that the ASCII values of the individual characters in the first string are less than, equal to, or greater than the values in the second string.

Format

#include <string.h>

int strncmp (const char *str_1, const char *str_2, size_t maxchar);


Arguments

str_1, str_2

Pointers to character strings.

maxchar

The maximum number of characters (beginning with the first) to search in both str_1 and str_2. If maxchar is 0, no comparison is performed and 0 is returned (the strings are considered equal).

Description

This function compares no more than maxchar characters from the string pointed to by str_1 to the string pointed to by str_2. The strings are compared until a null character is encountered, the strings differ, or maxchar is reached. Characters that follow a difference or a null character are not compared.

Return Values

< 0 Indicates that str_1 is less than str_2.
= 0 Indicates that str_1 equals str_2.
> 0 Indicates that str_1 is greater than str_2.

Examples

#1

#include <string.h> 
#include <stdio.h> 
 
main() 
{ 
    printf( "%d\n", strncmp("abcde", "abc", 3)); 
} 
 
      

When linked and executed, this example returns 0, because the first 3 characters of the 2 strings are equal:


$ run tmp 
0 

#2

#include <string.h> 
#include <stdio.h> 
 
    main() 
    { 
        printf( "%d\n", strncmp("abcde", "abc", 4)); 
    } 
 
      

When linked and executed, this example returns a value greater than 0 because the first 4 characters of the 2 strings are not equal (The "d" in the first string is not equal to the null character in the second):


$ run tmp 
        100 


strncpy

Copies not more than maxchar characters from str_2 into str_1.

Format

#include <string.h>

char *strncpy (char *str_1, const char *str_2, size_t maxchar);

Function Variants This function also has variants named _strncpy32 and _strncpy64 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_1, str_2

Pointers to character strings.

maxchar

The maximum number of characters to copy from str_2 to str_1 up to but not including the null terminator of str_2.

Description

This function copies no more than maxchar characters from str_2 to str_1, up to but not including the null terminator of str_2. If str_2 contains less than maxchar characters, str_1 is padded with null characters. If str_2 contains greater than or equal to maxchar characters, as many characters as possible are copied to str_1. Be aware that the str_1 argument might not be terminated by a null character after a call to strncpy .

Return Value

x The address of str_1.

strnlen

Returns the number of bytes in a string.

Format

#include <string.h>

size_t strnlen (const char *s, size_t n);


Arguments

s

Pointer to the string.

n

The maximum number of characters to examine.

Description

This function returns the number of bytes in the string pointed to by s. The string length value does not include the terminating null character. The strnlen function counts bytes until the first null byte or until n bytes have been examined.

Return Values

n The length of the string.

strpbrk

Searches a string for the occurrence of one of a specified set of characters.

Format

#include <string.h>

char *strpbrk (const char *str, const char *charset);

Function Variants This function also has variants named _strpbrk32 and _strpbrk64 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 character string. If this character string is a null string, 0 is returned.

charset

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

Description

This function scans the characters in the string, stops when it encounters a character found in charset, and returns the address of the first character in the string that appears in the character set.

Return Values

x The address of the first character in the string that is in the set.
NULL Indicates that no character is in the set.

strptime

Converts a character string into date and time values that are stored in a tm structure. Conversion is controlled by a format string.

Format

#include <time.h>

char *strptime (const char *buf, const char *format, struct tm *timeptr);

Function Variants This function also has variants named _strptime32 and _strptime64 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

buf

A pointer to the character string to convert.

format

A pointer to the string that defines how the input string is converted.

timeptr

A pointer to the local time structure. The tm structure is defined in the <time.h> header file.

Description

This function converts the string pointed to by buf into values that are stored in the structure pointed to by timeptr. The string pointed to by format defines how the conversion is performed.

The strptime function modifies only those fields in the tm structure that have corresponding conversion specifications in the format. In particular, strptime never sets the tm_isdst member of the tm structure.

The format string consists of zero or more directives. A directive is composed of one of the following:

The strptime function uses fields in the LC_TIME category of the program's current locale to provide a value.

Table REF-9 strptime Conversion Specifications
Specification Replaced by
%a The weekday name. This is either the abbreviated or the full name.
%A Same as %a
%b The month name. This is either the abbreviated or the full name.
%B Same as %b.
%c The date and time using the locale's date format
%Ec The locale's alternative date and time representation
%C The century number (the year divided by 100 and truncated to an integer) as a decimal number (00 -- 99). Leading zeros are permitted.
%EC The name of the base year (period) in the locale's alternative representation
%d The day of the month as a decimal number (01 -- 31). Leading zeros are permitted.
%Od The day of the month using the locale's alternative numeric symbols
%D Same as %m/%d/%y
%e Same as %d
%Oe The date of the month using the locale's alternative numeric symbols
%h Same as %b
%H The hour (24-hour clock) as a decimal number (00 -- 23). Leading zeros are permitted.
%OH The hour (24-hour clock) using the locale's alternative numeric symbols
%I The hour (12-hour clock) as a decimal number (01 -- 12). Leading zeros are permitted.
%OI The hour (12-hour clock) using the locale's alternative numeric symbols
%j The day of the year as a decimal number (001 -- 366)
%m The month as a decimal number (01 -- 12). Leading zeros are permitted.
%Om The month using the locale's alternative numeric symbols
%M The minute as a decimal number (00 -- 59). Leading zeros are permitted.
%OM The minutes using the locale's alternative numeric symbols
%n Any whitespace character
%p The locale's equivalent of the AM/PM designations associated with a 12-hour clock
%r The time in AM/PM notation (%I:%M:%S %p)
%R The time in 24-hour notation (%H:%M)
%S The second as a decimal number (00 -- 61). Leading zeros are permitted.
%OS The seconds using the locale's alternative numeric symbols
%t Any whitespace character
%T The time (%H:%M:%S)
%U The week number of the year (the first Sunday as the first day of week 1) as a decimal number (00 -- 53). Leading zeros are permitted.
%OU The week number of the year (Sunday as the first day of the week) using the locale's alternative numeric symbols
%w The weekday as a decimal number (0 [Sunday] -- 6). Leading zeros are permitted.
%Ow The weekday as a number (Sunday=0) using the locale's alternative numeric symbols
%W The week number of the year (the first Monday as the first day of week 1) as a decimal number (00 -- 53). Leading zeros are permitted.
%OW The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols
%x The locale's appropriate date representation
%Ex The locale's alternative date representation
%EX The locale's alternative time representation
%X The locale's appropriate time representation
%y The year without century as a decimal number (00 -- 99)
%Ey The offset from the base year (%EC) in the locale's alternative representation
%Oy The year without the century using the locale's alternative numeric symbols
%Y The year with century as a decimal number
%EY The locale's full alternative year representation
%% %


Return Values

x A pointer to the character following the last character parsed.
NULL Indicates that an error occurred. The contents of the tm structure are undefined.

Example


#include <string.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <time.h> 
#include <locale.h> 
#include <errno.h> 
 
#define NUM_OF_DATES  7 
#define BUF_SIZE 256 
 
/* This program takes a number of date and time strings and     */ 
/* converts them into tm structs using strptime().  These tm    */ 
/* structs are then passed to strftime() which will reverse the */ 
/* process.  The resulting strings are then compared with the   */ 
/* originals and if a difference is found then an error is      */ 
/* displayed.                                                   */ 
 
main() 
{ 
    int count, 
        i; 
    char buffer[BUF_SIZE]; 
    char *ret_val; 
    struct tm time_struct; 
    char dates[NUM_OF_DATES][BUF_SIZE] = 
    { 
        "Thursday 01 January 1970 00:08:20", 
        "Tuesday 29 February 1972 08:26:40", 
        "Tuesday 31 December 1991 23:59:59", 
        "Wednesday 01 January 1992 00:00:00", 
        "Sunday 03 May 1992 13:33:20", 
        "Monday 04 May 1992 17:20:00", 
        "Friday 15 May 1992 03:20:00"}; 
 
    for (i = 0; i < NUM_OF_DATES; i++) { 
        /* Convert to a tm structure */ 
        ret_val = strptime(dates[i], "%A %d %B %Y %T", &time_struct); 
 
        /* Check the return value */ 
        if (ret_val == (char *) NULL) { 
            perror("strptime"); 
            exit(EXIT_FAILURE); 
        } 
 
        /* Convert the time structure back to a formatted string */ 
        count = strftime(buffer, BUF_SIZE, "%A %d %B %Y %T", 
                          &time_struct); 
 
        /* Check the return value */ 
        if (count == 0) { 
            perror("strftime"); 
            exit(EXIT_FAILURE); 
        } 
 
        /* Check the result */ 
        if (strcmp(buffer, dates[i]) != 0) { 
            printf("Error: Converted string differs from the original\n"); 
        } 
        else { 
            printf("Successfully converted <%s>\n", dates[i]); 
        } 
    } 
} 

Running the example program produces the following result:


Successfully converted <Thursday 01 January 1970 00:08:20> 
Successfully converted <Tuesday 29 February 1972 08:26:40> 
Successfully converted <Tuesday 31 December 1991 23:59:59> 
Successfully converted <Wednesday 01 January 1992 00:00:00> 
Successfully converted <Sunday 03 May 1992 13:33:20> 
Successfully converted <Monday 04 May 1992 17:20:00> 
Successfully converted <Friday 15 May 1992 03:20:00> 


Previous Next Contents Index
  

1.800.AT.COMPAQ

privacy and legal statement