United States    
COMPAQ
Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

fpathconf

Retrieves file implementation characteristics.

Format

#include <unistd.h>

long int fpathconf (int filedes, int name);

Arguments

filedes

An open file descriptor.

name

The configuration attribute to query. If this attribute is not applicable to the file specified by the filesdes argument, fpathconf returns an error.

Description

This function allows an application to retrieve the characteristics of operations supported by the file system underlying the file named by the filesdes argument. Read, write, or execute permission of the named file is not required, but you must be able to search all directories in the path leading to the file.

Symbolic values for the name argument are defined in the <unistd.h> header file as follows:
_PC_LINK_MAX The maximum number of links to the file. If the filedes argument refers to a directory, the value returned applies to the directory itself.
_PC_MAX_CANON The maximum number of bytes in a canonical input line. This is applicable only to terminal devices.
_PC_MAX_INPUT The number of types allowed in an input queue. This is applicable only to terminal devices.
_PC_NAME_MAX Maximum number of bytes in a filename (not including a terminating null). The byte range value is between 13 and 255. This is applicable only to a directory file. The value returned applies to filenames within the directory.
_PC_PATH_MAX Maximum number of bytes in a pathname (not including a terminating null). The value is never larger than 65,535. This is applicable only to a directory file. The value returned is the maximum length of a relative pathname when the specified directory is the working directory.
_PC_PIPE_BUF Maximum number of bytes guaranteed to be written atomically. This is applicable only to a FIFO. The value returned applies to the referenced object. If the path argument refers to a directory, the value returned applies to any FIFO that exists or can be created within the directory.
_PC_CHOWN_RESTRICTED The value returned applies to any files (other than directories) that exist or can be created within the directory. This is applicable only to a directory file.
_PC_NO_TRUNC Returns 1 if supplying a component name longer than allowed by NAME_MAX causes an error. Returns 0 (zero) if long component names are truncated. This is applicable only to a directory file.
_PC_VDISABLE This is always 0 (zero); no disabling character is defined. This is applicable only to a terminal device.

Return Values

x The resultant value for the configuration attribute specified in the name argument.
--1 Indicates an error; errno is set to one of the following values:
  • EINVAL -- The name argument specifies an unknown or inapplicable characteristic.
  • EBADF -- the filedes argument is not a valid file descriptor.

fprintf

Performs formatted output to a specified file.

Format

#include <stdio.h>

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

Arguments

file_ptr

A pointer to the file to which the output is directed.

format_spec

A pointer to a character string that contains the format specification. For more information on format specifications and conversion characters, 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

An example of a conversion specification follows: 


#include <stdio.h> 
 
main() 
{ 
   int  temp = 4, temp2 = 17; 
 
   fprintf(stdout, "The answers are %d, and %d.", temp, temp2); 
}

Sample output (to the stdout file) from the previous example is as follows: 


The answers are 4, and 17.

For a complete description of the format specification and the output source, see Chapter 2.

Return Values

x The number of bytes written, excluding the null terminator.
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 -- Non-translatable 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 -- Non-translatable 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.

fputc

Writes a character to a specified file.

Format

#include <stdio.h>

int fputc (int character, FILE *file_ptr);

Arguments

character

An object of type int .

file_ptr

A file pointer.

Description

This function writes a single character to a file and returns the character. See also putc in this section.

Return Values

x The character written to the file. Indicates success.
EOF Indicates an output error.

fputs

Writes a character string to a file without copying the string's null terminator (\0).

Format

#include <stdio.h>

int fputs (const char *str, FILE *file_ptr);

Arguments

str

A pointer to a character string.

file_ptr

A file pointer.

Description

See also puts in this section. Unlike puts , the fputs function does not append a new-line character to the output string.

Return Values

Nonnegative value Indicates success.
EOF Indicates an error.

fputwc

Converts a wide character to its corresponding multibyte value, and writes the result to a specified file.

Format

#include <wchar.h>

wint_t fputwc (wint_t wc, FILE *file_ptr);

Arguments

wc

An object of type wint_t .

file_ptr

A file pointer.

Description

This function writes a wide character to a file and returns the character. See also putwc in this section.

Return Values

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 -- Non-translatable 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.

fputws

Writes a wide-character string to a file without copying the null terminating character.

Format

#include <wchar.h>

int fputws (const wchar_t *wstr, FILE *file_ptr);

Arguments

wstr

A pointer to a wide-character string.

file_ptr

A file pointer.

Description

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

Return Values

Nonnegative value Indicates success.
--1 Indicates an error. The function sets errno . For a list of the values see fputwc in this section.

fread

Reads a specified number of items from the file.

Format

#include <stdio.h>

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

Arguments

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.

Description

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


typedef unsigned int size_t

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

Return Values

n The number of bytes read divided by size_of_item.
0 Indicates the end-of-file or an error.

free

Makes available for reallocation the area allocated by a previous calloc , malloc , or realloc call.

Format

#include <stdlib.h>

void free (void *ptr);

Argument

ptr

The address returned by a previous call to malloc , calloc , or realloc . If ptr is a NULL pointer, no action occurs.

Description

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 Compaq C RTL have declared free to return an int , the implementation of free does return 0 on success and --1 on failure.

freopen

Substitutes the file named by a file specification for the open file addressed by a file pointer. The latter file is closed.

Format

#include <stdio.h>

FILE *freopen (const char *file_spec, const char *a_mode, FILE *file_ptr, ...);

Arguments

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 in this section 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.

Description

This 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.

Return Values

file_ptr The file pointer, if freopen is successful.
NULL Indicates an error.

frexp

Calculates the fractional and exponent parts of a double value.

Format

#include <math.h>

double frexp (double value, int *eptr);

Arguments

value

An object of type double .

eptr

A pointer to an int , to which frexp returns the exponent.

Description

This function converts value to the following form: 


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 5 . The example produces the following output: 


fraction = 0.500000 
exp = 5

Return Value

x The fractional part of the double value.

fscanf

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 -- Non-translatable VMS error. vaxc$errno contains the VMS 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 -- Non-translatable 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.

fseek

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

This function can position 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:

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 in this section.

Return Values

0 Indicates successful seeks.
--1 Indicates improper seeks.

Previous Next Contents Index
  

1.800.AT.COMPAQ

privacy and legal statement