HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


execl

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

Format

#include <unistd.h>

int execl (const char *file_spec, const char *arg0, ..., (char *)0); (ISO POSIX-1)

int execl (char *file_spec, ...); (COMPATABILITY)


Arguments

file_spec

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

arg0, ...

A sequence of pointers to null-terminated character strings.

If the POSIX-1 format is used, 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). (This pointer can also be the NULL pointer, but then execle would accomplish nothing.) The last pointer must be the NULL pointer. This is also the convention if the compatibility format is used.


Description

To understand how the exec functions operate, consider how the OpenVMS system calls any HP C program, as shown in the following syntax:

int main (int argc, char *argv[], char *envp[]);

The identifier argc is the argument count; argv is an array of argument strings. The first member of the array (argv[0]) contains the name of the image. The arguments are placed in subsequent elements of the array. The last element of the array is always the NULL pointer.

An exec function calls a child process in the same way that the run-time system calls any other HP C program. The exec functions pass the name of the image to be activated in the child; this value is placed in argv[0]. However, the functions differ in the way they pass arguments and environment information to the child:

If vfork was called before invoking an exec function, then when the exec function completes, control is returned to the parent process at the point of the vfork call. If vfork was not called, the exec function waits until the child has completed execution and then exits the parent process. See vfork and Chapter 5 for more information.


Return Value

- 1 Indicates failure.

execle

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

Format

#include <unistd.h>

int execle (char *file_spec, char *arg0, ..., (char *)0, char *envp[]); (ISO POSIX-1)

int execle (char *file_spec, ...); (COMPATABILITY)


Arguments

file_spec

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

arg0, ...

A sequence of pointers to null-terminated character strings.

If the POSIX-1 format is used, 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). (This pointer can also be the NULL pointer, but then execle would accomplish nothing.) The last pointer must be the NULL pointer. This is also the convention if the compatibility format is used.

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:

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 for a description of how the exec functions operate.

Return Value

- 1 Indicates failure.

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 VAXC$PATH environment name.

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

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

For non-POSIX behavior, a status value of EXIT_SUCCESS (1), EXIT_FAILURE (2), or a number from 3 to 255, as follows:

For POSIX behavior:

To get POSIX behavior, 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 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.

The C compiler command-line qualifier /[NO]MAIN=POSIX_EXIT can be used to direct the compiler to call __posix_exit instead of exit when returning from main . The default is /NOMAIN.

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

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

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

double expm1 (double x); (ALPHA, I64)

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

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


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.

exp2 (ALPHA, I64)

Returns the value of 2 raised to the power of the argument.

Format

#include <math.h>

double exp2 (double x);

float exp2f (float x);

long double exp2l (long double x);

)


Argument

x

A real value.

Description

The exp2 functions compute the base-2 exponential of 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

n 2** x.
HUGE_VAL Overflow occurred; errno is set to ERANGE.
1 x is +0 or - 0; errno is set to ERANGE.
0 x is - Inf or underflow occurred; errno is set to ERANGE.
x x is +Inf; 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, I64)

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


Argument

x

A real value.

Return Value

x The absolute value of the argument.

fchmod

Changes file access permissions.

Format

#include <stat.h>

int fchmod (int fildes, mode_t mode);


Arguments

fildes

An open file descriptor.

mode

The bit pattern that determines the access permissions.

Description

The fchmod function is equivalent to the chmod function, except that the file whose permissions are changed is specified by a file descriptor (fildes) rather than a filename.

Return Values

0 Indicates that the mode is successfully changed.
- 1 Indicates that the change attempt has failed.

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.


Previous Next Contents Index