Subversion Repositories planix.SVN

.TH EXEC 2

.SH NAME

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

.SH SYNOPSIS

.B #include <u.h>

.br

.B #include <libc.h>

.PP

.nf

.B

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

.PP

.B

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

.PP

.B

void	**_privates;

.PP

.B

int	_nprivates;

.PP

.B

#include <tos.h>

.PP

.ft L

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 */

};

.PP

.B

extern Tos *_tos;

.fi

.SH DESCRIPTION

.I Exec

and

.I execl

overlay the calling process with the named file, then

transfer to the entry point of the image of the file.

.PP

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

.IR stat (2)).

It should also be a valid binary image, as defined in the

.IR a.out (6)

for the current machine architecture,

or a shell script

(see

.IR rc (1)).

The first line of a

shell script must begin with

.L #!

followed by the name of the program to interpret the file

and any initial arguments to that program, for example

.IP

.EX

#!/bin/rc

ls | mc

.EE

.PP

When a C program is executed,

it is called as follows:

.IP

.EX

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

.EE

.PP

.I Argv

is a copy of the array of argument pointers passed to

.IR exec ;

that array must end in a null pointer, and

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

.I Execl

is like

.I exec

except that

.I argv

will be an array of the parameters that follow

.I name

in the call.  The last argument to

.I execl

must be a null pointer.

.PP

For a file beginning

.BR #! ,

the arguments passed to the program

.RB ( /bin/rc

in the example above) will be the name of the file being

executed, any arguments on the

.B #!

line, the name of the file again,

and finally the second and subsequent arguments given to the original

.I exec

call.

The result honors the two conventions of a program accepting as argument

a file to be interpreted and

.B argv[0]

naming the file being

executed.

.PP

Most attributes of the calling process are carried

into the result; in particular,

files remain open across

.I exec

(except those opened with

.B OCEXEC

OR'd

into the open mode; see

.IR open (2));

and the working directory and environment

(see

.IR env (3))

remain the same.

However, a newly

.I exec'ed

process has no notification handler

(see

.IR notify (2)).

.PP

The global cell

.B _privates

points to an array of

.B _nprivates

elements of per-process private data.

This storage is private for each process, even if the processes share data segments.

.PP

When the new program begins, the global pointer

.B _tos

is set to the address 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

.IR rfork s

and

.IR exec s.

If there is a user-space accessible fast clock (a processor

cycle counter),

.B cyclefreq

will be set to its frequency in Hz.

.B Kcycles

.RB ( pcycles )

counts the number of cycles 

this process has spent in kernel mode

(kernel and user mode).

.B Pid

is the current process's id.

.B Clock

is the user-profiling clock (see

.IR 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 programs.

.PP

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

.BR argc ;

the words beyond that are the zeroth and subsequent elements

of

.BR argv ,

followed by a terminating null pointer; and

the return register (e.g.

.B R0

on the 68020) contains the address of the clock information.

.SH SOURCE

.B /sys/src/libc/9syscall

.br

.B /sys/src/libc/port/execl.c

.SH SEE ALSO

.IR prof (1),

.IR intro (2),

.IR stat (2)

.SH DIAGNOSTICS

If these functions fail, they return and set

.IR errstr .

There can be no return to the calling process from a successful

.I exec

or

.IR execl ;

the calling image is lost.

.SH BUGS

There is a large but finite limit on the size of an argment list,

typically around 409,600 bytes.

The kernel constant

.B TSTKSIZ

controls this.