10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
142 lines
2.7 KiB
Groff
142 lines
2.7 KiB
Groff
.TH EXEC 3
|
|
.SH NAME
|
|
exec, execl \- 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, ...)
|
|
.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
|
|
.MR stat 3 ).
|
|
It should also be a valid binary image, as defined by the local
|
|
operating system, or a shell script
|
|
(see
|
|
.MR 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
|
|
.MR open 3 );
|
|
and the working directory and environment
|
|
(see
|
|
.MR getenv 3 )
|
|
remain the same.
|
|
However, a newly
|
|
.I exec'ed
|
|
process has no notification handlers
|
|
(see
|
|
.MR notify 3 ).
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/exec.c
|
|
.br
|
|
.B \*9/src/lib9/execl.c
|
|
.SH SEE ALSO
|
|
.MR prof 1 ,
|
|
.MR intro 3 ,
|
|
.MR stat 3
|
|
.SH DIAGNOSTICS
|
|
If these functions fail, they return and set
|
|
.IR errstr .
|
|
There can be no return from a successful
|
|
.I exec
|
|
or
|
|
.IR execl ;
|
|
the calling image is lost.
|
|
.SH BUGS
|
|
On Unix, unlike on Plan 9,
|
|
.I exec
|
|
and
|
|
.I execl
|
|
use the user's current path to locate
|
|
.IR prog .
|
|
This is a clumsy way to deal with Unix's lack of
|
|
a union directory for
|
|
.BR /bin .
|
|
.PP
|
|
To avoid name conflicts with the underlying system,
|
|
.I exec
|
|
and
|
|
.I execl
|
|
are preprocessor macros defined as
|
|
.I p9exec
|
|
and
|
|
.IR p9execl ;
|
|
see
|
|
.MR intro 3 .
|