manual page distributed with 4.2BSD

SCCS-vsn: lib/libc/sys/execve.2 5.1

diff --git a/usr/src/lib/libc/sys/execve.2 b/usr/src/lib/libc/sys/execve.2
index 62ecb73..dc3cf78 100644 (file)
--- a/usr/src/lib/libc/sys/execve.2
+++ b/usr/src/lib/libc/sys/execve.2
@@ -2,112 +2,108 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)execve.2    4.1 (Berkeley) %G%
+.\"    @(#)execve.2    5.1 (Berkeley) %G%

 .\"
 .\"

-.TH EXEC 2  4/1/81
+.TH EXECVE 2 "27 July 1983"

 .UC 4
 .SH NAME
 .UC 4
 .SH NAME

-execl, execv, execle, execve, execlp, execvp, exec, exece, environ \- execute a file
+execve \- execute a file

 .SH SYNOPSIS
 .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;
+.ft B
+execve(name, argv, envp)
+.br
+char *name, *argv[], *envp[];

 .fi
 .SH DESCRIPTION
 .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
+.I Execve
+transforms the calling process into a new process.
+The new process is constructed from an ordinary file
+called the \fInew process file\fP.
+This file is either an executable object file,
+or a file of data for an interpreter.
+An executable object file consists of an identifying header,
+followed by pages of data representing the initial program (text)
+and initialized data pages.  Additional pages may be specified
+by the header to be initialize with zero data.  See
+.IR a.out (5).
+.PP
+An interpreter file begins with a line of the form ``#! \fIinterpreter\fP'';
+When an interpreter file is
+.IR execve\| 'd,
+the system \fIexecve\fP\|'s the specified \fIinterpreter\fP, giving
+it the name of the originally exec'd file as an argument,
+shifting over the rest of the original arguments.
+.PP
+There can be no return from a successful \fIexecve\fP because the calling

 core image is lost.
 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
+This is the mechanism whereby different process images become active.
+.PP
+The argument \fIargv\fP is an array of character pointers
+to null-terminated character strings.  These strings constitute
+the argument list to be made available to the new
+process.  By convention, at least one argument must be present in
+this array, and the first element of this array should be
+the name of the executed program (i.e. the last component of \fIname\fP).
+.PP
+The argument \fIenvp\fP is also an array of character pointers
+to null-terminated strings.  These strings pass information to the
+new process which are not directly arguments to the command, see
+.IR environ (7).
+.PP
+Descriptors open in the calling process remain open in
+the new process, except for those for which the close-on-exec
+flag is set; see
+.IR close (2).
+Descriptors which remain open are unaffected by
+.IR execve .
+.PP
+Ignored signals remain ignored across an
+.IR execve ,
+but signals that are caught are reset to their default values.
+The signal stack is reset to be undefined; see
+.IR sigvec (2)
+for more information.
+.PP
+Each process has

 .I real
 .I real

-user ID and group ID and an
+user and group IDs and a

 .I effective
 .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
+user and group IDs.  The
+.I real
+ID identifies the person using the system; the
+.I effective
+ID determines his access privileges.
+.I Execve

 changes the effective user and group ID to
 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
+the owner of the executed file if the file has the \*(lqset-user-ID\*(rq
+or \*(lqset-group-ID\*(rq modes.  The
+.I real

 user ID is not affected.
 .PP
 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.
+The new process also inherits the following attributes from
+the calling process:

 .PP
 .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.
+.in +5n
+.nf
+.ta +2i
+process ID     see \fIgetpid\fP\|(2)
+parent process ID      see \fIgetppid\fP\|(2)
+process group ID       see \fIgetpgrp\fP\|(2)
+access groups  see \fIgetgroups\fP\|(2)
+working directory      see \fIchdir\fP\|(2)
+root directory see \fIchroot\fP\|(2)
+control terminal       see \fItty\fP\|(4)
+resource usages        see \fIgetrusage\fP\|(2)
+interval timers        see \fIgetitimer\fP\|(2)
+resource limits        see \fIgetrlimit\fP\|(2)
+file mode mask see \fIumask\fP\|(2)
+signal mask    see \fIsigvec\fP\|(2)
+.in -5n
+.fi

 .PP
 .PP

-When a C program is executed,
-it is called as follows:
+When the executed program begins, it is called as follows:

 .PP
 .PP

+.DT

 .nf
        main(argc, argv, envp)
        int argc;
 .nf
        main(argc, argv, envp)
        int argc;


@@ -115,30 +111,20 @@ it is called as follows:
 .fi
 .PP
 where
 .fi
 .PP
 where

-.IR argc ""
-is the argument count
+.I argc
+is the number of elements in \fIargv\fP
+(the ``arg count'')

 and
 and

-.IR argv ""
-is an array of character pointers
+.I argv
+is the array of character pointers

 to the arguments themselves.
 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.
 .PP
 .I Envp
 is a pointer to an array of strings that constitute
 the
 .I environment
 of the process.

+A pointer to this array is also stored in the global variable ``environ''.

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


@@ -146,195 +132,67 @@ The shell
 passes an environment entry for each global shell variable
 defined when the program is called.
 See
 passes an environment entry for each global shell variable
 defined when the program is called.
 See

-.IR environ (5)
+.IR environ (7)

 for some conventionally
 used names.
 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
+.SH "RETURN VALUE

 If
 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
+.I execve
+returns to the calling process an error has occurred; the
+return value will be \-1 and the global variable
+.I errno
+will contain an error code.
+.SH ERRORS
+.I Execve
+will fail and return to the calling process if one or more
+of the following are true:
+.TP 15
+[ENOENT]
+One or more components of the new process file's
+path name do not exist.
+.TP 15
+[ENOTDIR]
+A component of the new process file is not a directory.
+.TP 15
+[EACCES]
+Search permission is denied for a directory listed
+in the new process file's path prefix.
+.TP 15
+[EACCES]
+The new process file is not an ordinary file.
+.TP 15
+[EACCES]
+The new process file mode denies execute permission.
+.TP 15
+[ENOEXEC]
+The new process file has the appropriate access
+permission, but has an invalid magic number in its header.
+.TP 15
+[ETXTBSY]
+The new process file is a pure procedure (shared text)
+file that is currently open for writing or reading by some process.
+.TP 15
+[ENOMEM]
+The new process requires more virtual memory than
+is allowed by the imposed maximum
+.RI ( getrlimit (2)).
+.TP 15
+[E2BIG]
+The number of bytes in the new process's argument list
+is larger than the system-imposed limit of {ARG_MAX} bytes.
+.TP 15
+[EFAULT]
+The new process file is not as long as indicated by
+the size values in its header.
+.TP 15
+[EFAULT]
+\fIPath\fP\|, \fIargv\fP\|, or \fIenvp\fP point
+to an illegal address.
+.SH CAVEATS
+If a program is
+.I setuid
+to a non-super-user, but is executed when
+the real \fIuid\fP is ``root'', then the program has the powers
+of a super-user as well.
+.SH "SEE ALSO"
+exit(2), fork(2), execl(3), environ(7)