Return to execve.2 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2

Annotation of 43BSDTahoe/man/man2/execve.2, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)execve.2    6.7 (Berkeley) 5/22/86
        !             6: .\"
        !             7: .TH EXECVE 2 "May 22, 1986"
        !             8: .UC 4
        !             9: .SH NAME
        !            10: execve \- execute a file
        !            11: .SH SYNOPSIS
        !            12: .ft B
        !            13: execve(name, argv, envp)
        !            14: .br
        !            15: char *name, *argv[], *envp[];
        !            16: .fi
        !            17: .SH DESCRIPTION
        !            18: .I Execve
        !            19: transforms the calling process into a new process.
        !            20: The new process is constructed from an ordinary file
        !            21: called the \fInew process file\fP.
        !            22: This file is either an executable object file,
        !            23: or a file of data for an interpreter.
        !            24: An executable object file consists of an identifying header,
        !            25: followed by pages of data representing the initial program (text)
        !            26: and initialized data pages.  Additional pages may be specified
        !            27: by the header to be initialized with zero data.  See
        !            28: .IR a.out (5).
        !            29: .PP
        !            30: An interpreter file begins with a line of the form ``#! \fIinterpreter\fP''.
        !            31: When an interpreter file is
        !            32: .IR execve\| 'd,
        !            33: the system \fIexecve\fP\|'s the specified \fIinterpreter\fP, giving
        !            34: it the name of the originally exec'd file as an argument and
        !            35: shifting over the rest of the original arguments.
        !            36: .PP
        !            37: There can be no return from a successful \fIexecve\fP because the calling
        !            38: core image is lost.
        !            39: This is the mechanism whereby different process images become active.
        !            40: .PP
        !            41: The argument \fIargv\fP is a null-terminated array of character pointers
        !            42: to null-terminated character strings.  These strings constitute
        !            43: the argument list to be made available to the new
        !            44: process.  By convention, at least one argument must be present in
        !            45: this array, and the first element of this array should be
        !            46: the name of the executed program (i.e., the last component of \fIname\fP).
        !            47: .PP
        !            48: The argument \fIenvp\fP is also a null-terminated array of character pointers
        !            49: to null-terminated strings.  These strings pass information to the
        !            50: new process that is not directly an argument to the command (see
        !            51: .IR environ (7)).
        !            52: .PP
        !            53: Descriptors open in the calling process remain open in
        !            54: the new process, except for those for which the close-on-exec
        !            55: flag is set (see
        !            56: .IR close (2)).
        !            57: Descriptors that remain open are unaffected by
        !            58: .IR execve .
        !            59: .PP
        !            60: Ignored signals remain ignored across an
        !            61: .IR execve ,
        !            62: but signals that are caught are reset to their default values.
        !            63: Blocked signals remain blocked regardless of changes to the signal action.
        !            64: The signal stack is reset to be undefined (see
        !            65: .IR sigvec (2) 
        !            66: for more information).
        !            67: .PP
        !            68: Each process has
        !            69: .I real
        !            70: user and group IDs and an
        !            71: .I effective
        !            72: user and group IDs.  The
        !            73: .I real
        !            74: ID identifies the person using the system; the
        !            75: .I effective
        !            76: ID determines his access privileges.
        !            77: .I Execve
        !            78: changes the effective user and group ID to
        !            79: the owner of the executed file if the file has the \*(lqset-user-ID\*(rq
        !            80: or \*(lqset-group-ID\*(rq modes.  The
        !            81: .I real
        !            82: user ID is not affected.
        !            83: .PP
        !            84: The new process also inherits the following attributes from
        !            85: the calling process:
        !            86: .PP
        !            87: .in +5n
        !            88: .nf
        !            89: .ta +2i
        !            90: process ID     see \fIgetpid\fP\|(2)
        !            91: parent process ID      see \fIgetppid\fP\|(2)
        !            92: process group ID       see \fIgetpgrp\fP\|(2)
        !            93: access groups  see \fIgetgroups\fP\|(2)
        !            94: working directory      see \fIchdir\fP\|(2)
        !            95: root directory see \fIchroot\fP\|(2)
        !            96: control terminal       see \fItty\fP\|(4)
        !            97: resource usages        see \fIgetrusage\fP\|(2)
        !            98: interval timers        see \fIgetitimer\fP\|(2)
        !            99: resource limits        see \fIgetrlimit\fP\|(2)
        !           100: file mode mask see \fIumask\fP\|(2)
        !           101: signal mask    see \fIsigvec\fP\|(2), \fIsigmask\fP\|(2)
        !           102: .in -5n
        !           103: .fi
        !           104: .PP
        !           105: When the executed program begins, it is called as follows:
        !           106: .PP
        !           107: .DT
        !           108: .nf
        !           109:        main(argc, argv, envp)
        !           110:        int argc;
        !           111:        char **argv, **envp;
        !           112: .fi
        !           113: .PP
        !           114: where
        !           115: .I argc
        !           116: is the number of elements in \fIargv\fP
        !           117: (the ``arg count'')
        !           118: and
        !           119: .I argv
        !           120: is the array of character pointers
        !           121: to the arguments themselves.
        !           122: .PP
        !           123: .I Envp
        !           124: is a pointer to an array of strings that constitute
        !           125: the
        !           126: .I environment
        !           127: of the process.
        !           128: A pointer to this array is also stored in the global variable ``environ''.
        !           129: Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value.
        !           130: The array of pointers is terminated by a null pointer.
        !           131: The shell
        !           132: .IR sh (1)
        !           133: passes an environment entry for each global shell variable
        !           134: defined when the program is called.
        !           135: See
        !           136: .IR environ (7)
        !           137: for some conventionally
        !           138: used names.
        !           139: .SH "RETURN VALUE
        !           140: If
        !           141: .I execve
        !           142: returns to the calling process an error has occurred; the
        !           143: return value will be \-1 and the global variable
        !           144: .I errno
        !           145: will contain an error code.
        !           146: .SH ERRORS
        !           147: .I Execve
        !           148: will fail and return to the calling process if one or more
        !           149: of the following are true:
        !           150: .TP 15
        !           151: [ENOTDIR]
        !           152: A component of the path prefix is not a directory.
        !           153: .TP 15
        !           154: [EINVAL]
        !           155: The pathname contains a character with the high-order bit set.
        !           156: .TP 15
        !           157: [ENAMETOOLONG]
        !           158: A component of a pathname exceeded 255 characters,
        !           159: or an entire path name exceeded 1023 characters.
        !           160: .TP 15
        !           161: [ENOENT]
        !           162: The new process file does not exist.
        !           163: .TP 15
        !           164: [ELOOP]
        !           165: Too many symbolic links were encountered in translating the pathname.
        !           166: .TP 15
        !           167: [EACCES]
        !           168: Search permission is denied for a component of the path prefix.
        !           169: .TP 15
        !           170: [EACCES]
        !           171: The new process file is not an ordinary file.
        !           172: .TP 15
        !           173: [EACCES]
        !           174: The new process file mode denies execute permission.
        !           175: .TP 15
        !           176: [ENOEXEC]
        !           177: The new process file has the appropriate access
        !           178: permission, but has an invalid magic number in its header.
        !           179: .TP 15
        !           180: [ETXTBSY]
        !           181: The new process file is a pure procedure (shared text)
        !           182: file that is currently open for writing or reading by some process.
        !           183: .TP 15
        !           184: [ENOMEM]
        !           185: The new process requires more virtual memory than
        !           186: is allowed by the imposed maximum
        !           187: .RI ( getrlimit (2)).
        !           188: .TP 15
        !           189: [E2BIG]
        !           190: The number of bytes in the new process's argument list
        !           191: is larger than the system-imposed limit.
        !           192: The limit in the system as released is 20480 bytes
        !           193: (NCARGS in
        !           194: .IR <sys/param.h> .
        !           195: .TP 15
        !           196: [EFAULT]
        !           197: The new process file is not as long as indicated by
        !           198: the size values in its header.
        !           199: .TP 15
        !           200: [EFAULT]
        !           201: \fIPath\fP\|, \fIargv\fP\|, or \fIenvp\fP point
        !           202: to an illegal address.
        !           203: .TP 15
        !           204: [EIO]
        !           205: An I/O error occurred while reading from the file system.
        !           206: .SH CAVEATS
        !           207: If a program is
        !           208: .I setuid
        !           209: to a non-super-user, but is executed when
        !           210: the real \fIuid\fP is ``root'', then the program has some of the powers
        !           211: of a super-user as well.
        !           212: .SH "SEE ALSO"
        !           213: exit(2), fork(2), execl(3), environ(7)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.