Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-Fileshel_write()Pexec() GEMDOSSyntaxLONG Pexec( mode, fname, cmdline, envstr )
WORD mode;
char *fname,*cmdline,*envstr;
Function Pexec() has many functions designed to spawn child processes depending on the selected mode.
Opcode 75 (0x4B)
Availability Pexec() modes 0, 3, 4, and 5, are available in all GEMDOSversions. Mode 6 is available as of GEMDOS version 0.15.
Mode 6 is available as of GEMDOS version 0.19. Modes 100,
104, 106, and 200 are only available in the presence of
MiNT.
Parameters mode defines the function of Pexec() and the meaning of its
parameters and return value as defined below. For modes which load a program, fname specifies the GEMDOS file
specification of the file to load. cmdline is pointer to
a string containg the command line which will be passed to
the calling program. The first byte of the string should
indicate the length of the command line (maximum of 125
bytes). The actual command line starts at byte 2. envstr is
a pointer to an environment which is copied and assigned to
the child process. If envstr is NULL, the child inherits
a copy of the parent's environment.
Name mode Meaning
PE_LOADGO 0 'LOAD AND GO' - Load and execute named
program file and return a WORD exit
code when the child terminates.
PE_LOAD 3 'LOAD, DON'T GO' - Load named program.
If successful, the LONG return value is
the starting address of the child
processes' basepage. The parent owns
the memory of the child's environment
and basepage and must therefore free
them when completed with the child.
PE_GO 4 'JUST GO' - Execute process with
basepage at specified address. With
this mode, fname and envstr are NULL.
The starting address of the basepage of
the process to execute is given in the
cmdline parameter.
PE_BASEPAGE 5 'CREATE BASEPAGE' - This mode allocates
the largest block of free memory and
creates a basepage in the first 256
bytes of it. fname should be set to
NULL. It is the responsibility of the
parent to load or define the child's
code, shrink the memory block as
necessary, and initialize the basepage
pointers to the TEXT, DATA, and BSS
segments of the program. With MiNT, use
of this mode in conjunction with mode
PE_CGO can be used to emulate the
Pvfork() call without blocking the
parent.
PE_GOTHENFREE 6 'JUST GO, THEN FREE' - This mode is
identical to mode PE_GO except that
memory ownership of the child's
environment and basepage belong to the
child rather than the parent so that
when the child Pterm()'s, that memory
is automatically freed.
PE_CLOADGO 100 'LOAD, GO, DON'T WAIT' - This mode is
identical to mode PE_LOADGO except that
the parent process is returned to
immediately while the child continues
to execute. The positive process ID of
the child is returned. Environment and
basepage memory blocks are freed
automatically when the child Pterm()'s
PE_CGO 104 'JUST GO, DON'T WAIT' - This mode is
similar to mode PE_GO except that the
parent process is returned to
immediately while the child continues
to execute concurrently. The positive
process ID of the child is returned.
Memory ownership of the environment and
basepage are shared by the parent and
child (this sharing extends to all
memory owned by the parent). fname may
be used to supply a name for the child,
otherwise, if NULL is used, the name of
the parent will be used. cmdline should
point to the process basepage. envstr
should be NULL.
PE_NOSHARE 106 'JUST GO, DON'T WAIT, NO SHARING' -
This mode is exactly the same as mode
PE_CGO except that the child process
owns its own environment and basepage
sharing no memory with the parent.
PE_REPLACE 200 'REPLACE PROGRAM AND GO' - This mode
works like mode PE_CLOADGO except that
the parent process is terminated
immediately and the child process
completely replaces the parent in
memory retaining the same process ID.
fname, cmdline, and envstr, are all
normally passed and valid.
Binding pea envstr
pea cmdline
pea fname
move.w mode,-(sp)
move.w #$4B,-(sp)
trap #1
lea 16(sp),sp
Return Value The value returned by Pexec() is dependent on the mode value
and is therefore explained above. All Pexec() modes return
a LONG negative GEMDOS error code when the call fails.
A WORD negative value indicates the child was successfully
run but it terminated returning a negative error code. In
all cases, a process returning after having been interrupted
with ctrl-c returns 0x0000FFE0 (-32).
Comments Command lines longer than 126 bytes may be passed to
processes aware of the Atari Extended Command Line
Specification (see discussion earlier in this chapter).
See Also shel_write()