202 lines
4.5 KiB
Plaintext
202 lines
4.5 KiB
Plaintext
.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
|
|
int exec(char *name, char* argv[])
|
|
.PP
|
|
.B
|
|
int 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
|
|
There may be up to 256 bytes of arguments passed to the interpreter.
|
|
These are tokenized into up to 32 arguments by
|
|
.IR tokenize (2)
|
|
before being passed as the interpreters argument vector.
|
|
.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 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
|
|
.B Tos
|
|
structure.
|
|
.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.
|