197 lines
4.5 KiB
Groff
197 lines
4.5 KiB
Groff
.\" Copyright (c) 1983 Regents of the University of California.
|
|
.\" All rights reserved. The Berkeley software License Agreement
|
|
.\" specifies the terms and conditions for redistribution.
|
|
.\"
|
|
.\" @(#)execl.3 6.2 (Berkeley) 4/25/86
|
|
.\"
|
|
.TH EXECL 3 "April 25, 1986"
|
|
.UC 5
|
|
.SH NAME
|
|
execl, execv, execle, execlp, execvp, exec, environ \- execute a file
|
|
.SH SYNOPSIS
|
|
.ft B
|
|
#include <unistd.h>
|
|
|
|
.in +.5i
|
|
.ti -.5i
|
|
int execl(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL)
|
|
.ti -.5i
|
|
int execv(const char *\fIname\fP, char *const \fIargv\fP[])
|
|
.ti -.5i
|
|
int execle(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL, char *const \fIenvp\fP[])
|
|
.ti -.5i
|
|
int execlp(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL)
|
|
.ti -.5i
|
|
int execvp(const char *\fIname\fP, char *const \fIargv\fP[])
|
|
.in -.5i
|
|
|
|
extern char *const *environ;
|
|
.fi
|
|
.SH DESCRIPTION
|
|
These routines provide various interfaces to the
|
|
.B execve
|
|
system call. Refer to
|
|
.BR execve (2)
|
|
for a description of their properties; only
|
|
brief descriptions are provided here.
|
|
.PP
|
|
.B Exec
|
|
in all its forms
|
|
overlays the calling process with the named file, then
|
|
transfers to the
|
|
entry point of the core image of the file.
|
|
There can be no return from a successful exec; the calling
|
|
core image is lost.
|
|
.PP
|
|
The
|
|
.I name
|
|
argument
|
|
is a pointer to the name of the file
|
|
to be executed.
|
|
The pointers
|
|
.IR arg [ 0 ],
|
|
.IR arg [ 1 "] ..."
|
|
address null-terminated strings.
|
|
Conventionally
|
|
.IR arg [ 0 ]
|
|
is the name of the
|
|
file.
|
|
.PP
|
|
Two interfaces are available.
|
|
.B execl
|
|
is useful when a known file with known arguments is
|
|
being called;
|
|
the arguments to
|
|
.B execl
|
|
are the character strings
|
|
constituting the file and the arguments;
|
|
the first argument is conventionally
|
|
the same as the file name (or its last component).
|
|
A null pointer argument must end the argument list.
|
|
(Note that the
|
|
.B execl*
|
|
functions are variable argument functions. This means that the type
|
|
of the arguments beyond
|
|
.I arg0
|
|
is not checked. So the null pointer requires an explicit cast to type
|
|
.B "(char *)"
|
|
if not of that type already.)
|
|
.PP
|
|
The
|
|
.B execv
|
|
version is useful when the number of arguments is unknown
|
|
in advance;
|
|
the arguments to
|
|
.B execv
|
|
are the name of the file to be
|
|
executed and a vector of strings containing
|
|
the arguments.
|
|
The last argument string must be followed
|
|
by a null pointer.
|
|
.PP
|
|
When a C program is executed,
|
|
it is called as follows:
|
|
.PP
|
|
.RS
|
|
.ft B
|
|
.nf
|
|
int main(int \fIargc\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]);
|
|
|
|
exit(main(\fIargc\fP, \fIargv\fP, \fIenvp\fP));
|
|
.fi
|
|
.ft R
|
|
.RE
|
|
.PP
|
|
where
|
|
.I argc
|
|
is the argument count
|
|
and
|
|
.I argv
|
|
is an array of character pointers
|
|
to the arguments themselves.
|
|
As indicated,
|
|
.I argc
|
|
is conventionally at least one
|
|
and the first member of the array points to a
|
|
string containing the name of the file.
|
|
.PP
|
|
.I Argv
|
|
is directly usable in another
|
|
.B execv
|
|
because
|
|
.IR argv [ argc ]
|
|
is 0.
|
|
.PP
|
|
.I Envp
|
|
is a pointer to an array of strings that constitute
|
|
the
|
|
.I environment
|
|
of the process.
|
|
Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value.
|
|
The array of pointers is terminated by a null pointer.
|
|
The shell
|
|
.BR sh (1)
|
|
passes an environment entry for each global shell variable
|
|
defined when the program is called.
|
|
See
|
|
.BR environ (7)
|
|
for some conventionally
|
|
used names.
|
|
The C run-time start-off routine places a copy of
|
|
.I envp
|
|
in the global cell
|
|
.BR environ ,
|
|
which is used
|
|
by
|
|
.B execv
|
|
and
|
|
.B execl
|
|
to pass the environment to any subprograms executed by the
|
|
current program.
|
|
.PP
|
|
.B Execlp
|
|
and
|
|
.B execvp
|
|
are called with the same arguments as
|
|
.B execl
|
|
and
|
|
.BR execv ,
|
|
but duplicate the shell's actions in searching for an executable
|
|
file in a list of directories.
|
|
The directory list is obtained from the environment variable
|
|
.BR PATH .
|
|
Under standard MINIX 3, if a file is found that is executable, but does
|
|
not have the proper executable header then it is assumed to be
|
|
a shell script.
|
|
.B Execlp
|
|
and
|
|
.B execvp
|
|
execute
|
|
.B /bin/sh
|
|
to interpret the script.
|
|
Under Minix-vmd this does not happen, a script must begin with
|
|
.B #!
|
|
and the full path name of the interpreter if it is to be an
|
|
executable script.
|
|
.SH "SEE ALSO"
|
|
.BR execve (2),
|
|
.BR fork (2),
|
|
.BR environ (7),
|
|
.BR sh (1).
|
|
.SH DIAGNOSTICS
|
|
If the file cannot be found,
|
|
if it is not executable,
|
|
if it does not start with a valid magic number (see
|
|
.BR a.out (5)),
|
|
if maximum memory is exceeded,
|
|
or if the arguments require too much space,
|
|
a return
|
|
constitutes the diagnostic;
|
|
the return value is \-1 and
|
|
.B errno
|
|
is set as for
|
|
.BR execve .
|
|
Even for the super-user,
|
|
at least one of the execute-permission bits must be set for
|
|
a file to be executed.
|