United States

Compaq C

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

Previous | Contents | Index

# feof

> Tests a file to see if the end-of-file has been reached.

## Format

> #include <stdio.h>

> int feof (FILE *file_ptr);

## Argument

> ### file_ptr

> A file pointer.

## Return Values

> nonzero integer | Indicates that the end-of-file has been reached.
> 0 | Indicates that the end-of-file has not been reached.

# ferror

> Returns a nonzero integer if an error occurred while reading or writing a file.

## Format

> #include <stdio.h>

> int ferror (FILE *file_ptr);

## Argument

> ### file_ptr

> A file pointer.

## Description

> A call to `ferror` continues to return a nonzero integer until the file is closed or until `clearerr` is called.

## Return Values

> 0 | Indicates success.
> nonzero integer | Indicates that an error has occurred.

# fflush

> Writes out any buffered information for the specified file.

## Format

> #include <stdio.h>

> int fflush (FILE *file_ptr);

## Argument

> ### file_ptr

> A file pointer. If this argument is a NULL pointer, all buffers associated with all currently open files are flushed.

## Description

> The output files are normally buffered only if they are not directed to a terminal, except for stderr, which is not buffered by default.

> The `fflush` function flushes the Compaq C RTL buffers. However, RMS has its own buffers. The `fflush` function does not guarantee that the file will be written to disk. (See the description of `fsync` for a way to flush buffers to disk.)

> If the file pointed to by file_ptr was opened in record mode and if there is unwritten data in the buffer, then `fflush` always generates a record.

## Return Values

> 0 | Indicates that the operation is successful.
> EOF | Indicates that the buffered data cannot be written to the file, or that the file control block is not associated with an output file.

# ffs

> Finds the index of the first bit set in a string.

## Format

> #include <strings.h>

> int ffs (int iteger);

## Arguments

> ### integer

> The integer to be examined for the first bit set.

## Description

> This function finds the first bit set (beginning with the least significant bit) and returns the index of that bit. Bits are numbered starting at 1 (the least significant bit).

## Return Values

> x | The index of the first bit set.
> 0 | If index is 0.

# fgetc

> Returns the next character from a specified file.

## Format

> #include <stdio.h>

> int fgetc (FILE *file_ptr);

## Argument

> ### file_ptr

> A pointer to the file to be accessed.

## Description

> See the `getc` macro in this section.

## Return Values

> x | The returned character.
> EOF | Indicates the end-of-file or an error.

# fgetname

> Returns the file specification associated with a file pointer.

## Format

> #include <stdio.h>

> char *fgetname (FILE *file_ptr, char *buffer, ...);

Function Variants This function also has variants named `_fgetname32` and `_fgetname64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### file_ptr

> A file pointer.

> ### buffer

> A pointer to a character string that is large enough to hold the file specification.

> ### ...

> An optional additional argument that can be either 1 or 0. If you specify 1, the `fgetname` function returns the file specification in OpenVMS format. If you specify 0, `fgetname` returns the file specification in UNIX style format. If you do not specify this argument, `fgetname` returns the file name according to your current command language interpreter. For more information about UNIX style file specifications, see Section 1.4.3.

## Description

> This function places the file specification at the address given in the buffer. The buffer should be an array large enough to contain a fully qualified file specification (the maximum length is 256 characters).

## Return Values

> n | The address of the buffer.
> 0 | Indicates an error.

## Restriction

> This function is specific to the Compaq C RTL and is not portable.

# fgetpos

> Stores the current file position for a given file.

## Format

> #include <stdio.h>

> int fgetpos (FILE *stream, 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

> This function stores the current value of the file position indicator for the stream pointed to by stream into the object pointed to by pos.

## Return Values

> 0 | Indicates successful completion.
> --1 | Indicates that there are errors.

## Example

>     #include <stdio.h>
>     #include <stdlib.h>

>     main()
>     {
>         FILE *fp;
>         int stat,
>             i;
>         int character;
>         char ch,
>              c_ptr[130],
>              d_ptr[130];
>         fpos_t posit;

>         /* Open a file for writing.  */

>         if ((fp = fopen("file.dat", "w+")) == NULL) {
>             perror("open");
>             exit(1);
>         }

>        /* Get the beginning position in the file.  */

>         if (fgetpos(fp, &posit) != 0)
>             perror("fgetpos");

>         /* Write some data to the file. */

>         if (fprintf(fp, "this is a test\n") == 0) {
>             perror("fprintf");
>             exit(1);
>         }

>         /* Set the file position back to the beginning. */

>         if (fsetpos(fp, &posit) != 0)
>             perror("fsetpos");

>         fgets(c_ptr, 130, fp);
>         puts(c_ptr);        /* Should be "this is a test."  */

>         /* Close the file. */

>         if (fclose(fp) != 0) {
>             perror("close");
>             exit(1);
>         }

>     }

# fgets

> Reads a line from the specified file, up to one less than the specified maximum number of characters or up to and including the new-line character, whichever comes first. The function stores the string in str.

## Format

> #include <stdio.h>

> char *fgets (char *str, int maxchar, FILE *file_ptr);

Function Variants This function also has variants named `_fgets32` and `_fgets64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### str

> A pointer to a character string that is large enough to hold the information fetched from the file.

> ### maxchar

> The maximum number of characters to fetch.

> ### file_ptr

> A file pointer.

## Description

> This function terminates the line with a null character (\0). Unlike `gets` , `fgets` places the new-line character that terminates the input line into the user buffer if more than maxchar characters have not already been fetched.

> When the file pointed to by file_ptr is opened in record mode, `fgets` treats the end of a record the same as a new-line character, so it reads up to and including a new-line character or to the end of the record.

## Return Values

> x | Pointer to str.
> NULL | Indicates the end-of-file or an error. The contents of str are undefined if a read error occurs.

## Example

>     #include <stdio.h>
>     #include <stdlib.h>
>     #include <unixio.h>

>     main()
>     {
>         FILE *fp;
>         char c_ptr[130];

>         /* Create a dummy data file  */

>         if ((fp = fopen("file.dat", "w+")) == NULL) {
>             perror("open");
>             exit(1);
>         }

>         fprintf(fp, "this is a test\n") ;
>         fclose(fp) ;

>         /* Open a file with some data -"this is a test"   */

>         if ((fp = fopen("file.dat", "r+")) == NULL) {
>            perror("open error") ;
>             exit(1);
>         }

>         fgets(c_ptr, 130, fp);
>         puts(c_ptr);        /* Display what fgets got.  */
>         fclose(fp);

>         delete("file.dat") ;
>     }

# fgetwc

> Reads the next character from a specified file, and converts it to a wide-character code.

## Format

> #include <wchar.h>

> wint_t fgetwc (FILE *file_ptr);

## Arguments

> ### file_ptr

> A pointer to the file to be accessed.

## Description

> Upon successful completion, the `fgetwc` function returns the wide-character code read from the file pointed to by file_ptr and converted to type `wint_t` . If the file is at end-of-file, the end-of-file indicator is set, and WEOF is returned. If an I/O read error occurred, then the error indicator is set, and WEOF is returned.

> Applications can use `ferror` or `feof` to distinguish between an error condition and an end-of-file condition.

## Return Values

> x | The wide-character code of the character read.
> WEOF | Indicates the end-of-file or an error. If a read error occurs, the function sets `errno` to one of the following: EALREADY -- An operation is already in progress on the same file. EBADF -- The file descriptor is not valid. EILSEQ -- Invalid character detected.

# fgetws

> Reads a line of wide characters from a specified file.

## Format

> #include <wchar.h>

> wchar_t *fgetws (wchar_t *wstr, int maxchar, FILE *file_ptr);

Function Variants This function also has variants named `_fgetws32` and `_fgetws64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### wstr

> A pointer to a wide-character string large enough to hold the information fetched from the file.

> ### maxchar

> The maximum number of wide characters to fetch.

> ### file_ptr

> A file pointer.

## Description

> This function reads wide characters from the specified file and stores them in the array pointed to by wstr. The function reads up to maxchar-1 characters or until the newline character is read, converted, and transferred to wstr, or until an end-of-file condition is encountered. The function terminates the line with a null wide character. `fgetws` places the newline that terminates the input line into the user buffer, unless maxchar characters have already been fetched.

## Return Values

> x | Pointer to wstr.
> NULL | Indicates the end-of-file or an error occurred. The contents of wstr are undefined if a read error occurs. If a read error occurs, the function sets `errno` . For a list of possible `errno` values, see `fgetwc` in this section.

## Example

>     #include <stdlib.h>
>     #include <stdio.h>
>     #include <locale.h>
>     #include <wchar.h>

>     main()
>     {
>         wchar_t wstr[80],
>                *ret;
>         FILE *fp;

>         /* Create a dummy data file  */

>         if ((fp = fopen("file.dat", "w+")) == NULL) {
>             perror("open");
>             exit(1);
>         }

>         fprintf(fp, "this is a test\n") ;
>         fclose(fp) ;

>        /* Open a test file containing : "this is a test" */

>         if ((fp = fopen("file.dat", "r")) == (FILE *) NULL) {
>             perror("File open error");
>             exit(EXIT_FAILURE);
>         }

>         ret = fgetws(wstr, 80, fp);
>         if (ret == (wchar_t *) NULL) {
>             perror("fgetws failure");
>             exit(EXIT_FAILURE);
>         }

>         fputws(wstr, stdout);
>         fclose(fp);
>         delete("file.dat");
>     }

# fileno

> Returns the file descriptor associated with the specified file pointer.

## Format

> #include <stdio.h>

> int fileno (FILE *file_ptr);

## Argument

> ### file_ptr

> A file pointer.

## Description

> If you are using DEC C Version 5.2 or lower, undefine the `fileno` macro:

>     #if defined(fileno)
>     #undef fileno
>     #endif

## Return Value

> x | Integer file descriptor.
> --1 | Indicates an error.

# floor

> Returns (as a `double` ) the largest integer that is less than or equal to its argument.

## Format

> #include <math.h>

> double floor (double x);

## Argument

> ### x

> A real value.

# fmod

> Computes the floating-point remainder of the first argument divided by the second. If the second argument is 0, the function returns 0.

## Format

> #include <math.h>

> double fmod (double x, double y);

## Arguments

> ### x

> A real value.

> ### y

> A real value.

## Return Values

> 0 | Indicates that y is 0.
> x | The value f, which has the same sign as the argument x, such that x == i * y + f for some integer i, where the magnitude of f is less than the magnitude of y.

# fopen

> Opens a file by returning the address of a FILE structure.

## Format

> #include <stdio.h>

> FILE *fopen (const char *file_spec, const char *a_mode); (ANSI C)

> FILE *fopen (const char *file_spec, const char *a_mode, ...); (DEC C EXTENSION)

## Arguments

> ### file_spec

> A character string containing a valid file specification.

> ### a_mode

> The access mode indicator. Use one of the following character strings: "r", "w", "a", "r+", "w+", "rb", "r+b", "rb+", "wb", "w+b", "wb+", "ab", "a+b", "ab+", or "a+".

> These access modes have the following effects:

> - "r" opens an existing file for reading.
> - "w" creates a new file, if necessary, and opens the file for writing. If the file exists, it creates a new file with the same name and a higher version number.
> - "a" opens the file for append access. An existing file is positioned at the end-of-file, and data is written there. If the file does not exist, the Compaq C RTL creates it.

> The update access modes allow a file to be opened for both reading and writing. When used with existing files, "r+" and "a+" differ only in the initial positioning within the file. The modes are as follows:

> - "r+" opens an existing file for read update access. It is opened for reading, positioned first at the beginning-of-file, but writing is also allowed.
> - "w+" opens a new file for write update access.
> - "a+" opens a file for append update access. The file is first positioned at the end-of-file (writing). If the file does not exist, the Compaq C RTL creates it.
> - "b" means binary access mode. In this case, no conversion of carriage-control information is attempted.

> ### ...

> Optional file attribute arguments. The file attribute arguments are the same as those used in the `creat` function. For more information, see the `creat` function.

## Description

> If a version of the file exists, a new file created with `fopen` inherits certain attributes from the existing file unless those attributes are specified in the `fopen` call. The following attributes are inherited:

> > Record format
> > Maximum record size
> > Carriage control
> > File protection.

> If you specify a directory in the file name and it is a search list that contains an error, Compaq C for OpenVMS Systems interprets it as a file open error.

> The file control block can be freed with the `fclose` function, or by default on normal program termination.

## Return Values

> x | File pointer.
> NULL | Indicates an error. The constant NULL is defined in the `<stdio.h>` header file to be the NULL pointer value. The function returns NULL to signal the following errors: File protection violations Attempts to open a nonexistent file for read access Failure to open the specified file

# fp_class, fp_classf, fp_classl (ALPHA ONLY)

> Determine the class of IEEE floating-point values.

## Format

> #include <math.h>

> int fp_class (double x);

> int fp_classf (float x);

> int fp_classl (long double x);

## Arguments

> ### x

> An IEEE floating-point number.

## Description

> These functions determine the class of the specified IEEE floating-point number, returning a constant from the `<fp_class.h>` header file. They never cause an exception, even for signaling NaNs (Not-a-Number). These functions implement the recommended `class(x)` function in the appendix of the IEEE 754-1985 standard for binary floating-point arithmetic. The constants in `<fp_class.h>` refer to the following classes of values:

> FP_SNAN | Signaling NaN (Not-a-Number)
> FP_QNAN | Quiet NaN
> FP_POS_INF | +infinity
> FP_NEG_INF | --infinity
> FP_POS_NORM | positive normalized
> FP_NEG_NORM | negative normalized
> FP_POS_DENORM | positive denormalized
> FP_NEG_DENORM | negative denormalized
> FP_POS_ZERO | +0.0 (positive zero)
> FP_NEG_ZERO | --0.0 (negative zero)

## Return Values

> x | A constant from the `<fp_class.h>` header file.

Previous | Next | Contents | Index

privacy and legal statement