| Previous | Contents | Index |
Gets information about a device containing the specified file.
#include <statvfs.h>int fstatvfs (int filedes, struct statvfs *buffer);
filedes
File descriptor obtained from a successful open or fcntl function call.buffer
Pointer to a statvfs structure to hold the returned information.
The fstatvfs function returns descriptive information about the device containing the specified file. Read, write, or execute permission of the specified file is not required. The returned information is in the format of a statvfs structure, which is defined in the <statvfs.h> header file and contains the following members:unsigned long f_bsize - Preferred block size.
unsigned long f_frsize - Fundamental block size.
fsblkcnt_t f_blocks - Total number of blocks in units of f_frsize .
fsblkcnt_t f_bfree - Total number of free blocks. If f_bfree would assume a meaningless value due to the misreporting of free block count by $GETDVI for a DFS disk, then f_bfree is set to the maximum block count.
fsblkcnt_t f_bavail - Number of free blocks available. Set to the unused portion of the caller's disk quota.
fsfilcnt_t f_files - Total file (inode) count.
fsfilcnt_t f_ffree - Free file (inode) count. For OpenVMS systems, this value is calculated as freeblocks/clustersize.
fsfilcnt_t f_favail - Free file (inode) count nonprivileged. Set to f_ffree .
unsigned long f_fsid - File system identifier. This identifier is based on the allocation-class device name. This gives a unique value based on device, as long as the device is locally mounted.
unsigned long f_flag - Bit mask representing one or more of the following flags:ST_RONLY - The volume is read-only.
ST_NOSUID - The volume has protected subsystems enabled.
unsigned long f_namemax - Maximum length of a file name.
char f_basetype[64] - Device-type name.
char f_fstr[64] - Logical volume name.
char __reserved[64] - Media type name.Upon successful completion, fstatvfs returns 0 (zero). Otherwise, it returns - 1 and sets errno to indicate the error.
See also statvfs .
0 Sucessful completion. - 1 Indicates an error. errno is set to one of the following:
- EBADF - The file descriptor parameter contains an invalid value.
- EIO - An I/O error occurred while reading the device.
- EINTR - A signal was caught during execution of the function.
- EOVERFLOW - One of the values to be returned cannot be represented correctly in the structure pointed to by buffer.
Flushes data all the way to the disk.
#include <unistd.h>int fsync (int fd);
fd
A file descriptor corresponding to an open file.
The fsync 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.
The ftell function measures the byte offset from the beginning of the file.For variable-length files, VFC files, or any file with carriage-control attributes, if 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 current byte offset to the specified stream file. This function is equivalent to ftell .
#include <stdio.h>off_t ftello (FILE *file_ptr);
file_ptr
A file pointer.
The ftello function is identical to the ftell function, except that the return value is of type off_t instead of long int .The off_t data type is either a 64-bit or 32-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and can be selected at compile time by defining the _LARGEFILE feature-test macro as follows:
CC/DEFINE=_LARGEFILE
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 the ftime 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. The off_t data type is either a 32-bit or 64-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and can be selected at compile time by defining the _LARGEFILE feature-test macro as follows:
CC/DEFINE=_LARGEFILE
The ftruncate 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.
Acquires ownership of a stdio (FILE*) object.
#include <stdio.h>int ftrylockfile (FILE *file_ptr);
file_ptr
A file pointer.
The ftrylockfile function is used by a thread to acquire ownership of a stdio (FILE*) object, if the object is available. The ftrylockfile function is a non-blocking version of flockfile .The ftrylockfile function returns zero for success and nonzero to indicate that the lock cannot be acquired.
See also flockfile and funlockfile .
0 Indicates success. nonzero Indicates the lock cannot be acquired.
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.
The ftw 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.
Notes
- The ftw function is reentrant; make sure that the function supplied as argument function is also reentrant.
- The C RTL supports a standard-compliant definition of the stat structure and associated definitions. To use them, compile your application with the _USE_STD_STAT feature-test macro defined. See the <stat.h> header file on your system for more information.
See also malloc , longjump , and stat .
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.
Unlocks a stdio stream.
#include <stdio.h>void funlockfile (FILE *file_ptr);
file_ptr
A file pointer.
The funlockfile function unlocks a stdio stream, causing the thread that had been holding the lock to relinquish exclusive use of the stream.File pointers passed are assumed to be valid; flockfile will perform locking even on invalid file pointers. Also, the funlockfile function will not fail if the calling thread does not own a lock on the file pointer passed.
Matching flockfile and funlockfile calls can be nested. If the stream has been locked recursively, it will remain locked until the last matching funlockfile is called.
All C RTL file-pointer I/O functions lock their file pointers as if calling flockfile and funlockfile .
See also flockfile and ftrylockfile .
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.
The fwait 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.
The fwide function determines the orientation of the stream pointed to by stream and sets the orientation of a nonoriented 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 .
Writes output to the stream under control of the wide-character format string.
#include <wchar.h>int fwprintf (FILE *stream, const wchar_t *format, ...);
stream
A file pointer.format
A pointer to a wide-character string containing the format specifications. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2....
Optional expressions whose resultant types correspond to conversion specifications given in the format specification.If no conversion specifications are given, the output sources can be omitted. Otherwise, the function calls must have exactly as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.
Conversion specifications are matched to output sources in left-to-right order. Any excess output sources are ignored.
The fwprintf function writes output to the stream pointed to by stream under control of the wide-character string pointed to by format, which specifies how to convert subsequent arguments to output. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated, but are otherwise ignored. The fwprintf function returns when it encounters the end of the format string.The format argument is composed of zero or more directives that include:
- Ordinary wide characters (not the percent sign (%))
- Conversion specifications
n The number of wide characters written. Negative value Indicates an error. The function sets errno to one of the following:
- EILSEQ -- Invalid character detected.
- EINVAL -- Insufficient arguments.
- ENOMEM -- Not enough memory available for conversion.
- ERANGE -- Floating-point calculations overflow.
- EVMSERR -- Nontranslatable OpenVMS error. vaxc$errno contains the OpenVMS error code. This might indicate that conversion to a numeric value failed because of overflow.
The function can also set errno to the following as a result of errors returned from the I/O subsystem:
- EBADF -- The file descriptor is not valid.
- EIO -- I/O error.
- ENOSPC -- No free space on the device containing the file.
- ENXIO -- Device does not exist.
- EPIPE -- Broken pipe.
- ESPIPE -- Illegal seek in a file opened for append.
- EVMSERR -- Nontranslatable OpenVMS error. vaxc$errno contains the OpenVMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.
The following example shows how to print a date and time in the form "Sunday, July 3, 10:02", followed by pi to five decimal places:
#include <math.h> #include <stdio.h> #include <wchar.h> /*...*/ wchar_t *weekday, *month; /* pointers to wide-character strings */ int day, hours, min; fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n", weekday, month, day, hour, min); fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));
| Previous | Next | Contents | Index |