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.

ftello

Returns the current byte offset to the specified stream file. Equivalent to ftell .

Format

#include <stdio.h>

off_t ftello (FILE *file_ptr);

Argument

file_ptr

A file pointer.

Description

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 integer or a 32-bit integer. The 64-bit interface allows for file sizes greater than 2 gigabytes, and can be selected at compile time by defining the _LARGEFILE feature-test macro:

CC/DEFINE=_LARGEFILE

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

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. The off_t data type is either a 32-bit integer or 64-bit integer. The 64-bit interface allows for file sizes greater than 2 gigabytes, and can be selected at compile time by defining the _LARGEFILE feature-test macro:

CC/DEFINE=_LARGEFILE

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 .

fwprintf

Writes output to the stream under control of the wide-character format string.

Format

#include <wchar.h>

int fwprintf (FILE *stream, const wchar_t *format, ...);

Arguments

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.

Description

This 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

Return Values

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 VMS error. vaxc$errno contains the VMS 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 VMS error. vaxc$errno contains the VMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.

Example

The following example shows how to print a date and time in the form "Sunday, July 3, 10:02", followed by Pi sign 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));

fwrite

Writes a specified number of items to the file.

Format

#include <stdio.h>

size_t fwrite (const void *ptr, size_t size_of_item, size_t number_items, FILE *file_ptr);

Arguments

ptr

A pointer to the memory location from which information is being written. The type of the object pointed to is determined by the type of the item being written.

size_of_item

The size, in bytes, of the items being written.

number_items

The number of items to be written.

file_ptr

A file pointer that indicates the file to which the items are being written.

Description

The type size_t is defined in the header file <stdio.h> as follows:

typedef unsigned int size_t

The writing begins at the current location in the file. The items are written from storage beginning at the location given by the first argument. You must also specify the size of an item, in bytes.

If the file pointed to by file_ptr is a record file, the fwrite function outputs at least number_items records, each of length size_of_item.

Return Value

x	The number of items written. The number of records written depends upon the maximum record size of the file.

fwscanf

Reads input from the stream under control of the wide-character format string.

Format

#include <wchar.h>

int fwscanf (FILE *stream, const wchar_t *format, ...);

Arguments

stream

A file pointer.

format

A pointer to a wide-character string containing the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

...

Optional expressions whose results correspond to conversion specifications given in the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

If no conversion specifications are given, you can omit the input pointers. Otherwise, the function calls must have exactly as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.

Description

This function reads input from the stream pointed to by stream under the control of the wide-character string pointed to by format. 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 otherwise ignored.

The format is composed of zero or more directives that include:

• One or more white-space wide characters.
• An ordinary wide character (neither a percent (%)) nor a white-space wide character).
• Conversion specifications.

Each conversion specification is introduced by the wide character %.

If the stream pointed to by the stream argument has no orientation, fwscanf makes the stream wide-oriented.

Return Values

n	The number of input items assigned, sometimes fewer than provided for, or even zero, in the event of an early matching failure.
EOF	Indicates an error; input failure occurs before any conversion.

gcvt

Converts its argument to a null-terminated string of ASCII digits and returns the address of the string.

Format

#include <stdlib.h>

char *gcvt (double value, int ndigit, char *buffer);

Arguments

value

An object of type double that is converted to a null-terminated string of ASCII digits.

ndigit

The number of ASCII digits to use in the converted string. If ndigit is less than 6, the value of 6 is used.

buffer

A storage location to hold the converted string.

Description

This function places the converted string in a buffer and returns the address of the buffer. If possible, gcvt produces ndigit significant digits in F-format, or if not possible, in E-format. Trailing zeros are suppressed.

The ecvt , fcvt , and gcvt functions represent the following special values specified in the IEEE Standard for floating-point arithmetic:

Value	Representation
Quiet NaN	NaNQ
Signalling NaN	NaNS
+Infinity	Infinity
--Infinity	--Infinity

The sign associated with each of these values is stored into the sign argument. In IEEE floating-point representation, a value of 0 (zero) can be positive or negative, as set by the sign argument.

See also fcvt and ecvt in this section.

Return Value

x	The address of the buffer.