|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
Writes a character to a specified file.
#include <stdio.h>int fputc (int character, FILE *file_ptr);
character
An object of type int .file_ptr
A file pointer.
The fputc function writes a single character to a file and returns the character.See also putc .
x The character written to the file. Indicates success. EOF Indicates an output error.
Writes a character string to a file without copying the string's null terminator (\0).
#include <stdio.h>int fputs (const char *str, FILE *file_ptr);
str
A pointer to a character string.file_ptr
A file pointer.
Unlike puts , the fputs function does not append a new-line character to the output string.See also puts .
Nonnegative value Indicates success. EOF Indicates an error.
Converts a wide character to its corresponding multibyte value, and writes the result to a specified file.
#include <wchar.h>wint_t fputwc (wint_t wc, FILE *file_ptr);
wc
An object of type wint_t .file_ptr
A file pointer.
The fputwc function writes a wide character to a file and returns the character.See also putwc .
x The character written to the file. Indicates success. WEOF Indicates an output error. The function sets errno to the following:
- EILSEQ -- Invalid wide-character code detected.
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.
Writes a wide-character string to a file without copying the null-terminating character.
#include <wchar.h>int fputws (const wchar_t *wstr, FILE *file_ptr);
wstr
A pointer to a wide-character string.file_ptr
A file pointer.
The fputws function converts the specified wide-character string to a multibyte character string and writes it to the specified file. The function does not append a terminating null byte corresponding to the null wide-character to the output string.
Nonnegative value Indicates success. - 1 Indicates an error. The function sets errno . For a list of the values, see fputwc .
Reads a specified number of items from the file.
#include <stdio.h>size_t fread (void *ptr, size_t size_of_item, size_t number_items, FILE *file_ptr);
ptr
A pointer to the location, within memory, where you place the information being read. The type of the object pointed to is determined by the type of the item being read.size_of_item
The size of the items being read, in bytes.number_items
The number of items to be read.file_ptr
A pointer that indicates the file from which the items are to be read.
The type size_t is defined in the header file <stdio.h> as follows:
typedef unsigned int size_tThe reading begins at the current location in the file. The items read are placed in 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 was opened in record mode, fread will read size_of_item multiplied by number_items bytes from the file. That is, it does not necessarily read number_items records.
n The number of bytes read divided by size_of_item. 0 Indicates the end-of-file or an error.
Makes available for reallocation the area allocated by a previous calloc , malloc , or realloc call.
#include <stdlib.h>void free (void *ptr);
ptr
The address returned by a previous call to malloc , calloc , or realloc . If ptr is a NULL pointer, no action occurs.
The ANSI C standard defines free as not returning a value; therefore, the function prototype for free is declared with a return type of void . However, since a free can fail, and since previous versions of the HP C RTL have declared free to return an int , the implementation of free does return 0 on success and - 1 on failure.
Substitutes the file named by a file specification for the open file addressed by a file pointer. The latter file is closed.
#include <stdio.h>FILE *freopen (const char *file_spec, const char *a_mode, FILE *file_ptr, ...);
file_spec
A pointer to a string that contains a valid OpenVMS or UNIX style file specification. After the function call, the given file pointer is associated with this file.a_mode
The access mode indicator. See the fopen function for a description.file_ptr
A file pointer....
Optional file attribute arguments. The file attribute arguments are the same as those used in the creat function.
The freopen function is typically used to associate one of the predefined names stdin , stdout , or stderr with a file. For more information about these predefined names, see Chapter 2.
file_ptr The file pointer, if freopen is successful. NULL Indicates an error.
Calculates the fractional and exponent parts of a floating-point value.
#include <math.h>double frexp (double value, int *eptr);
float frexp (float value, int *eptr); (ALPHA ONLY)
long double frexp (long double value, int *eptr); (ALPHA ONLY)
value
A floating-point number of type double , float , or long double .eptr
A pointer to an int where frexp places the exponent.
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.
#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 5 . The example produces the following output:
fraction = 0.500000 exp = 5|value| = Infinity or NaN is an invalid argument.
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.
#include <stdio.h>int fscanf (FILE *file_ptr, const char *format_spec, ...);
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.
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 17The 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.
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.
#include <stdio.h>int fseek (FILE *file_ptr, long int offset, int direction);
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.
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 .
0 Indicates successful seeks. - 1 Indicates improper seeks.
Positions the file to the specified byte offset in the file. Equivalent to fseek .
#include <stdio.h>int fseeko (FILE *file_ptr, off_t offset, int direction);
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=_LARGEFILEdirection
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.
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.
#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 the fstat 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:
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=_LARGEFILEAs 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
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 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 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.
0 Indicates successful completion. - 1 Indicates an error other than a protection violation. - 2 Indicates a protection violation.
| Previous | Next | Contents | Index |