glenda.party
term% ls -F
term% cat index.txt
EXEC(2)                       System Calls Manual                      EXEC(2)



NAME
       exec, execl, _privates, _nprivates, _tos - execute a file

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

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

       void* execl(char *name, ...)

       void **_privates;

       int  _nprivates;

       #include <tos.h>

       typedef struct Tos Tos;
       struct Tos {
           struct { ... } prof;    /* profiling data */
           uvlong  cyclefreq;      /* cycle clock frequency */
           vlong   kcycles;        /* kernel cycles */
           vlong   pcycles;        /* process cycles (kernel + user) */
           ulong   pid;            /* process id */
           ulong   clock;          /* profiling clock */
           /* top of stack is here */
       };

       extern Tos *_tos;

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 argu‐
       ments 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 executed.

       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)).

       The global cell _privates points to an array of _nprivates elements  of
       per-process  private  data.   This storage is private for each process,
       even if the processes share data segments.

       When the new program begins, the global pointer _tos is set to the  ad‐
       dress  of  a  structure  that  holds information allowing accurate time
       keeping and clock reading in user space.  These data are updated by the
       kernel  during  of the life of the process, including across rforks and
       execs.  If there is a user-space accessible fast clock (a processor cy‐
       cle  counter),  cyclefreq  will be set to its frequency in Hz.  Kcycles
       (pcycles) counts the number of cycles this process has spent in  kernel
       mode  (kernel  and user mode).  Pid is the current process's id.  Clock
       is the user-profiling clock (see prof(1)).  Its  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  pro‐
       grams.

       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  regis‐
       ter  (e.g.  R0 on the 68020) contains the address of the clock informa‐
       tion.

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

SEE ALSO
       prof(1), intro(2), stat(2)

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

BUGS
       There is a large but finite limit on the size of an argment list, typi‐
       cally around 409,600 bytes.  The kernel constant TSTKSIZ controls this.



                                                                       EXEC(2)