United States

Compaq C

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

Previous | Contents | Index

# execlp

> Passes the name of an image to be activated in a child process. This function is nonreentrant.

## Format

> #include <unistd.h>

> int execlp (const char *file_name, const char *arg0, ..., (char *)0); (ISO POSIX-1)

> int execlp (char *file_name, ...); (COMPATABILITY)

## Arguments

> ### file_name

> The file name of a new image to be activated in the child process. The device and directory specification for the file is obtained by searching the environment name VAXC$PATH.

> ### argn

> A sequence of pointers to null-terminated character strings. By convention, at least one argument must be present and must point to a string that is the same as the new process file name (or its last component).

> ### ...

> A sequence of pointers to strings. At least one pointer must exist to terminate the list. This pointer must be the NULL pointer.

## Description

> See `execl` in this section for a description of how the exec functions operate.

## Return Value

> --1 | Indicates failure.

# execv

> Passes the name of an image to be activated in a child process. This function is nonreentrant.

## Format

> #include <unistd.h>

> int execv (char *file_spec, char *argv[]);

## Arguments

> ### file_spec

> The full file specification of a new image to be activated in the child process.

> ### argv

> An array of pointers to null-terminated character strings. These strings constitute the argument list available to the new process. By convention, argv[0] must point to a string that is the same as the new process file name (or its last component). argv is terminated by a NULL pointer.

## Description

> See `execl` in this section for a description of how the exec functions operate.

## Return Value

> --1 | Indicates failure.

# execve

> Passes the name of an image to be activated in a child process. This function is nonreentrant.

## Format

> #include <unistd.h>

> int execve (const char *file_spec, char *argv[], char *envp[]);

## Arguments

> ### file_spec

> The full file specification of a new image to be activated in the child process.

> ### argv

> An array of pointers to null-terminated character strings. These strings constitute the argument list available to the new process. By convention, argv[0] must point to a string that is the same as the new process file name (or its last component). argv is terminated by a NULL pointer.

> ### envp

> An array of strings that specifies the program's environment. Each string in envp has the following form:

> `name = value`

> The name can be one of the following names and the value is a null-terminated string to be associated with the name:

> - HOME---Your login directory
> - TERM---The type of terminal being used
> - PATH---The default device and directory
> - USER---The name of the user who initiated the process

> The last element in envp must be the NULL pointer.

> When the operating system executes the program, it places a copy of the current environment vector (envp) in the external variable `environ` .

## Description

> See `execl` in this section for a description of how the exec functions operate.

## Return Value

> --1 | Indicates failure.

# execvp

> Passes the name of an image to be activated in a child process. This function is nonreentrant.

## Format

> #include <unistd.h>

> int execvp (const char *file_name, char *argv[]);

## Arguments

> ### file_name

> The file name of a new image to be activated in the child process. The device and directory specification for the file is obtained by searching the environment name VAXC$PATH.

> ### argv

> An array of pointers to null-terminated character strings. These strings constitute the argument list available to the new process. By convention, argv[0] must point to a string that is the same as the new process file name (or its last component). argv is terminated by a NULL pointer.

## Description

> See `execl` in this section for a description of how the exec functions operate.

## Return Value

> --1 | Indicates failure.

# exit, _exit

> Terminate execution of the program from which they are called. These functions are nonreentrant.

## Format

> #include <stdlib.h>

> void exit (int status);

> #include <unistd.h>

> void _exit (int status);

## Argument

> ### status

> A status value of EXIT_SUCCESS (0), EXIT_FAILURE (1), or a number from 2 to 255:
> - A status value of 0 or EXIT_SUCCESS is translated to the OpenVMS SS$_NORMAL status code to return the OpenVMS success value.
> - A status value of 1 or EXIT_FAILURE is translated to an error-level exit status. The status value is passed to the parent process.
> - Any other status value is left the same.

> To use these status values as described, include `<unistd.h>` and compile with the `_POSIX_EXIT` feature-test macro set (either with /DEFINE=_POSIX_EXIT or with `#define _POSIX_EXIT` at the top of your file, before any file inclusions). This behavior is available only on OpenVMS Version 7.0 and higher systems.

## Description

> If the process was invoked by the DIGITAL Command Language (DCL), the status is interpreted by DCL and a message is displayed.

> If the process was a child process created using `vfork` or an exec function, then the child process exits and control returns to the parent. The two functions are identical; the `_exit` function is retained for reasons of compatibility with VAX C.

> The `exit` and `_exit` functions make use of the $EXIT system service. If your process is being invoked by the RUN command using any of the hibernation and scheduled wakeup qualifiers, the process might not correctly return to hibernation state when an `exit` or `_exit` call is made.

> Note EXIT_SUCCESS and EXIT_FAILURE are portable across any ANSI C compiler to indicate success or failure. On OpenVMS systems, they are mapped to OpenVMS condition codes with the severity set to success or failure, respectively. Values in the range of 2 to 255 can be used by a child process to communicate a small amount of data to the parent. The parent retreives this data using the `wait` , `wait3` , `wait4` , or `waitpid` functions.

# exp

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

## Format

> #include <math.h>

> double exp (double x);

## Argument

> ### x

> A real value.

## Description

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

## Return Value

> x | The base e raised to the power of the argument.
> HUGE_VAL | Indicates overflow; `errno` is set to ERANGE.

# fabs

> Returns the absolute value of a floating-point value.

## Format

> #include <math.h>

> double fabs (double x);

## 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 VMS 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 parameter.

## Description

> The `fcntl` function performs controlling operations on the open file specified by the file_desc parameter.

> The values for the request parameter 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);
> The following call
>     fid = dup2(file_desc, file_desc2);
> 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 parameter 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 (zero), 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 parameter as follows: F_DUPFD -- Returns a new file descriptor. F_GETFD -- Returns FD_CLOEXEC or 0 (zero). F_SETFD -- Returns a value other than --1.
> --1 | Indicates that an error occurred. The function sets errno to the following value: EBADF -- The file_desc parameter is not a valid open file descriptor and the argument parameter file descriptor is negative or greater than or equal to the per-process limit. EFAULT -- The argument parameter is an invalid address. EINVAL -- The request parameter is F_DUPFD and the argument parameter 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 parameter. EMFILE -- The request parameter is F_DUPFD and too many or OPEN_MAX file descriptors are currently open in the calling process, or no file descriptors greater than or equal to 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 Compaq 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

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

## 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 in this section for a description. Note that the access mode specified must agree with the mode used to open the file originally. This includes binary/text access mode ("b" mode on `fdopen` and the "ctx=bin" option on `creat` or `open` ).

## Description

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

Previous | Next | Contents | Index

privacy and legal statement