EXEC(2) 							System Calls Manual							   EXEC(2)

NAME

       exec, execl, _clock - execute a file

SYNOPSIS

       #include <u.h>
       #include <libc.h>

       int exec(char *name, char* argv[])

       int execl(char *name, ...)

       long *_clock;

DESCRIPTION

       Exec and execl overlay the calling process with the named file, then transfer to the entry point of the image of the file.

       Name  points to the name of the file to be executed; it must not be a directory, and the permissions must allow the current user to execute
       it (see stat(2)).  It should also be a valid binary image, as defined in the a.out(6) for the current  machine  architecture,  or  a  shell
       script  (see  rc(1)).   The  first line of a shell script must begin with followed by the name of the program to interpret the file and any
       initial arguments to that program, for example

	      #!/bin/rc
	      ls | mc

       When a C program is executed, it is called as follows:

	      void main(int argc, char *argv[])

       Argv is a copy of the array of argument pointers passed to exec; that array must end in a null pointer, and argc is the number of  elements
       before  the  null  pointer.  By convention, the first argument should be the name of the program to be executed.  Execl is like exec except
       that argv will be an array of the parameters that follow name in the call.  The last argument to execl must be a null pointer.

       For a file beginning #!, the arguments passed to the program (/bin/rc in the example above) will be the name of the  file  being  executed,
       any arguments on the #!	line, the name of the file again, and finally the second and subsequent arguments given to the original exec call.
       The result honors the two conventions of a program accepting as argument a file to be interpreted and argv[0] naming the  file  being  exe-
       cuted.

       Most  attributes of the calling process are carried into the result; in particular, files remain open across exec (except those opened with
       OCEXEC OR'd into the open mode; see open(2)); and the working directory and environment (see env(3)) remain the	same.	However,  a  newly
       exec'ed process has no notification handler (see notify(2)).

       When  the new program begins, the global cell _clock is set to the address of a cell that keeps approximate time expended by the process at
       user level.  The time is measured in milliseconds but is updated at a system-dependent lower rate.  This clock is  typically  used  by  the
       profiler but is available to all programs.

       The  above  conventions	apply  to  C  programs;  the raw system interface to the new image is as follows: the word pointed to by the stack
       pointer is argc; the words beyond that are the zeroth and subsequent elements of argv, followed by a  terminating  null	pointer;  and  the
       return register (e.g.  R0 on the 68020) contains the address of the clock.

   Alef
       In  Alef,  the intent and syntax are the same but the implementation is different.  Exec (or execl; this description applies to either) may
       be called only by a proc holding a single task, typically the implicit main task of the proc.  First, access(2) is called  to  see  if  the
       named  file  exists  and has execute permission.  If not, exec returns -1 immediately.  Otherwise, it will never return: it frees resources
       private to the invoking proc and calls the exec system call.  If this fails, it calls the bare _exits system call (see exits(2))  with  the
       error string as argument.  Therefore, if the file looks executable, the calling process is lost, whether the exec succeeds or not.

SOURCE

       /sys/src/libc/9syscall
       /sys/src/libc/port/execl.c

SEE ALSO

       intro(2), stat(2)

DIAGNOSTICS

       If these functions fail, they return and set errstr.  There can be no return from a successful exec or execl; the calling image is lost.

																	   EXEC(2)