man/man3/execl.3

   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, environ \- execute a file
  11 .SH SYNOPSIS
  12 .ft B
  13 #include <unistd.h>
  14
  15 .in +.5i
  16 .ti -.5i
  17 int execl(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL)
  18 .ti -.5i
  19 int execv(const char *\fIname\fP, char *const \fIargv\fP[])
  20 .ti -.5i
  21 int execle(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL, char *const \fIenvp\fP[])
  22 .ti -.5i
  23 int execlp(const char *\fIname\fP, const char *\fIarg0\fP, ..., (char *) NULL)
  24 .ti -.5i
  25 int execvp(const char *\fIname\fP, char *const \fIargv\fP[])
  26 .in -.5i
  27
  28 extern char *const *environ;
  29 .fi
  30 .SH DESCRIPTION
  31 These routines provide various interfaces to the
  32 .B execve
  33 system call.  Refer to
  34 .BR  execve (2)
  35 for a description of their properties; only
  36 brief descriptions are provided here.
  37 .PP
  38 .B Exec
  39 in all its forms
  40 overlays the calling process with the named file, then
  41 transfers to the
  42 entry point of the core image of the file.
  43 There can be no return from a successful exec; the calling
  44 core image is lost.
  45 .PP
  46 The
  47 .I name
  48 argument
  49 is a pointer to the name of the file
  50 to be executed.
  51 The pointers
  52 .IR arg [ 0 ],
  53 .IR arg [ 1 "] ..."
  54 address null-terminated strings.
  55 Conventionally
  56 .IR arg [ 0 ]
  57 is the name of the
  58 file.
  59 .PP
  60 Two interfaces are available.
  61 .B execl
  62 is useful when a known file with known arguments is
  63 being called;
  64 the arguments to
  65 .B execl
  66 are the character strings
  67 constituting the file and the arguments;
  68 the first argument is conventionally
  69 the same as the file name (or its last component).
  70 A null pointer argument must end the argument list.
  71 (Note that the
  72 .B execl*
  73 functions are variable argument functions.  This means that the type
  74 of the arguments beyond
  75 .I arg0
  76 is not checked.  So the null pointer requires an explicit cast to type
  77 .B "(char *)"
  78 if not of that type already.)
  79 .PP
  80 The
  81 .B execv
  82 version is useful when the number of arguments is unknown
  83 in advance;
  84 the arguments to
  85 .B execv
  86 are the name of the file to be
  87 executed and a vector of strings containing
  88 the arguments.
  89 The last argument string must be followed
  90 by a null pointer.
  91 .PP
  92 When a C program is executed,
  93 it is called as follows:
  94 .PP
  95 .RS
  96 .ft B
  97 .nf
  98 int main(int \fIargc\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]);
  99
 100 exit(main(\fIargc\fP, \fIargv\fP, \fIenvp\fP));
 101 .fi
 102 .ft R
 103 .RE
 104 .PP
 105 where
 106 .I argc
 107 is the argument count
 108 and
 109 .I argv
 110 is an array of character pointers
 111 to the arguments themselves.
 112 As indicated,
 113 .I argc
 114 is conventionally at least one
 115 and the first member of the array points to a
 116 string containing the name of the file.
 117 .PP
 118 .I Argv
 119 is directly usable in another
 120 .B execv
 121 because
 122 .IR argv [ argc ]
 123 is 0.
 124 .PP
 125 .I Envp
 126 is a pointer to an array of strings that constitute
 127 the
 128 .I environment
 129 of the process.
 130 Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value.
 131 The array of pointers is terminated by a null pointer.
 132 The shell
 133 .BR sh (1)
 134 passes an environment entry for each global shell variable
 135 defined when the program is called.
 136 See
 137 .BR environ (7)
 138 for some conventionally
 139 used names.
 140 The C run-time start-off routine places a copy of
 141 .I envp
 142 in the global cell
 143 .BR environ ,
 144 which is used
 145 by
 146 .B execv
 147 and
 148 .B execl
 149 to pass the environment to any subprograms executed by the
 150 current program.
 151 .PP
 152 .B Execlp
 153 and
 154 .B execvp
 155 are called with the same arguments as
 156 .B execl
 157 and
 158 .BR execv ,
 159 but duplicate the shell's actions in searching for an executable
 160 file in a list of directories.
 161 The directory list is obtained from the environment variable
 162 .BR PATH .
 163 Under standard MINIX 3, if a file is found that is executable, but does
 164 not have the proper executable header then it is assumed to be
 165 a shell script.
 166 .B Execlp
 167 and
 168 .B execvp
 169 execute
 170 .B /bin/sh
 171 to interpret the script.
 172 Under Minix-vmd this does not happen, a script must begin with
 173 .B #!
 174 and the full path name of the interpreter if it is to be an
 175 executable script.
 176 .SH "SEE ALSO"
 177 .BR execve (2),
 178 .BR fork (2),
 179 .BR environ (7),
 180 .BR sh (1).
 181 .SH DIAGNOSTICS
 182 If the file cannot be found,
 183 if it is not executable,
 184 if it does not start with a valid magic number (see
 185 .BR a.out (5)),
 186 if maximum memory is exceeded,
 187 or if the arguments require too much space,
 188 a return
 189 constitutes the diagnostic;
 190 the return value is \-1 and
 191 .B errno
 192 is set as for
 193 .BR execve .
 194 Even for the super-user,
 195 at least one of the execute-permission bits must be set for
 196 a file to be executed.