520a39efcd
Our #! line length is very short, and the naïve quoting makes it difficult to pass more complicated arguments to the programs being run. This is fine for simple interpreters, but it's often useful to pass arguments to more complicated interpreters like auth/box or awk. This change raises the limit, but also switches to tokenizing via tokenize(2), rather than hand rolled whitespace splitting. The limits chosen are arbitrary, but they leave approximately 3 KiB of stack space on 386, and 13k on amd64. This is a lot of stack used, but it should leave enough for fairly deep devtab chan stacks.
201 lines
4.5 KiB
Text
201 lines
4.5 KiB
Text
.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.
|