+.\" 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
projects / unix-history / commitdiff