Return to execve.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

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