 |
Compaq C
Compaq C
Run-Time Library Reference Manual for
OpenVMS Systems
unordered (ALPHA ONLY)
Returns the value 1 (True) if either or both of the arguments is a NaN.
Otherwise, it returns the value 0 (False).
Format
#include <math.h>
double unordered (double x, double y);
float unorderedf (float x, float y);
long double unorderedl (long double x, long double y);
Argument
x
A real number.
y
A real number.
Return Values
|
1
|
Either or both of the arguments is a NaN.
|
|
0
|
Neither argument is a NaN.
|
utime
Sets file access and modification times.
Format
#include <types.h>
int utime (const char *path, const struct utimbuf
*times);
Argument
path
A pointer to a file.
times
A null pointer or a pointer to a
utimbuf
structure.
Description
The
utime
function sets the access and modification times of the file named by
the path argument.
If times is a null pointer, the access and modification times
of the file are set to the current time. To use
utime
in this way, the effective user ID of the process must match the owner
of the file, or the process must have write permission to the file or
have appropriate privileges.
If times is not a null pointer, it is interpreted as a pointer
to a
utimbuf
structure, and the access and modification times are set to the values
in the specified structure. Only a process with an effective user ID
equal to the user ID of the file or a process with appropriate
privileges can use
utime
this way.
The
utimbuf
structure is defined by the
<utime.h>
header. The times in the
utimbuf
structure are measured in seconds since the Epoch.
Upon successful completion,
utime
marks the time of the last file status change, st_ctime, to be
updated. See the <stat.h> header file.
Note
(ALPHA ONLY)
On OpenVMS Alpha systems, the
stat
,
fstat
,
utime
, and
utimes
functions have been enhanced to take advantage of the new file-system
support for POSIX-compliant file timestamps.
This support is available only on ODS-5 devices on OpenVMS Alpha
systems beginning with a version of OpenVMS Alpha after Version 7.3.
Before this change, the
stat
and
fstat
functions were setting the values of the st_ctime, st_mtime, and
st_atime fields based on the following file attributes:
st_ctime - ATR$C_CREDATE (file creation time)
st_mtime - ATR$C_REVDATE (file revision time)
st_atime - was always set to st_mtime because no support for file
access time was available
Also, for the file-modification time,
utime
and
utimes
were modifying the ATR$C_REVDATE file attribute, and ignoring the
file-access-time argument.
After the change, for a file on an ODS-5 device, the
stat
and
fstat
functions set the values of the st_ctime, st_mtime, and st_atime fields
based on the following new file attributes:
st_ctime - ATR$C_ATTDATE (last attribute modification time)
st_mtime - ATR$C_MODDATE (last data modification time)
st_atime - ATR$C_ACCDATE (last access time)
If ATR$C_ACCDATE is zero, as on an ODS-2 device, the
stat
and
fstat
functions set st_atime to st_mtime.
For the file-modification time, the
utime
and
utimes
functions modify both the ATR$C_REVDATE and ATR$C_MODDATE file
attributes. For the file-access time, these functions modify the
ATR$C_ACCDATE file attribute. Setting the ATR$C_MODDATE and
ATR$C_ACCDATE file attributes on an ODS-2 device has no effect.
For compatibility, the old behavior of
stat
,
fstat
,
utime
and
utimes
remains the default, regardless of the kind of device.
The new behavior must be explicitly enabled by defining the
DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before invoking the
application. Setting this logical does not affect the behavior of
stat
,
fstat
,
utime
and
utimes
for files on an ODS-2 device.
|
Return Values
|
0
|
Successful execution.
|
|
-1
|
Indicates an error. The function sets
errno
to one of the following values:
The
utime
function
will fail if:
- EACCES -- Search permission is denied by a component of the
path prefix; or the
times argument is a null pointer and the effective user ID of
the process does not match the owner of the file and write access is
denied.
- ELOOP -- Too many symbolic links were encountered in resolving
path.
- ENAMETOOLONG -- The length of the
path argument exceeds {PATH_MAX}, a path name component is
longer than {NAME_MAX}, or a path name resolution of a symbolic link
produced an intermediate result whose length exceeds {PATH_MAX}.
- ENOENT -- A component of
path does not name an existing file, or path is an empty
string.
- ENOTDIR -- A component of the
path prefix is not a directory.
- EPERM --The
times argument is not a null pointer and the calling process'
effective user ID has write-access to the file but does not match the
owner of the file and the calling process does not have the appropriate
privileges.
- EROFS -- The file system containing the file is read-only.
|
utimes
Sets file access and modification times.
Format
#include <time.h>
int utimes (const char *path, const struct timeval
times[2]);
Argument
path
A pointer to a file.
times
an array of
timeval
structures. The first array member represents the date and time of last
access, and the second member represents the date and time of last
modification. The times in the
timeval
structure are measured in seconds and microseconds since the Epoch,
although rounding toward the nearest second may occur.
Description
The
utimes
function sets the access and modification times of the file pointed to
by the path argument to the value of the times argument. The
utimes
function allows time specifications accurate to the microsecond.
If the times argument is a null pointer, the access and
modification times of the file are set to the current time. The
effective user ID of the process must be the same as the owner of the
file, or must have write access to the file or appropriate privileges
to use this call in this manner.
Upon completion,
utimes
marks the time of the last file status change, st_ctime, for
update.
Note
(ALPHA ONLY)
On OpenVMS Alpha systems, the
stat
,
fstat
,
utime
, and
utimes
functions have been enhanced to take advantage of the new file-system
support for POSIX-compliant file timestamps.
This support is available only on ODS-5 devices on OpenVMS Alpha
systems beginning with a version of OpenVMS Alpha after Version 7.3.
Before this change, the
stat
and
fstat
functions were setting the values of the st_ctime, st_mtime, and
st_atime fields based on the following file attributes:
st_ctime - ATR$C_CREDATE (file creation time)
st_mtime - ATR$C_REVDATE (file revision time)
st_atime - was always set to st_mtime because no support for file
access time was available
Also, for the file-modification time,
utime
and
utimes
were modifying the ATR$C_REVDATE file attribute, and ignoring the
file-access-time argument.
After the change, for a file on an ODS-5 device, the
stat
and
fstat
functions set the values of the st_ctime, st_mtime, and st_atime fields
based on the following new file attributes:
st_ctime - ATR$C_ATTDATE (last attribute modification time)
st_mtime - ATR$C_MODDATE (last data modification time)
st_atime - ATR$C_ACCDATE (last access time)
If ATR$C_ACCDATE is zero, as on an ODS-2 device, the
stat
and
fstat
functions set st_atime to st_mtime.
For the file-modification time, the
utime
and
utimes
functions modify both the ATR$C_REVDATE and ATR$C_MODDATE file
attributes. For the file-access time, these functions modify the
ATR$C_ACCDATE file attribute. Setting the ATR$C_MODDATE and
ATR$C_ACCDATE file attributes on an ODS-2 device has no effect.
For compatibility, the old behavior of
stat
,
fstat
,
utime
and
utimes
remains the default, regardless of the kind of device.
The new behavior must be explicitly enabled by defining the
DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before invoking the
application. Setting this logical does not affect the behavior of
stat
,
fstat
,
utime
and
utimes
for files on an ODS-2 device.
|
Return Values
|
0
|
Successful execution.
|
|
-1
|
Indicates an error. The file times do not change and the function sets
errno
to one of the following values:
The
utimes
function
will fail if:
- EACCES -- Search permission is denied by a component of the
path prefix; or the
times argument is a null pointer and the effective user ID of
the process does not match the owner of the file and write access is
denied.
- ELOOP -- Too many symbolic links were encountered in resolving
path.
- ENAMETOOLONG -- The length of the
path argument exceeds {PATH_MAX}, a path name component is
longer than {NAME_MAX}, or a path name resolution of a symbolic link
produced an intermediate result whose length exceeds {PATH_MAX}.
- ENOENT -- A component of
path does not name an existing file, or path is an empty
string.
- ENOTDIR -- A component of the
path prefix is not a directory.
- EPERM --The
times argument is not a null pointer and the calling process'
effective user ID has write-access to the file but does not match the
owner of the file and the calling process does not have the appropriate
privileges.
- EROFS -- The file system containing the file is read-only.
|
unsetenv
Deletes all instances of the environment variable name from the
environment list.
Format
#include <stdlib.h>
void unsetenv (const char *name);
Arguments
name
The environment variable to delete from the environment list.
Description
This function deletes all instances of the variable name pointed to by
the name argument from the environment list.
usleep
Suspends execution for an interval.
Format
#include <unistd.h>
int usleep (unsigned int mseconds);
Arguments
mseconds
The number of microseconds to suspend execution for.
Description
This function suspends the current process from execution for the
number of microseconds specified by the mseconds argument.
This argument must be less than 1,000,000. However, if its value is 0,
then the call has no effect.
There is one real-time interval timer for each process. The
usleep
function does not interfere with a previous setting of this timer. If
the process set this timer before calling
usleep
and if the time specified by mseconds equals or exceeds the
interval timer's prior setting, then the process is awakened shortly
before the timer was set to expire.
Return Values
|
0
|
Indicates success.
|
|
--1
|
Indicates an error occurred;
errno
is set to EINVAL.
|
VAXC$CRTL_INIT
Allows you to call the Compaq C RTL from other languages or to use
the Compaq C RTL when your main function is not in C. It initializes
the run-time environment and establishes both an exit and condition
handler.
VAXC$CRTL_INIT
is a synonym for
DECC$CRTL_INIT
. Either name invokes the same routine.
Format
#include <signal.h>
void VAXC$CRTL_INIT();
Description
The following example shows a Pascal program that calls the
Compaq C RTL using the
VAXC$CRTL_INIT
function:
On OpenVMS VAX systems:
$ PASCAL EXAMPLE
$ LINK EXAMPLE,SYS$LIBRARY:DECCRTL/LIB
$ TY EXAMPLE.PAS
PROGRAM TESTC(input, output);
PROCEDURE VAXC$CRTL_INIT; extern;
BEGIN
VAXC$CRTL_INIT;
END
$
|
On OpenVMS Alpha systems:
$ PASCAL EXAMPLE
$ LINK EXAMPLE,SYS$LIBRARY:VAXCRTL/LIB
$ TY EXAMPLE.PAS
PROGRAM TESTC(input, output);
PROCEDURE VAXC$CRTL_INIT; extern;
BEGIN
VAXC$CRTL_INIT;
END
$
|
A shareable image need only call this function if it contains a
Compaq C function for signal handling, environment variables,
I/O, exit handling, a default file protection mask, or if it is a child
process that should inherit context.
Although many of the initialization activities are performed only once,
DECC$CRTL_INIT
can safely be called multiple times. On OpenVMS VAX systems,
DECC$CRTL_INIT
establishes the Compaq C RTL internal OpenVMS exception handler in
the frame of the routine that calls
DECC$CRTL_INIT
each time
DECC$CRTL_INIT
is called.
At least one frame in the current call stack must have that handler
established for OpenVMS exceptions to get mapped to UNIX signals.
VAXC$ESTABLISH
Used for establishing an OpenVMS exception handler for a particular
routine. This function establishes a special Compaq C RTL exception
handler in the routine that called it. This special handler catches all
RTL-related exceptions that occur in later routines, and passes on all
other exceptions to your handler.
Format
#include <signal.h>
void VAXC$ESTABLISH (unsigned int (*exception_handler)(void
*sigarr, void *mecharr));
Arguments
exception_handler
The name of the function that you want to establish as an OpenVMS
exception handler. You pass a pointer to this function as the parameter
to VAXC$ESTABLISH.
sigarr
A pointer to the signal array.
mecharr
A pointer to the mechanism array.
Description
VAXC$ESTABLISH
must be used in place of LIB$ESTABLISH when programs use the
Compaq C RTL routines
setjmp
or
longjmp
. See
setjmp
and
longjmp
, or
sigsetjmp
and
siglongjmp
in this section.
You can only invoke the
VAXC$ESTABLISH
function from a Compaq C for OpenVMS function, because it relies on the
allocation of data space on the run-time stack by
the Compaq C compiler. Calling the OpenVMS system library routine
LIB$ESTABLISH directly from a Compaq C function results in
undefined
behavior from the
setjmp
and
longjmp
functions.
To cause an OpenVMS exception to generate a UNIX style signal, user
exception handlers must return SS$_RESIGNAL upon receiving any
exception that they do not want to handle. Returning SS$_NORMAL
prevents the generation of a UNIX style signal. UNIX signals are
generated as if by an exception handler in the stack frame of the main
C program. Not all OpenVMS exceptions correspond to UNIX signals. See
Chapter 4 for more information on the interaction of OpenVMS
exceptions and UNIX style signals.
Calling
VAXC$ESTABLISH
with an argument of NULL cancels an existing handler in that routine.
Notes
- On OpenVMS Alpha systems, VAXC$ESTABLISH is implemented as a
compiler built-in function, not as a Compaq C RTL function.
(ALPHA ONLY)
- On OpenVMS VAX systems, programs compiled with /NAMES=AS_IS should
link against SYS$LIBRARY:DECCRTL.OLB to resolve the name
VAXC$ESTABLISH, whether or not the program is compiled with the
/PREFIX_LIBRARY_ENTRIES switch. This is a restriction in the
implementation. (VAX ONLY)
|
va_arg
Used for returning the next item in the argument list.
Format
#include <stdarg.h> (ANSI C)
#include <varargs.h> (COMPAQ C EXTENSION)
type va_arg (va_list ap, type);
Arguments
ap
A variable list containing the next argument to be obtained.
type
A data type that is used to determine the size of the next item in the
list. An argument list can contain items of varying sizes, but the
calling routine must determine what type of argument is expected since
it cannot be determined at run time.
Description
This function interprets the object at the address specified by the
list incrementor according to type. If there is no corresponding
argument, the behavior is undefined.
When using
va_arg
to write portable applications, include the
<stdarg.h>
header file (defined by the ANSI C standard), not the
<varargs.h>
header file, and use
va_arg
only in conjunction with other functions and macros defined in
<stdarg.h>
.
For an example of argument-list processing using the <stdarg.h>
functions and definitions, see Chapter 3, Example 3-6.
va_count
Returns the number of longwords (VAX ONLY) or quadwords
(ALPHA ONLY) in the argument list.
Format
#include <stdarg.h> (ANSI C)
#include <varargs.h> (COMPAQ C EXTENSION)
void va_count (int *count);
Argument
count
An integer variable name in which the number of longwords
(VAX ONLY) or quadwords (ALPHA ONLY) is returned.
Description
This function places the number of longwords (VAX ONLY) or
quadwords (ALPHA ONLY) in the argument list into count. The
value returned in count is the number of longwords
(VAX ONLY) or quadwords (ALPHA ONLY) in the function argument
block not counting the count field itself.
If the argument list contains items whose storage requirements are a
longword (VAX ONLY) or quadword (ALPHA ONLY) of memory or less,
the number in the count argument is also the number of
arguments. However, if the argument list contains items that are longer
than a longword (VAX ONLY) or a quadword (ALPHA ONLY),
count must be interpreted to obtain the number of arguments.
Because a
double
is 8 bytes, it occupies two argument-list positions on OpenVMS VAX
systems, and one argument-list position on OpenVMS Alpha systems.
This function is specific to Compaq C for OpenVMS Systems and is not portable.
va_end
Finishes the
<varargs.h>
or
<stdarg.h>
session.
Format
#include <stdarg.h> (ANSI C)
#include <varargs.h> (COMPAQ C EXTENSION)
void va_end (va_list ap);
Argument
ap
The object used to traverse the argument list length. You must declare
and use the argument ap as shown in this format section.
Description
You can execute multiple traversals of the argument list, each
delimited by
va_start
...
va_end
. The
va_end
function sets ap equal to NULL.
When using this function to write portable applications, include the
<stdarg.h>
header file (defined by the ANSI C standard), not the
<varargs.h>
header file, and use
va_end
only in conjunction with other routines defined in
<stdarg.h>
.
For an example of argument-list processing using the <stdarg.h>
functions and definitions, see Chapter 3, Example 3-6.
|
 |
|
