Return to execl.3 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man3

Annotation of cci/usr/src/man/man3/execl.3, revision 1.1

1.1     ! root        1: .TH EXECL 3 "1 April 1981"
        !             2: .UC 4
        !             3: .SH NAME
        !             4: execl, execv, execle, execlp, execvp, exec, exece, exect, environ \- execute a file
        !             5: .SH SYNOPSIS
        !             6: .nf
        !             7: .B execl(name, arg0, arg1, ..., argn, 0)
        !             8: .B char *name, *arg0, *arg1, ..., *argn;
        !             9: .PP
        !            10: .B execv(name, argv)
        !            11: .B char *name, *argv[];
        !            12: .PP
        !            13: .B "execle(name, arg0, arg1, ..., argn, 0, envp)"
        !            14: .B "char *name, *arg0, *arg1, ..., *argn, *envp[];"
        !            15: .PP
        !            16: .B "exect(name, argv, envp)
        !            17: .B "char *name, *argv[], *envp[];
        !            18: .PP
        !            19: .B extern char **environ;
        !            20: .fi
        !            21: .SH DESCRIPTION
        !            22: These routines provide various interfaces to the
        !            23: .I execve 
        !            24: system call.  Refer to 
        !            25: .IR  execve (2)
        !            26: for a description of their properties; only
        !            27: brief descriptions are provided here.
        !            28: .PP
        !            29: .I Exec
        !            30: in all its forms
        !            31: overlays the calling process with the named file, then
        !            32: transfers to the
        !            33: entry point of the core image of the file.
        !            34: There can be no return from a successful exec; the calling
        !            35: core image is lost.
        !            36: .PP
        !            37: The
        !            38: .I name
        !            39: argument
        !            40: is a pointer to the name of the file
        !            41: to be executed.
        !            42: The pointers
        !            43: .IR arg [ 0 ],
        !            44: .IR arg [ 1 "] ..."
        !            45: address null-terminated strings.
        !            46: Conventionally
        !            47: .IR arg [ 0 ]
        !            48: is the name of the
        !            49: file.
        !            50: .PP
        !            51: Two interfaces are available.
        !            52: .I execl
        !            53: is useful when a known file with known arguments is
        !            54: being called;
        !            55: the arguments to
        !            56: .I execl
        !            57: are the character strings
        !            58: constituting the file and the arguments;
        !            59: the first argument is conventionally
        !            60: the same as the file name (or its last component).
        !            61: A 0 argument must end the argument list.
        !            62: .PP
        !            63: The
        !            64: .I execv
        !            65: version is useful when the number of arguments is unknown
        !            66: in advance;
        !            67: the arguments to
        !            68: .I execv
        !            69: are the name of the file to be
        !            70: executed and a vector of strings containing
        !            71: the arguments.
        !            72: The last argument string must be followed
        !            73: by a 0 pointer.
        !            74: .PP
        !            75: The
        !            76: .I exect
        !            77: version is used when the executed file is to be
        !            78: manipulated with 
        !            79: .IR ptrace (2).
        !            80: The program is forced to single step a single
        !            81: instruction giving the parent an opportunity to
        !            82: manipulate its state.  This is done
        !            83: by setting the trace bit in the process status
        !            84: longword.
        !            85: .PP
        !            86: When a C program is executed,
        !            87: it is called as follows:
        !            88: .PP
        !            89: .nf
        !            90:        main(argc, argv, envp)
        !            91:        int argc;
        !            92:        char **argv, **envp;
        !            93: .fi
        !            94: .PP
        !            95: where
        !            96: .I argc
        !            97: is the argument count
        !            98: and
        !            99: .I argv 
        !           100: is an array of character pointers
        !           101: to the arguments themselves.
        !           102: As indicated,
        !           103: .I argc
        !           104: is conventionally at least one
        !           105: and the first member of the array points to a
        !           106: string containing the name of the file.
        !           107: .PP
        !           108: .I Argv
        !           109: is directly usable in another
        !           110: .I execv
        !           111: because
        !           112: .IR argv [ argc ]
        !           113: is 0.
        !           114: .PP
        !           115: .I Envp
        !           116: is a pointer to an array of strings that constitute
        !           117: the
        !           118: .I environment
        !           119: of the process.
        !           120: Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value.
        !           121: The array of pointers is terminated by a null pointer.
        !           122: The shell
        !           123: .IR sh (1)
        !           124: passes an environment entry for each global shell variable
        !           125: defined when the program is called.
        !           126: See
        !           127: .IR environ (7)
        !           128: for some conventionally
        !           129: used names.
        !           130: The C run-time start-off routine places a copy of
        !           131: .I envp
        !           132: in the global cell
        !           133: .IR environ ,
        !           134: which is used
        !           135: by
        !           136: .I execv
        !           137: and
        !           138: .I execl
        !           139: to pass the environment to any subprograms executed by the
        !           140: current program.
        !           141: .PP
        !           142: .I Execlp
        !           143: and
        !           144: .I execvp
        !           145: are called with the same arguments as
        !           146: .I execl
        !           147: and
        !           148: .IR execv ,
        !           149: but duplicate the shell's actions in searching for an executable
        !           150: file in a list of directories.
        !           151: The directory list is obtained from the environment.
        !           152: .SH FILES
        !           153: .ta \w'/bin/sh  'u
        !           154: /bin/sh        shell, invoked if command file found
        !           155: by
        !           156: .I execlp
        !           157: or
        !           158: .I execvp
        !           159: .SH "SEE ALSO"
        !           160: execve(2),
        !           161: fork(2),
        !           162: environ(7),
        !           163: csh(1)
        !           164: .SH DIAGNOSTICS
        !           165: If the file cannot be found,
        !           166: if it is not executable,
        !           167: if it does not start with a valid magic number (see
        !           168: .IR a.out (5)),
        !           169: if maximum memory is exceeded,
        !           170: or if the arguments require too much space,
        !           171: a return
        !           172: constitutes the diagnostic;
        !           173: the return value is \-1.
        !           174: Even for the super-user,
        !           175: at least one of the execute-permission bits must be set for
        !           176: a file to be executed.
        !           177: .SH BUGS
        !           178: If
        !           179: .I execvp
        !           180: is called to execute a file that turns out to be a shell
        !           181: command file,
        !           182: and if it is impossible to execute the shell,
        !           183: the values of
        !           184: .I argv[0]
        !           185: and
        !           186: .I argv[\-1]
        !           187: will be modified before return.

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