HP OpenVMS Systems Documentation

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Calculates the fractional and exponent parts of a floating-point value.

Format

#include <math.h>

double frexp (double value, int *eptr);

float frexp (float value, int *eptr); (ALPHA, I64)

long double frexp (long double value, int *eptr); (ALPHA, I64)

Arguments

value

A floating-point number of type double , float , or long double .

eptr

A pointer to an int where frexp places the exponent.

Description

The frexp functions break the floating-point number (value) into a normalized fraction and an integral power of 2, as follows:

value = fraction * (2exp)

The fractional part is returned as the return value. The exponent is placed in the integer variable pointed to by eptr.

Example

#include <math.h> main () { double val = 16.0, fraction; int exp; fraction = frexp(val, &exp); printf("fraction = %f\n",fraction); printf("exp = %d\n",exp); }

In this example, frexp converts the value 16 to .5 * 2 ⁵ . The example produces the following output:

fraction = 0.500000 exp = 5

|value| = Infinity or NaN is an invalid argument.

Return Values

x	The fractional part of value.
0	Both parts of the result are 0.
NaN	If value is NaN, NaN is returned, errno is set to EDOM, and the value of * eptr is unspecified.
value	If | value| = Infinity, value is returned, errno is set to EDOM, and the value of * eptr is unspecified.

Performs formatted input from a specified file, interpreting it according to the format specification.

Format

#include <stdio.h>

int fscanf (FILE *file_ptr, const char *format_spec, ...);

Arguments

file_ptr

A pointer to the file that provides input text.

format_spec

A pointer to a character string that contains the format specification. For more information on conversion characters, see Chapter 2.

...

Optional expressions whose results correspond to conversion specifications given in the format specification.

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

An example of a conversion specification follows:

#include <stdio.h> main () { int temp, temp2; fscanf(stdin, "%d %d", &temp, &temp2); printf("The answers are %d, and %d.", temp, temp2); }

Consider a file, designated by stdin , with the following contents:

4 17

The example conversion specification produces the following result:

The answers are 4, and 17.

For a complete description of the format specification and the input pointers, see Chapter 2.

Return Values

x

The number of successfully matched and assigned input items.

EOF

Indicates that the end-of-file was encountered or a read error occurred. If a read error occurs, the function sets errno to one of the following: EILSEQ -- Invalid character detected. EVMSERR -- Nontranslatable OpenVMS error. vaxc$errno contains the OpenVMS error code. This can indicate that conversion to a numeric value failed due to 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. ENXIO -- Device does not exist. EPIPE -- Broken pipe. 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.

Positions the file to the specified byte offset in the file.

Format

#include <stdio.h>

int fseek (FILE *file_ptr, long int offset, int direction);

Arguments

file_ptr

A file pointer.

offset

The offset, specified in bytes.

direction

An integer indicating the position to which the offset is added to calculate the new position. The new position is the beginning of the file if direction is SEEK_SET, the current value of the file position indicator if direction is SEEK_CUR, or end-of-file if direction is SEEK_END.

Description

The fseek function can position a fixed-length record-access file with no carriage control or a stream-access file on any byte offset, but can position all other files only on record boundaries.

The available Standard I/O functions position a variable-length or VFC record file at its first byte, at the end-of-file, or on a record boundary. Therefore, the arguments given to fseek must specify any of the following:

• The beginning or end of the file
• A 0 offset from the current position (an arbitrary record boundary)
• The position returned by a previous, valid ftell call

See the fgetpos and fsetpos functions for a portable way to seek to arbitrary locations with these types of record files.

CAUTION If, while accessing a stream file, you seek beyond the end-of-file and then write to the file, the fseek function creates a hole by filling the skipped bytes with zeros. In general, for record files, fseek should only be directed to an absolute position that was returned by a previous valid call to ftell , or to the beginning or end of a file. If a call to fseek does not satisfy these conditions, the results are unpredictable.

See also open , creat , dup , dup2 , and lseek .

Return Values

0	Indicates successful seeks.
- 1	Indicates improper seeks.

Positions the file to the specified byte offset in the file. Equivalent to fseek .

Format

#include <stdio.h>

int fseeko (FILE *file_ptr, off_t offset, int direction);

Arguments

file_ptr

A file pointer.

offset

The offset, specified 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

direction

An integer indicating the position to which the offset is added to calculate the new position. The new position is the beginning of the file if direction is SEEK_SET, the current value of the file position indicator if direction is SEEK_CUR, or end-of-file if direction is SEEK_END.

Description

The fseeko function is identical to the fseek function, except that the offset argument is of type off_t instead of long int .

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.

Accesses information about the file specified by the file descriptor.

Format

#include <stat.h>

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

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:

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. For st_size to report a correct value, you need to flush both the C RTL and RMS buffers.
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.

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

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

The fstat function does not work on remote network files.

Be aware that for the stat_t structure member st_size to report a correct value, you need to flush both the C RTL and RMS buffers.

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 and I64 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 at run time 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.

Gets information about a device containing the specified file.

Format

#include <statvfs.h>

int fstatvfs (int filedes, struct statvfs *buffer);

Arguments

filedes

File descriptor obtained from a successful open or fcntl function call.

buffer

Pointer to a statvfs structure to hold the returned information.

Description

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 .

Return Value

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.