|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
Gets system identification information.
#include <utsname.h>int uname (struct utsname *name);
name
The current system identifier.
The uname function stores null-terminated strings of information identifying the current system into the structure referenced by the name argument.The utsname structure is defined in the <utsname.h> header file and contains the following members:
sysname Name of the operating system implementation nodename Network name of this machine release Release level of the operating system version Version level of the operating system machine Machine hardware platform
0 Indicates success. - 1 Indicates an error; errno or vaxc$errno is set as appropriate.
Pushes a character back into the input stream and leaves the stream positioned before the character.
#include <stdio.h>int ungetc (int character, FILE *file_ptr);
character
A value of type int .file_ptr
A file pointer.
When using the ungetc function, the character is pushed back onto the file indicated by file_ptr.One push-back is guaranteed, even if there has been no previous activity on the file. The fseek function erases all memory of pushed-back characters. The pushed-back character is not written to the underlying file. If the character to be pushed back is EOF, the operation fails, the input stream is left unchanged, and EOF is returned.
See also fseek and getc .
x The push-back character. EOF Indicates it cannot push the character back.
Pushes a wide character back into the input stream.
#include <wchar.h>wint_t ungetwc (wint_t wc, FILE *file_ptr);
wc
A value of type wint_t .file_ptr
A file pointer.
When using the ungetwc function, the wide character is pushed back onto the file indicated by file_ptr.One push-back is guaranteed, even if there has been no previous activity on the file. If a file positioning function (such as fseek ) is called before the pushed back character is read, the bytes representing the pushed back character are lost.
If the character to be pushed back is WEOF, the operation fails, the input stream is left unchanged, and WEOF is returned.
See also getwc .
x The push-back character. WEOF Indicates that the function cannot push the character back. errno is set to one of the following:
- EBADF -- The file descriptor is not valid.
- EALREADY -- Operation is already in progress on the same file.
- EILSEQ -- Invalid wide-character code detected.
Returns the value 1 (TRUE) if either or both of the arguments is a NaN. Otherwise, it returns the value 0 (FALSE).
#include <math.h>double unordered (double x, double y);
float unorderedf (float x, float y);
long double unorderedl (long double x, long double y);
x
A real number.y
A real number.
1 Either or both of the arguments is a NaN. 0 Neither argument is a NaN.
Sets file access and modification times.
#include <types.h>int utime (const char *path, const struct utimbuf *times);
path
A pointer to a file.times
A NULL pointer or a pointer to a utimbuf structure.
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, stat and fstat set 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 0, 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.
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 pathname component is longer than {NAME_MAX}, or a pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.
- ENOENT -- 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 -- times is not a NULL pointer and the calling process's 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.
Sets file access and modification times.
#include <time.h>int utimes (const char *path, const struct timeval times[2]);
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.
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 0, 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.
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 pathname component is longer than {NAME_MAX}, or a pathname 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's 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.
Deletes all instances of the environment variable name from the environment list.
#include <stdlib.h>void unsetenv (const char *name);
name
The environment variable to delete from the environment list.
The unsetenv function deletes all instances of the variable name pointed to by the name argument from the environment list.
Suspends execution for an interval.
#include <unistd.h>int usleep (unsigned int mseconds);
mseconds
The number of microseconds to suspend execution for.
The usleep 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.
0 Indicates success. - 1 Indicates an error occurred; errno is set to EINVAL.
Allows you to call the HP C RTL from other languages or to use the HP 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.
#include <signal.h>void VAXC$CRTL_INIT();
The following example shows a Pascal program that calls the HP 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 an HP 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 HP 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.
Used for establishing an OpenVMS exception handler for a particular routine. This function establishes a special HP 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.
#include <signal.h>void VAXC$ESTABLISH (unsigned int (*exception_handler)(void *sigarr, void *mecharr));
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.
VAXC$ESTABLISH must be used in place of LIB$ESTABLISH when programs use the HP C RTL routines setjmp or longjmp . See setjmp and longjmp , or sigsetjmp and siglongjmp .You can only invoke the VAXC$ESTABLISH function from an HP C for OpenVMS function, because it relies on the allocation of data space on the run-time stack by the HP C compiler. Calling the OpenVMS system library routine LIB$ESTABLISH directly from an HP 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 an HP 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)
| Previous | Next | Contents | Index |