|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
Creates a file protection mask that is used when a new file is created, and returns the previous mask value.
#include <stat.h>mode_t umask (mode_t mode_complement);
mode_complement
Shows which bits to turn off when a new file is created. See the description of chmod to determine what the bits represent.
Initially, the file protection mask is set from the current process's default file protection. This is done when the C main program starts up or when DECC$CRTL_INIT (or VAXC$CRTL_INIT ) is called. You can change this for all files created by your program by calling umask or you can use chmod to change the file protection on individual files. The file protection of a file created by open or creat is the bitwise AND of the open and creat mode argument with the complement of the value passed to umask on the previous call.
Note
The way to create files with OpenVMS RMS default protections using the UNIX system-call functions umask , mkdir , creat , and open is to call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on.
In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.
x The old mask value.
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.
Deletes the specified symbolic link from the system.
#include <unistd.h>int unlink (const char *link_name);
link_name
The name of the symbolic link to be deleted.
The unlink function deletes the specified symbolic link (link_name) from the system. The contents of the symbolic link are not examined, and no action is performed on the file specified in the contents. For other files, the unlink function behaves the same as the C RTL remove function.See also symlink , readlink , realpath , lchown , and lstat .
0 Succesful completion. - 1 Indicates an error. The named file ( link_name) is unchanged, and errno is set to any errno value from remove .
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.
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.
Sets file access and modification times.
#include <utime.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, I64)
On OpenVMS Alpha and I64 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, I64)
On OpenVMS Alpha and I64 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.
| Previous | Next | Contents | Index |