manual page distributed with 4.1BSD

[unix-history] / usr / src / lib / libc / sys / execve.2

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)execve.2	4.1 (Berkeley) %G%
.\"
.TH EXEC 2  4/1/81
.UC 4
.SH NAME
execl, execv, execle, execve, execlp, execvp, exec, exece, environ \- execute a file
.SH SYNOPSIS
.nf
.B execl(name, arg0, arg1, ..., argn, 0)
.B char *name, *arg0, *arg1, ..., *argn;
.PP
.B execv(name, argv)
.B char *name, *argv[];
.PP
.B "execle(name, arg0, arg1, ..., argn, 0, envp)"
.B "char *name, *arg0, *arg1, ..., *argn, *envp[];"
.PP
.B execve(name, argv, envp)
.B char *name, *argv[], *envp[];
.PP
.B extern char **environ;
.fi
.SH DESCRIPTION
.I 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
Files remain open across
.I exec
unless explicit arrangement has been made;
see
.IR ioctl (2).
Ignored/held signals remain ignored/held across
these calls, but
signals that are caught (see
.IR signal (2))
are reset
to their default values.
.PP
Each user has a
.I real
user ID and group ID and an
.I effective
user ID and group ID.
The
real
ID
identifies the person using the system;
the
effective
ID
determines his access privileges.
.I Exec
changes the effective user and group ID to
the owner of the executed file if the file has the `set-user-ID'
or `set-group-ID'
modes.
The
real
user ID is not affected.
.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
From C, two interfaces are available.
.I execl
is useful when a known file with known arguments is
being called;
the arguments to
.I 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 0 argument must end the argument list.
.PP
The
.I execv
version is useful when the number of arguments is unknown
in advance;
the arguments to
.I 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 0 pointer.
.PP
When a C program is executed,
it is called as follows:
.PP
.nf
	main(argc, argv, envp)
	int argc;
	char **argv, **envp;
.fi
.PP
where
.IR argc ""
is the argument count
and
.IR argv ""
is an array of character pointers
to the arguments themselves.
As indicated,
.IR 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
.I 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
.IR sh (1)
passes an environment entry for each global shell variable
defined when the program is called.
See
.IR environ (5)
for some conventionally
used names.
The C run-time start-off routine places a copy of
.I envp
in the global cell
.I environ,
which is used
by
.IR execv \ and \ execl
to pass the environment to any subprograms executed by the
current program.
The
.I exec
routines use lower-level routines as follows
to pass an environment explicitly:
.RS
.nf
execve(file, argv, environ);
execle(file, arg0, arg1, . . . , argn, 0, environ);
.fi
.RE
.PP
.I Execlp
and
.I execvp
are called with the same arguments as
.I execl
and
.I 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.
.PP
To aid execution of command files of various programs,
if the first two characters of the executable file are '#!' then
.I exec
attempts to read a pathname from the executable file and use
that program as the command files command interpreter. For example, the
following command file sequence would be used to begin a
.I csh
script:
.RS
.nf
#! /bin/csh
# This shell script computes the checksum on /dev/foobar
#
	...
.fi
.RE
A single parameter may be passed the interpreter, specified after the
name of the interpreter; its length and the length of the name
of the interpreter combined must not exceed 32 characters.
The space (or tab) following the '#!' is mandatory, and the
pathname must be explicit (no paths are searched).
.SH FILES
.ta \w'/bin/sh  'u
/bin/sh	shell, invoked if command file found
by
.I execlp
or
.I execvp
.SH "SEE ALSO"
fork(2), environ(5), csh(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
.IR 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.
Even for the super-user,
at least one of the execute-permission bits must be set for
a file to be executed.
.SH BUGS
If
.I execvp
is called to execute a file that turns out to be a shell
command file,
and if it is impossible to execute the shell,
the values of
.I argv[0]
and
.I argv[\-1]
will be modified before return.
.SH "ASSEMBLER (PDP-11)"
.DT
(exec = 11.)
.br
.B sys exec; name; argv
.PP
(exece = 59.)
.br
.B sys exece; name; argv; envp
.PP
Plain
.I exec
is obsoleted by
.I exece,
but remains for historical reasons.
.PP
When the called file starts execution on the PDP11,
the stack pointer points to a word containing the number of arguments.
Just above
this number is a list of pointers to the argument strings,
followed by a null pointer, followed by the pointers to
the environment strings and then another null pointer.
The strings themselves follow;
a 0 word is left at the very top of memory.
.PP
  sp\(->	nargs
.br
	arg0
.br
	...
.br
	argn
.br
	0
.br
	env0
.br
	...
.br
	envm
.br
	0
.PP
 arg0:	<arg0\e0>
.br
	...
.br
 env0:	<env0\e0>
.br
	0
.PP
On the Interdata 8/32,
the stack begins at a conventional place
(currently 0xD0000)
and grows upwards.
After
.I exec,
the layout of data on the stack is as follows.
.PP
.nf
	int	0
 arg0:	byte	...
	...
argp0:	int	arg0
	...
	int	0
envp0:	int	env0
	...
	int	0
 %2\(->	space	40
	int	nargs
	int	argp0
	int	envp0
 %3\(->
.fi
.PP
This arrangement happens to conform well to C calling conventions.
.PP
On a VAX-11, the stack begins at
.lg 0
0x7ffff000
.lg 1
and grows towards lower numbered addresses.
After
.IR exec ,
the layout of data on the stack is as follows.
.PP
.nf
.ta \w' arg0:  'u
 ap \(->
 fp \(->
 sp \(->	.long nargs
	.long arg0
	...
	.long argn
	.long 0
	.long env0
	...
	.long envn
	.long 0
 arg0:	.byte "arg0\e0"
	...
 envn:	.byte "envn\e0"
	.long 0