United States    
COMPAQ
Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index

11.5 Sample Date/Time Scenario

The following example and explanation shows how to use the Compaq C RTL time functions to print the current time:


#include <stdio.h> 
#include <time.h> 
 
main () 
{ 
  time_t t; 
 
  t = time((time_t)0); 
  printf ("The current time is: %s\n",asctime (localtime (&t))); 
}  

This example:

  1. Calls the time function to get the current time in seconds since the Epoch, in terms of UTC.
  2. Passes this value to the localtime function, which uses time-conversion information as specified by tzset to determine which time-zone conversion rules should be used to compute local time from UTC. By default, these rules are specified in the file defined by SYS$LOCALTIME:
    1. For a user in the Eastern United States interested in their local time, SYS$LOCALTIME would be defined during installation to SYS$COMMON:[SYS$ZONEINFO.US]EASTERN, the time-zone file containing conversion rules for the Eastern U.S. time zone..
    2. If the local time falls during daylight savings time (DST), SYS$COMMON:[SYS$ZONEINFO.US]EASTERN indicates that a time differential factor of -4 hours needs to be applied to UTC to get local time.
      If the local time falls during Eastern standard time (EST), SYS$COMMON:[SYS$ZONEINFO.US]EASTERN indicates that a time differential factor of -5 hours needs to be applied to UTC to get local time.
    3. The Compaq C RTL applies -4 (DST) or -5 (EST) to UTC, and localtime returns the local time in terms of a tm structure.
  3. Pass this tm structure to the asctime function to print the local time in a readable format.


Reference Section

This section alphabetically describes the functions contained in the Compaq C Run-Time Library (RTL).


abort

Sends the signal SIGABRT that terminates execution of the program.

Format

#include <stdlib.h>

void abort (void);


abs

Returns the absolute value of an integer.

Format

#include <stdlib.h>

int abs (int x);


Argument

x

An integer.

Return Value

x The absolute value of the input argument. If the argument is LONG_MIN, abs returns LONG_MIN because --LONG_MIN cannot fit in an int variable.

access

Checks a file to see whether a specified access mode is allowed. This function only checks UIC protection; ACLs are not checked.

Note

The access function does not accept network files as arguments.

Format

#include <unistd.h>

int access (const char *file_spec, int mode);


Arguments

file_spec

A character string that gives an OpenVMS or UNIX style file specification. The usual defaults and logical name translations are applied to the file specification.

mode

Interpreted as shown in Table REF-1.

Table REF-1 Interpretation of the mode Argument
Mode Argument Access Mode
F_OK Tests to see if the file exists
X_OK Execute
W_OK Write (implies delete access)
R_OK Read

Combinations of access modes are indicated by ORing the values. For example, to check to see if a file has RWED access mode, invoke access as follows:


access (file_spec, R_OK | W_OK | X_OK); 


Return Values

0 Indicates that the access is allowed.
--1 Indicates that the access is not allowed.

Example


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
 
main() 
{ 
    if (access("sys$login:login.com", F_OK)) { 
        perror("ACCESS - FAILED"); 
        exit(2); 
    } 
} 


acos

Returns a value in the range 0 to Pi sign, which is the arc cosine of its radian argument.

Format

#include <math.h>

double acos (double x);


Argument

x

A radian expressed as a real value.

Description

When abs (x) is greater than 1.0, the value of acos (x) is 0 and the acos function sets errno to EDOM.

[w]addch

Add a character to the window at the current position of the cursor.

Format

#include <curses.h>

int addch (char ch);

int waddch (WINDOW *win, char ch);


Arguments

win

A pointer to the window.

ch

The character to be added. A new-line character (\n) clears the line to the end, and moves the cursor to the next line at the same x coordinate. A return (\r) moves the cursor to the beginning of the line on the window. A tab (\t) moves the cursor to the next tabstop within the window.

Description

When the waddch function is used on a subwindow, it writes the character onto the underlying window as well.

The addch routine performs the same function as waddch , but on the stdscr window.

The cursor is moved after the character is written to the screen.


Return Values

OK Indicates success.
ERR Indicates that writing the character would cause the screen to scroll illegally. For more information, see the scrollok function in this section.

[w]addstr

Add the string pointed to by str to the window at the current position of the cursor.

Format

#include <curses.h>

int addstr (char *str);

int waddstr (WINDOW *win, char *str);


Arguments

win

A pointer to the window.

str

A pointer to a character string.

Description

When the waddstr function is used on a subwindow, the string is written onto the underlying window as well.

The addstr routine performs the same function as waddstr , but on the stdscr window.

The cursor position changes as a result of calling this routine.


Return Values

OK Indicates success.
ERR Indicates that the function causes the screen to scroll illegally, but it places as much of the string onto the window as possible. For more information, see the scrollok function in this section.

alarm

Sends the signal SIGALRM (defined in the <signal.h> header file) to the invoking process after the number of seconds indicated by its argument has elapsed.

Format

#include <unistd.h>

unsigned int alarm (unsigned int seconds); (ISO POSIX-1)

int alarm (unsigned int seconds); (COMPATABILITY)


Argument

seconds

Has a maximum limit of LONG_MAX seconds.

Description

Calling the alarm function with a 0 argument cancels any pending alarms.

Unless it is caught or ignored, the signal generated by alarm terminates the process. Successive alarm calls reinitialize the alarm clock. Alarms are not stacked.

Because the clock has a 1-second resolution, the signal may occur up to 1 second early. If the SIGALRM signal is caught, resumption of execution may be held up due to scheduling delays.

When the SIGALRM signal is generated, a call to SYS$WAKE is generated whether or not the process is hibernating. The pending wake causes the current pause () to return immediately (after completing any function that catches the SIGALRM).


Return Value

n The number of seconds remaining from a previous alarm request.

asctime, asctime_r

Converts a broken-down time in a tm structure into a 26-character string in the following form:


Sun Sep 16 01:03:52 1984\n\0 

All fields have a constant width.


Format

#include <time.h>

char *asctime (const struct tm *timeptr);

char *asctime_r (const struct tm *timeptr, char *buffer); (ISO POSIX-1)


Argument

timeptr

A pointer to a structure of type tm , which contains the broken-down time.

The tm structure is defined in the <time.h> header file, and also shown in Table REF-4 in the description of localtime .

buffer

A pointer to a character array that is at least 26 bytes long. This array is used to store the generated date-and-time string.

Description

The asctime and asctime_r functios convert the contents of tm into a 26-character string and returns a pointer to the string.

The difference between asctime_r and asctime is that the former puts the result into a user-specified buffer. The latter puts the result into thread-specific static memory allocated by the Compaq C RTL, which can be overwritten by subsequent calls to ctime or asctime ; you must make a copy if you want to save it.

On success, asctime returns a pointer to the string; asctime_r returns its second argument. On failure, these functions return the NULL pointer.

See the localtime function in this section for a list of the members in tm .

Note

Generally speaking, UTC-based time functions can affect in-memory time-zone information, which is process-wide data. However, if the system time zone remains the same during the execution of the application (which is the common case) and the cache of timezone files is enabled (which is the default), then the _r variant of the time functions asctime_r , ctime_r , gmtime_r and localtime_r , is both thread-safe and AST-reentrant.

If, however, the system time zone can change during the execution of the application or the cache of timezone files is not enabled, then both variants of the UTC-based time functions belong to the third class of functions, which are neither thread-safe nor AST-reentrant.

Return Value

x A pointer to the string, if successful.
NULL Indicates failure.

asin

Returns a value in the range --Pi sign/2 to Pi sign/2, which is the arc sine of its radian argument.

Format

#include <math.h>

double asin (double x);


Argument

x

A radian expressed as a real number.

Description

When abs (x) is greater than 1.0, the value of asin (x) is 0 and errno is set to EDOM.

assert

Used for implementing run-time diagnostics in programs.

Format

#include <assert.h>

void assert (int expression);


Argument

expression

An expression that has an int type.

Description

When assert is executed, if expression is false (that is, it evaluates to 0), assert writes information about the particular call that failed (including the text of the argument, the name of the source file, and the source line number; the latter two are respectively the values of the preprocessing macros __FILE__ and __LINE__) to the standard error file in an implementation-defined format. Then, it calls the abort function.

The assert function writes a message in the following form:


Assertion failed:  expression, file aaa, line nnn

If expression is true (that is, it evaluates to nonzero) or if the signal SIGABRT is being ignored, assert returns no value.

Note

If a null character ('\0') is part of the expression being asserted, then only the text up to and including the null character is printed, since the null character effectively terminates the string being output.

Compiling with the CC command qualifier /DEFINE=NDEBUG or with the preprocessor directive #define NDEBUG ahead of the #include assert statement causes the assert function to have no effect.


Example


#include <stdio.h> 
#include <assert.h> 
 
main() 
{ 
    printf("Only this and the assert\n"); 
    assert(1 == 2);     /* expression is FALSE */ 
 
    /* abort should be called so the printf will not happen. */ 
 
    printf("FAIL abort did not execute"); 
} 


atan

Returns a value in the range --Pi sign/2 to Pi sign/2, which is the arc tangent of its radian argument.

Format

#include <math.h>

double atan (double x);


Argument

x

A radian expressed as a real value.

atan2

Returns a value in the range --Pi sign to Pi sign. The returned value is the arc tangent of y/x, where y and x are the two arguments.

Format

#include <math.h>

double atan2 (double y, double x);


Arguments

y

A real value.

x

A real value.

atexit

Registers a function that is called without arguments at program termination.

Format

#include <stdlib.h>

int atexit (void (*func) (void));


Argument

func

A pointer to the function to be registered.

Return Values

0 Indicates that the registration has succeeded.
nonzero Indicates failure.

Restriction

The longjmp function cannot be executed from within the handler, because the destination address of the longjmp no longer exists.

Example


#include <stdlib.h> 
#include <stdio.h> 
 
static void hw(void); 
 
main() 
{ 
    atexit(hw); 
} 
    
static void hw() 
{ 
        puts("Hello, world\n"); 
} 

Running this example produces the following output:


Hello, world 
 


atof

Converts an ASCII character string to a double-precision number.

Format

#include <stdlib.h>

double atof (const char *nptr);


Argument

nptr

A pointer to the character string to be converted to a double-precision number. The string is interpreted by the same rules that are used to interpret floating constants.

Description

The string to be converted has the following format:

[white-spaces][+|-]digits[radix-character][digits][e|E[+|-]integer]

Where radix-character is defined in the current locale.

The first unrecognized character ends the conversion.

This function is equivalent to strtod(nptr, (char**) NULL) .


Return Values

x The converted value.
0 Indicates an underflow or the conversion could not be performed. The function sets errno to ERANGE or EINVAL, respectively.
(+/-)HUGE_VAL Indicates overflow; errno is set to ERANGE.

atoi, atol

Convert strings of ASCII characters to the appropriate numeric values.

Format

#include <stdlib.h>

int atoi (const char *nptr);

long int atol (const char *nptr);


Argument

nptr

A pointer to the character string to be converted to a numeric value.

Description

The atoi and atol functions convert the initial portion of a string to its decimal int or long int value, respectively. The atoi and atol functions do not account for overflows resulting from the conversion. The string to be converted has the following format:

[white-spaces][+|-]digits

The function call atol (str) is equivalent to strtol (str, (char**)NULL, 10) , and the function call atoi (str) is equivalent to (int) strtol (str, (char**)NULL, 10) , except, in both cases, for the behavior on error.


Return Value

n The converted value.


Previous Next Contents Index
  

1.800.AT.COMPAQ

privacy and legal statement