United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# fsetpos

> Sets the file position indicator for a given file.

## Format

> #include <stdio.h>

> int fsetpos (FILE *stream, const fpos_t *pos);

## Arguments

> ### 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` .

## Description

> Call the `fgetpos` function before using the `fsetpos` function.

## Return Values

> 0 | Indicates success.
> --1 | Indicates an error.

# fstat

> Accesses information about the file specified by the file descriptor.

## Format

> #include <stat.h>

> int fstat (int file_desc, struct stat *buffer);

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.

## Arguments

> ### 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

## Description

> 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.

## Return Values

> 0 | Indicates successful completion.
> --1 | Indicates an error other than a protection violation.
> --2 | Indicates a protection violation.

# fsync

> Flushes data all the way to the disk.

## Format

> #include <unistd.h>

> int fsync (int fd);

## Argument

> ### fd

> A file descriptor corresponding to an open file.

## Description

> 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.

## Return Values

> 0 | Indicates successful completion.
> --1 | Indicates an error.

# ftell

> Returns the current byte offset to the specified stream file.

## Format

> #include <stdio.h>

> long int ftell (FILE *file_ptr);

## Argument

> ### file_ptr

> A file pointer.

## Description

> 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.

## Return Values

> n | The current offset.
> EOF | Indicates an error.

# ftime

> Returns the elapsed time since 00:00:00, January 1, 1970, in the structure pointed at by timeptr.

## Format

> #include <timeb.h>

> int ftime (struct timeb *timeptr);

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.

## Argument

> ### timeptr

> A pointer to the structure `timeb_t` .

## Description

> 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.

## Return Values

> 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.

# ftruncate

> Truncates a file to a specified length.

## Format

> #include <unistd.h>

> int ftruncate (int filedes, off_t length);

## Arguments

> ### filedes

> The descriptor of a file that must be open for writing.

> ### length

> The new length of the file in bytes.

## Description

> 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.

## Return Values

> 0 | Indicates success.
> --1 | An error occurred; `errno` is set to indicate the error.

# ftw

> Walks a file tree.

## Format

> #include <ftw.h>

> int ftw (const char *path, int(*function)(const char *, const struct stat *,int), int depth);

## Arguments

> ### 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.

## Description

> 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.

## Return Values

> 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.

# fwait

> Waits for I/O on a specific file to complete.

## Format

> #include <stdio.h>

> int fwait (FILE *fp);

## Argument

> ### fp

> A file pointer corresponding to an open file.

## Description

> This function is used primarily to wait for completion of pending asynchronous I/O.

## Return Values

> 0 | Indicates successful completion.
> --1 | Indicates an error.

# fwide

> Determines and sets the orientation of a stream.

## Format

> #include <wchar.h>

> int fwide (FILE *stream, int mode);

## Arguments

> ### stream

> A file pointer.

> ### mode

> A value that specifies the desired orientation of the stream.

## Description

> 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.

## Return Values

> > 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

privacy and legal statement