man(1) Manual page archive


     EXEC(2)                                                   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 cur-
          rent user to execute it (see stat(2)). It should also be a
          valid binary image, as defined in the a.out(6) for the cur-
          rent machine architecture, or a shell script (see rc(1)).
          The first line of a shell script must begin with `#!'  fol-
          lowed 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 argu-
          ments 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
          executed.

     EXEC(2)                                                   EXEC(2)

          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 imple-
          mentation 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 immedi-
          ately.  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 call-
          ing image is lost.