| United States |
|
|
| Previous | Contents | Index |
Sets the file position indicator for a given file.
#include <stdio.h>int fsetpos (FILE *stream, const fpos_t *pos);
stream
A file pointer.pos
A pointer to an implementation-defined structure. The fgetpos function fills this structure with information that can be used on subsequent calls to fsetpos .
Call the fgetpos function before using the fsetpos function.
0 Indicates success. --1 Indicates an error.
Accesses information about the file specified by the file descriptor.
#include <stat.h>Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to this function that is equivalent to the behavior before OpenVMS Version 7.0.int fstat (int file_desc, struct stat *buffer);
file_desc
A file descriptor.buffer
A pointer to a structure of type stat_t , which is defined in the <stat.h> header file. The argument receives information about that particular file. The members of the structure pointed to by buffer are as follows:
Member Type Definition st_dev dev_t Pointer to a physical device name st_ino[3] ino_t Three words to receive the file ID st_mode mode_t File "mode" (prot, dir,...) st_nlink nlink_t For UNIX system compatibility only st_uid uid_t Owner user ID st_gid gid_t Group member: from st_uid st_rdev dev_t UNIX system compatibility -- always 0 st_size off_t File size, in bytes st_atime time_t File access time; always the same as st_mtime st_mtime time_t Last modification time st_ctime time_t File creation time st_fab_rfm char Record format st_fab_rat char Record attributes st_fab_fsz char Fixed header size st_fab_mrs unsigned Record size The types dev_t , ino_t , off_t , mode_t , nlink_t , uid_t , gid_t , and time_t , are defined in the <stat.h> header file. However, when compiling for compatibility (/DEFINE=_DECC_V4_SOURCE), only dev_t , ino_t , and off_t are defined.
As of OpenVMS Version 7.0, times are given in seconds since the Epoch (00:00:00 GMT, January 1, 1970).
The st_mode structure member is the status information mode and is defined in the <stat.h> header file. The st_mode bits follow:
Bits Constant Definition 0170000 S_IFMT Type of file 0040000 S_IFDIR Directory 0020000 S_IFCHR Character special 0060000 S_IFBLK Block special 0100000 S_IFREG Regular 0030000 S_IFMPC Multiplexed char special 0070000 S_IFMPB Multiplexed block special 0004000 S_ISUID Set user ID on execution 0002000 S_ISGID Set group ID on execution 0001000 S_ISVTX Save swapped text even after use 0000400 S_IREAD Read permission, owner 0000200 S_IWRITE Write permission, owner 0000100 S_IEXEC Execute/search permission, owner
This function does not work on remote network files.
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.
0 Indicates successful completion. --1 Indicates an error other than a protection violation. --2 Indicates a protection violation.
Flushes data all the way to the disk.
#include <unistd.h>int fsync (int fd);
fd
A file descriptor corresponding to an open file.
This function behaves much like the fflush function. The primary difference between the two is that fsync flushes data all the way to the disk while fflush flushes data only as far as the underlying RMS buffers. Also, with fflush , you can flush all buffers at once; with fsync you cannot.
0 Indicates successful completion. --1 Indicates an error.
Returns the current byte offset to the specified stream file.
#include <stdio.h>long int ftell (FILE *file_ptr);
file_ptr
A file pointer.
This function measures the byte offset from the beginning of the file.For variable-length files, VFC files, or any file with carriage-control attributes, it the file is opened in record mode, then ftell returns the starting position of the current record, not the current byte offset.
When using record files, the ftell function ignores any characters that have been pushed back using either ungetc or ungetwc . This behavior does not occur if stream files are being used.
For a portable way to measure the exact offset for any type of file, see the fgetpos function.
n The current offset. EOF Indicates an error.
Returns the elapsed time since 00:00:00, January 1, 1970, in the structure pointed at by timeptr.
#include <timeb.h>Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to this function that is equivalent to the behavior before OpenVMS Version 7.0.int ftime (struct timeb *timeptr);
timeptr
A pointer to the structure timeb_t .
The typedef timeb_t refers to the following structure defined in the <timeb.h> header file:
typedef struct timeb { time_t time; unsigned short millitm; short timezone; short dstflag; };The member time gives the time in seconds.
The member millitm gives the fractional time in milliseconds.
After a call to ftime , the timezone and dstflag members of the timeb structure have the values of the global variables timezone and dstflag , respectively. See the description of the tzset function for timezone and dstflag global variables.
0 Successful execution. The timeb_t structure is filled in. --1 Indicates an error. Failure might indicate that the system's time-differential factor (that is, the difference between the system time and UTC time) is not set correctly. If the value of the SYS$TIMEZONE_DIFFERENTIAL logical is wrong, the function fails with errno set to EINVAL.
Truncates a file to a specified length.
#include <unistd.h>int ftruncate (int filedes, off_t length);
filedes
The descriptor of a file that must be open for writing.length
The new length of the file in bytes.
This function truncates a file at the specified position. For record files, the position must be a record boundary. Also, the files must be local, regular files.If the file was previously larger than length, extra data is lost. If the file was previously shorter than length, bytes between the old and new lengths are read as zeros.
0 Indicates success. --1 An error occurred; errno is set to indicate the error.
Walks a file tree.
#include <ftw.h>int ftw (const char *path, int(*function)(const char *, const struct stat *,int), int depth);
path
The directory hierarchy to be searched.function
The function to be invoked for each file in the directory hierarchy.depth
The maximum number of directory streams or file descriptors, or both, available for use by ftw . This argument should be in the range of 1 to OPEN_MAX.
This function recursively searches the directory hierarchy that descends from the directory specified by the path argument.For each file in the hierarchy, ftw calls the function specified by the function argument, passes it a pointer to a null-terminated character string containing the name of the file, a pointer to a stat structure containing information about the file, and an integer.
The integer identifies the file type. Possible values, defined in <ftw.h> are:
FTW_F Regular file. FTW_D Directory. FTW_DNR Directory that cannot be read. FTW_NS A file on which stat could not successfully be executed. If the integer is FTW_DNR, then the files and subdirectories contained in that directory are not processed.
If the integer is FTW_NS, then the stat structure contents are meaningless. For example, a file in a directory for which you have read permission but not execute (search) permission can cause the function argument to pass FTW_NS.
The ftw function finishes processing a directory before processing any of its files or subdirectories.
The ftw function continues the search until:
- The directory hierarchy specified by the path argument is completed.
- An invocation of the function specified by the function argument returns a nonzero value.
- An error (such as an I/O error) is detected within the ftw function.
Because the ftw function is recursive, it is possible for it to terminate with a memory fault because of stack overflow when applied to very deep file structures.
The ftw function uses the malloc function to allocate dynamic storage during its operation. If ftw is forcibly terminated, as with a call to longjmp from the function pointed to by the function argument, ftw has no chance to free that storage. It remains allocated.
A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have the function specified by the function argument return a nonzero value the next time it is called.
Note
The ftw function is reentrant; make sure that the function supplied as argument function is also reentrant.See malloc , longjump , lstat , and stat in this section.
0 Indicates success. x Indicates that the function specified by the function argument stops its search, and returns the value that was returned by the function. --1 Indicates an error; errno is set to one of the following values:
- EACCES -- Search permission is denied for any component of the path argument or read permission is denied for the path argument.
- ENAMETOOLONG -- The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX while [_POSIX_NO_TRUNC] is in effect.
- ENOENT -- The path argument points to the name of a file that does not exist or points to an empty string.
- ENOMEM -- There is insufficient memory for this operation.
Also, if the function pointed to by the function argument encounters an error, errno can be set accordingly.
Waits for I/O on a specific file to complete.
#include <stdio.h>int fwait (FILE *fp);
fp
A file pointer corresponding to an open file.
This function is used primarily to wait for completion of pending asynchronous I/O.
0 Indicates successful completion. --1 Indicates an error.
Determines and sets the orientation of a stream.
#include <wchar.h>int fwide (FILE *stream, int mode);
stream
A file pointer.mode
A value that specifies the desired orientation of the stream.
This function determines the orientation of the stream pointed to by stream and sets the orientation of a non-oriented stream according to the mode argument in the following way:
If the mode argument is Then the fwide function greater than zero makes the stream wide-oriented. less than zero makes the stream byte-oriented. zero does not alter the orientation of the stream. If the orientation of the stream has already been set, fwide does not alter it. Because no error status is defined for fwide , the calling application should check errno if fwide returns a 0.
> 0 After the call, the stream is wide-oriented. < 0 After the call, the stream is byte-oriented. 0 After the call, the stream has no orientation or a stream argument is invalid; the function sets errno .
| Previous | Next | Contents | Index |
|
