exec.3 (2801B)
1 .TH EXEC 3 2 .SH NAME 3 exec, execl \- execute a file 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .PP 9 .nf 10 .B 11 int exec(char *name, char* argv[]) 12 .PP 13 .B 14 int execl(char *name, ...) 15 .fi 16 .SH DESCRIPTION 17 .I Exec 18 and 19 .I execl 20 overlay the calling process with the named file, then 21 transfer to the entry point of the image of the file. 22 .PP 23 .I Name 24 points to the name of the file 25 to be executed; it must not be a directory, and the permissions 26 must allow the current user to execute it 27 (see 28 .MR stat (3) ). 29 It should also be a valid binary image, as defined by the local 30 operating system, or a shell script 31 (see 32 .MR rc (1) ). 33 The first line of a 34 shell script must begin with 35 .L #! 36 followed by the name of the program to interpret the file 37 and any initial arguments to that program, for example 38 .IP 39 .EX 40 #!/bin/rc 41 ls | mc 42 .EE 43 .PP 44 When a C program is executed, 45 it is called as follows: 46 .IP 47 .EX 48 void main(int argc, char *argv[]) 49 .EE 50 .PP 51 .I Argv 52 is a copy of the array of argument pointers passed to 53 .IR exec ; 54 that array must end in a null pointer, and 55 .I argc 56 is the number of elements before the null pointer. 57 By convention, the first argument should be the name of 58 the program to be executed. 59 .I Execl 60 is like 61 .I exec 62 except that 63 .I argv 64 will be an array of the parameters that follow 65 .I name 66 in the call. The last argument to 67 .I execl 68 must be a null pointer. 69 .PP 70 For a file beginning 71 .BR #! , 72 the arguments passed to the program 73 .RB ( /bin/rc 74 in the example above) will be the name of the file being 75 executed, any arguments on the 76 .B #! 77 line, the name of the file again, 78 and finally the second and subsequent arguments given to the original 79 .I exec 80 call. 81 The result honors the two conventions of a program accepting as argument 82 a file to be interpreted and 83 .B argv[0] 84 naming the file being 85 executed. 86 .PP 87 Most attributes of the calling process are carried 88 into the result; in particular, 89 files remain open across 90 .I exec 91 (except those opened with 92 .B OCEXEC 93 OR'd 94 into the open mode; see 95 .MR open (3) ); 96 and the working directory and environment 97 (see 98 .MR getenv (3) ) 99 remain the same. 100 However, a newly 101 .I exec'ed 102 process has no notification handlers 103 (see 104 .MR notify (3) ). 105 .SH SOURCE 106 .B \*9/src/lib9/exec.c 107 .br 108 .B \*9/src/lib9/execl.c 109 .SH SEE ALSO 110 .MR prof (1) , 111 .MR intro (3) , 112 .MR stat (3) 113 .SH DIAGNOSTICS 114 If these functions fail, they return and set 115 .IR errstr . 116 There can be no return from a successful 117 .I exec 118 or 119 .IR execl ; 120 the calling image is lost. 121 .SH BUGS 122 On Unix, unlike on Plan 9, 123 .I exec 124 and 125 .I execl 126 use the user's current path to locate 127 .IR prog . 128 This is a clumsy way to deal with Unix's lack of 129 a union directory for 130 .BR /bin . 131 .PP 132 To avoid name conflicts with the underlying system, 133 .I exec 134 and 135 .I execl 136 are preprocessor macros defined as 137 .I p9exec 138 and 139 .IR p9execl ; 140 see 141 .MR intro (3) .