HP OpenVMS Systems Documentation

Content starts here HP C

HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


exp

Returns the base e raised to the power of the argument.

Format

#include <math.h>

double exp (double x);

float expf (float x); (ALPHA ONLY)

long double expl (long double x); (ALPHA ONLY)

double expm1 (double x); (ALPHA ONLY)

float expm1f (float x); (ALPHA ONLY)

long double expm1l (long double x); (ALPHA ONLY)


Argument

x

A real value.

Description

The exp functions compute the value of the exponential function, defined as e**x, where e is the constant used as a base for natural logarithms.

The expm1 functions compute exp(x) - 1 accurately, even for tiny x.

If an overflow occurs, the exp functions return the largest possible floating-point value and set errno to ERANGE. The constant HUGE_VAL is defined in the <math.h> header file to be the largest possible floating-point value.


Return Values

x The exponential value of the argument.
HUGE_VAL Overflow occurred; errno is set to ERANGE.
0 Underflow occurred; errno is set to ERANGE.
NaN x is NaN; errno is set to EDOM.

fabs

Returns the absolute value of its argument.

Format

#include <math.h>

double fabs (double x);

float fabsf (float x); (ALPHA ONLY)

long double fabsl (long double x); (ALPHA ONLY)


Argument

x

A real value.

Return Value

x The absolute value of the argument.

fchown

Changes the owner and group of a file.

Format

#include <unistd.h>

int fchown (int fildes, uid_t owner, gid_t group);


Arguments

fildes

An open file descriptor.

owner

A user ID corresponding to the new owner of the file.

group

A group ID corresponding to the group of the file.

Description

The fchown function has the same effect as chown except that the file whose owner and group are to be changed is specified by the file descriptor fildes.

Return Values

0 Indicates success.
- 1 Indicates failure. The function sets errno to one of the following values:

The fchown function will fail if:

  • EBADF -- The fildes argument is not an open file descriptor.
  • EPERM -- The effective user ID does not match the owner of the file, or the process does not have appropriate privilege.
  • EROFS -- The file referred to by fildes resides on a read-only file system.

The fchown function may fail if:

  • EINVAL -- The owner or group ID is not a value supported by the implementation.
  • EIO -- A physical I/O error has occurred.
  • EINTR -- The fchown function was interrupted by a signal that was caught.

fclose

Closes a file by flushing any buffers associated with the file control block and freeing the file control block and buffers previously associated with the file pointer.

Format

#include <stdio.h>

int fclose (FILE *file_ptr);


Argument

file_ptr

A pointer to the file to be closed.

Description

When a program terminates normally, the fclose function is automatically called for all open files.

The fclose function tries to write buffered data by using an implicit call to fflush .

If the write fails (because the disk is full or the user's quota is exceeded, for example), fclose continues executing. It closes the OpenVMS channel, deallocates any buffers, and releases the memory associated with the file descriptor (or FILE pointer). Any buffered data is lost, and the file descriptor (or FILE pointer) no longer refers to the file.

If your program needs to recover from errors when flushing buffered data, it should make an explicit call to fsync (or fflush ) before calling fclose .


Return Values

0 Indicates success.
EOF Indicates that the file control block is not associated with an open file.

fcntl

Performs controlling operations on an open file.

Format

#include <sys/types.h>

#include <unistd.h>

#include <fcntl.h>

int fcntl (int file_desc, int request [, int file_desc2]);


Arguments

file_desc

An open file descriptor obtained from a successful open , fcntl , or pipe function.

request

The operation to be performed.

file_desc2

A variable that depends on the value of the request argument.

Description

The fcntl function performs controlling operations on the open file specified by the file_desc argument.

The values for the request argument are defined in the header file <fcntl.h> , and include the following:

F_DUPFD Returns a new file descriptor that is the lowest numbered available (that is, not already open) file descriptor greater than or equal to the third argument ( file_desc2) taken as an integer of type int .

The new file descriptor refers to the same file as the original file descriptor ( file_desc). The FD_CLOEXEC flag associated with the new file descriptor is cleared to keep the file open across calls to one of the exec functions.

The following two calls are equivalent:

fid = dup(file_desc);

fid = fcntl(file_desc, F_DUPFD, 0);

Consider the following call:

fid = dup2(file_desc, file_desc2);

It is similar (but not equivalent) to:

close(file_desc2);

fid = fcntl(file_desc, F_DUPFD, file_desc2);
F_GETFD Gets the value of the close-on-exec flag associated with the file descriptor file_desc. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. The file_desc2 argument should not be specified.
F_SETFD Sets the close-on-exec flag associated with file_desc to the value of the third argument, taken as type int .

If the third argument is 0, the file remains open across the exec functions, which means that a child process spawned by the exec function inherits this file descriptor from the parent.

If the third argument is FD_CLOEXEC , the file is closed on successful execution of the next exec function, which means that the child process spawned by the exec function will not inherit this file descriptor from the parent.


Return Values

n Upon successful completion, the value returned depends on the value of the request argument as follows:
  • F_DUPFD -- Returns a new file descriptor.
  • F_GETFD -- Returns FD_CLOEXEC or 0.
  • F_SETFD -- Returns a value other than - 1.
- 1 Indicates that an error occurred. The function sets errno to one of the following values:
  • EBADF -- The file_desc argument is not a valid open file descriptor and the file_desc2 argument is negative or greater than or equal to the per-process limit.
  • EFAULT -- The file_desc2 argument is an invalid address.
  • EINVAL -- The request argument is F_DUPFD and the file_desc2 argument is negative or greater than or equal to OPEN_MAX.

    Either the OPEN_MAX value or the per-process soft descriptor limit is checked.

    An illegal value was provided for the request argument.

  • EMFILE -- The request argument is F_DUPFD and OPEN_MAX file descriptors are currently open in the calling process, or no file descriptors greater than or equal to the file_desc2 argument are available.

    Either the OPEN_MAX value or the per-process soft descriptor limit is checked.

  • ENOMEM -- The system was unable to allocate memory for the requested file descriptor.

fcvt

Converts its argument to a null-terminated string of ASCII digits and returns the address of the string. The string is stored in a thread-specific location created by the HP C RTL.

Format

#include <stdlib.h>

char *fcvt (double value, int ndigits, int *decpt, int *sign);


Arguments

value

An object of type double that is converted to a null-terminated string of ASCII digits.

ndigits

The number of ASCII digits after the decimal point to be used in the converted string.

decpt

The position of the decimal point relative to the first character in the returned string. The returned string does not contain the actual decimal point. A negative int value means that the decimal point is decpt number of spaces to the left of the returned digits (the spaces are filled with zeros). A 0 value means that the decimal point is immediately to the left of the first digit in the returned string.

sign

An integer value that indicates whether the value argument is positive or negative. If value is negative, the fcvt function places a nonzero value at the address specified by sign. Otherwise, the functions assign 0 to the address specified by sign.

Description

The fcvt function converts value to a null-terminated string and returns a pointer to it. The resulting low-order digit is rounded to the correct digit for outputting ndigits digits in C F-format. The decpt argument is assigned the position of the decimal point relative to the first character in the string.

In C F-format, ndigits is the number of digits desired after the decimal point. Very large numbers produce a very long string of digits before the decimal point, and ndigit of digits after the decimal point. For large numbers, it is preferable to use the gcvt or ecvt function so that E-format is used.

Repeated calls to the fcvt function overwrite any existing string.

The ecvt , fcvt , and gcvt functions represent the following special values specified in the IEEE Standard for floating-point arithmetic:

Value Representation
Quiet NaN NaNQ
Signalling NaN NaNS
+Infinity Infinity
- Infinity - Infinity

The sign associated with each of these values is stored into the sign argument. In IEEE floating-point representation, a value of 0 (zero) can be positive or negative, as set by the sign argument.

See also gcvt and ecvt .


Return Value

x A pointer to the converted string.

fdopen

Associates a file pointer with a file descriptor returned by an open , creat , dup , dup2 , or pipe function.

Format

#include <stdio.h>

FILE *fdopen (int file_desc, char *a_mode);


Arguments

file_desc

The file descriptor returned by open , creat , dup , dup2 , or pipe .

a_mode

The access mode indicator. See the fopen function for a description. Note that the access mode specified must agree with the mode used to originally open the file. This includes binary/text access mode ("b" mode on fdopen and the "ctx=bin" option on creat or open ).

Description

The fdopen function allows you to access a file, originally opened by one of the UNIX I/O functions, with Standard I/O functions. Ordinarily, a file can be accessed by either a file descriptor or by a file pointer, but not both, depending on the way you open it. For more information, see Chapters 1 and 2.

Return Values

pointer Indicates that the operation has succeeded.
NULL Indicates that an error has occurred.

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

See the getc macro.

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


Previous Next Contents Index