Return to execl.3 CVS log

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

Annotation of 43BSDTahoe/man/man3/execl.3, revision 1.1

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

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