[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


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.

ferror_unlocked (ALPHA, I64)

Same as ferror , except used only within a scope protected by flockfile and funlockfile .

Format

#include <stdio.h>

int ferror_unlocked (FILE *file_ptr);


Argument

file_ptr

A file pointer.

Description

The reentrant version of the ferror function is locked against multiple threads calling it simultaneously. This incurs overhead to ensure integrity of the stream. The unlocked version of this call, ferror_unlocked can be used to avoid the overhead. The ferror_unlocked function is functionally identical to the ferror function, except that it is not required to be implemented in a thread-safe manner. The ferror_unlocked function can be safely used only within a scope that is protected by the flockfile and funlockfile functions used as a pair. The caller must ensure that the stream is locked before ferror_unlocked is used.

See also flockfile , ftrylockfile , and funlockfile .


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


Argument

integer

The integer to be examined for the first bit set.

Description

The ffs 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

The fgetc function returns the next character from the specified file.

Compiling with the __UNIX_PUTC macro defined enables an optimization that uses a faster, inlined version of this function.

See also the fgetc_unlocked function and the getc macro.


Return Values

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

fgetc_unlocked (ALPHA, I64)

Same as the fgetc function, except used only within a scope protected by flockfile and funlockfile .

Format

#include <stdio.h>

int fgetc_unlocked (FILE *file_ptr);


Argument

file_ptr

A file pointer.

Description

The reentrant version of the fgetc function is locked against multiple threads calling it simultaneously. This incurs overhead to ensure integrity of the stream. The unlocked version of this call, fgetc_unlocked can be used to avoid the overhead. The fgetc_unlocked function is functionally identical to the fgetc function, except that fgetc_unlocked can be safely used only within a scope that is protected by the flockfile and funlockfile functions used as a pair. The caller must ensure that the stream is locked before fgetc_unlocked is used.

Compiling with the __UNIX_PUTC macro defined enables an optimization that uses a faster, inlined version of this function.

See also getc_unlocked , flockfile , ftrylockfile , and funlockfile .


Return Values

n 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 The fgetname function has variants named _fgetname32 and _fgetname64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 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

The fgetname 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

The fgetname function is specific to the HP 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

The fgetpos 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 The fgets function has variants named _fgets32 and _fgets64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 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

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


Argument

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 The fgetws function has variants named _fgetws32 and _fgetws64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 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

The fgetws 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 new-line 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 new-line 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. 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 .

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 version 5.2 or lower of the C compiler, undefine the fileno macro:


#if defined(fileno)
#undef fileno
#endif

Return Values

x Integer file descriptor.
- 1 Indicates an error.

finite (ALPHA, I64)

Returns the integer value 1 (TRUE) when its argument is a finite number, or 0 (FALSE) if not.

Format

#include <math.h>

int finite (double x);

int finitef (float x);

int double finitel (long double x);


Argument

x

A real value.

Description

The finite functions return 1 when - Infinity < x < +Infinity. They return 0 when |x| = Infinity, or x is a NaN.

flockfile (ALPHA, I64)

Locks a stdio stream.

Format

#include <stdio.h>

void flockfile (FILE *file_ptr);


Argument

file_ptr

A file pointer.

Description

The flockfile function locks a stdio stream so that a thread can have exclusive use of that stream for multiple I/O operations. Use the flockfile function for a thread that wants to ensure that the output of several printf functions, for example, is not garbled by another thread also trying to use printf .

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 ftrylockfile and funlockfile .


floor

Returns the largest integer less than or equal to the argument.

Format

#include <math.h>

double floor (double x);

float floorf (float x); (ALPHA, I64)

long double floorl (long double x); (ALPHA, I64)


Argument

x

A real value.

Return Value

n The largest integer less than or equal to the argument.


Previous Next Contents Index