Home GEMDOSGEMDOS Date and TimeDate and Time Memory managementMemory management

5.11 Process functions

Pause        Suspends a process until the arrival of a signal.
Pdomain      Sets or inquires the processes' execution domain.
Pexec        Loads and executes a further program.
Pfork        Creates a copy of the current process.
Pgetauid     Gets the user ID of a process at the beginning.
Pgetegid     Gets the effective group ID of a process.
Pgeteuid     Gets the effective user ID of a process.
Pgetgid      Gets the group ID of a process.
Pgetgroups   gets the supplementary group ids for the calling process.
Pgetpgrp     Gets current process group number.
Pgetpid      Gets current process ID.
Pgetppid     Gets process ID for parent process.
Pgetpriority Gets the current priority value for a process.
Pgetuid      Gets the user ID of a process.
Pkill        Sends a signal to a process.
Pmsg         Sends and receives messages.
Pnice        Alters priority of the calling process.
Prenice      Adjusts priority of a specified process.
Prusage      Gets resource information about current process.
Psemaphore   Creates, uses or destroys a semaphore.
Psetauid     Sets user ID of a process at the start.
Psetegid     Sets effective group ID of a process.
Pseteuid     Sets effective user ID of a process.
Psetgid      Alters group ID of a process.
Psetgroups   Sets the supplementary group ids for the calling process.
Psetlimit    Sets/gets limits of the system resources.
Psetpgrp     Sets/gets process group number of a process.
Psetpriority Sets the current priority value for a process.
Psetregid    Sets the real and/or effective group ID for the calling process.
Psetreuid    Sets the real and/or effective user ID for the calling process.
Psetuid      Alters user ID of a process.
Psigaction   Alters manner of signal handling.
Psigblock    Alters signal mask.
Psigintr     Assigns a signal to a particular exception vector.
Psignal      Alters manner of signal handling.
Psigpause    Sets a new signal mask and then suspends process until the arrival of a signal.
Psigpending  Checks which signals have been sent but not processed.
Psigreturn   Prepares exit from a signal-handler.
Psigsetmask  Sets/replaces a signal mask.
Psysctl      Gets or sets system information.
Pterm        Terminates program and returns value to caller.
Pterm0       Terminates program and returns 0 to caller.
Ptermres     Terminates program but leaves it in memory.
Ptrace       Process tracing and debugging.
Pumask       Sets initial creation mask for files/directories.
Pusrval      Sets/interrogates specific process information.
Pvfork       Creates copy of the current process.
Pwait        Tries to get the exit code of waiting or terminated child process.
Pwait3       Gets exit code of any waiting or terminated children of the calling process.
Pwaitpid     Gets exit code information about one or more child processes.

See also: Memory management   Signals   Task-Manager

5.11.1 Pause

Name: »Pause« - Suspend a process until the arrival of a signal.
 
Opcode: 289
 
Syntax: void Pause ( void );
 
Description: The function Pause suspends the calling process until a signal for this arrives. If a signal-handler has been installed for this signal with Psignal, the handler will be called before the function Pause returns.
 
The function will not return if the signal-handler executes a non-local jump (via longjump), or if the program is terminated.
 
Return value: The function has no direct return result.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Psigblock   Psignal   Psigpause   Psigsetmask   Signals
 

5.11.1.1 Bindings for Pause

C: void Pause ( void );
 
Assembler:
 
move.w    #289,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.2 Pdomain

Name: »Pdomain« - Set or get the caller's execution domain.
 
Opcode: 281
 
Syntax: int16_t Pdomain ( int16_t dom );
 
Description: The function Pdomain serves for setting or obtaining the domain in which the process is executed. This domain can influence the behaviour of the process drastically in parts. The following apply:
 
dom Meaning
   
-1 Get currently valid domain (don't change it)
 0 TOS-domain (default value). In this domain all system calls behave exactly as under normal TOS.
 1 MiNT-domain. In this domain the behaviour of Fread and Fwrite is influences by the parameters set for Fcntl when these are applied to a terminal. Furthermore, filenames returned by Fsfirst or Fsnext are handled in a different way.

Note: MiNT-compatible processes should also be able to deal with files that do not correspond to the standard DOS convention (8+3 characters).
 
Return value: The function returns the domain of the process that was valid at the function call.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and MagiC as of Version 4.0 (05.11.1995).
 
Group: Process functions
 
See also: Binding   Dpathconf   Dopendir
 

5.11.2.1 Bindings for Pdomain

C: int16_t Pdomain ( int16_t dom );
 
Assembler:
 
move.w    dom,-(sp)    ; Offset 2
move.w    #281,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.3 Pexec

Name: »Program execution« - Load and execute a program.
 
Opcode: 75
 
Syntax: int32_t Pexec ( uint16_t mode, ... );
 
Description: The function Pexec loads and launches a program. With the parameter mode one can select from several variants:
 
mode Meaning
 
0 int32_t Pexec (0, int8_t *name, int8_t *cmdline, int8_t *env);
 
Load and go: Loads and launches the program specified in name and passes the command line cmdline. Returns a WORD exit code when the child terminates. The following apply for the parameter env:
 
-1 = Do not create an environment
NULL = Inherit the environment of the parent

Any other value is a pointer to the environment to be inherited.
 
3 PD *Pexec (3, int8_t* name, int8_t *cmdline, int8_t *env);
 
Load, don't go: This is used most often for launching overlays or for loading programs in a debugger. Corresponds to mode 0 with the difference that the program is not launched immediately, but that a pointer to the child processes' basepage is returned as a LONG. The parent owns the memory of the child's environment and basepage and hence must free them when finished with the child.
 
4 int32_t Pexec (4, 0L, PD *basepage, 0L);
 
Just go: Launches an already loaded program with basepage at the specified address. The basepage should have been created with mode 3 or 5.
 
5 PD *Pexec (5, 0L, int8_t *cmdline, int8_t *env);
 
Create basepage: First of all GEMDOS creates a new environment. Then the largest block of free memory is allocated and a basepage is created in the first 256 bytes. The following applies for the parameter env:
 
-1 = Do not create an environment
NULL = Inherit the environment of the parent

Any other value is a pointer to the environment to be inherited.
 
With MiNT, use of this mode in conjunction with mode 3 can be used to emulate the Pvfork call without blocking the parent.
 
6 int32_t Pexec (6, 0L, PD *basepage, 0L);
 
Just go, then free: Corresponds to mode 4 but with the difference that the allocated memory belongs to the launched process (child) and not to the launcher (parent); thus the basepage memory blocks are freed automatically when the child is terminated with Pterm. Together with mode 3 one can achieve the same effect with it as with mode 0. This mode is available only from GEMDOS Version 0.15.
 
7 PD *Pexec (7, uint32_t prgflags, int8_t *cmdline, int8_t *env);
 
Create basepage, respecting prgflags: Similar to mode 5, but in prgflags one can pass the same information as in the ph_prgflags field of the program header. This mode is used by the BIOS of the TT030 to launch GEM, and is only available as of GEMDOS Version 0.19.
 
100 int32_t Pexec (100, int8_t *name, int8_t *cmdline, int8_t *env);
 
Load, go, don't wait: Similar to mode 0, only the caller does not wait until the launched program is terminated, i.e. the parent process is returned to immediately while the child continues to excecute. The return value is a negative error-code or the positive PID of the child.
 
101 As this mode is only used internally by MagiC for inheriting path and file handles, the details of the exact syntax will be forgone here.
 
102 Is used internally by MagiC to remove a given process. Therefore the details of the exact syntax will be forgone here.
 
104 int32_t Pexec (104, int8_t *name, PD *basepage, 0L);
 
Just go, don't wait: Similar to mode 4, only the caller does not wait until the launched program is terminated. A process will be launched whose basepage was set earlier with mode 3, 5 or 7. One should note that the environment and the basepage of the child is also owned by the parent (in fact the child inherits all the memory that is possessed by the parent). The parameter name is a pointer to a string that describes the name of the new process; with a NULL value the name of the parent process will be used. The function returns a negative error-code, or the positive PID of the child.
 
106 int32_t Pexec (106, int8_t *name, PD *basepage, 0L);
 
Just go, don't wait, no sharing: Similar to mode 104, however the environment and basepage of the child are not in the possession of the parent, and the child has no access to memory that was allocated to the parent process. At the termination of the child its memory is released again. In combination with mode 3, therefore, Pexec (106, ...) corresponds to mode 100 (while mode 3 followed by mode 6 corresponds to a call of Pexec (0, ...)).
Is no longer supported from MagiC 2.0 onwards.
 
107 Corresponds essentially with mode 7, and is used internally by MagiC since version 2.10. Hence the details of the exact syntax will be forgone here.
 
108 Is used by MagiC since version 2.10 internally for launching a desk accessory. Since the exact syntax is not officially documented, it is better for own programs to fall back on shel_write.
 
200 int32_t Pexec (200, int8_t *name, int8_t *cmdline, int8_t *env);
 
Replace program and go: Similar to mode 100, however the new process overwrites the old one completely. Though the old process retains its PID and most of its attributes, all the memory it occupied will be released. While Pexec (0, ...) can be taken as a subprogram call (call...return), this mode acts more like a 'goto'.
 
300
 
301
 
401 Is used internally by MagiC. Therefore the details of the exact syntax will be forgone here.
 

Note: Not all the modes are available under all varieties of operating system; therefore careful note should be taken of the return value of the function. Unknown modes results in a function return of EINVFN.
 
Command lines are passed as a Pascal format string, i.e. the first byte contains the length of the line (maximum 124 characters).
 
Return value: Return value: The function returns the exit code of the child process. If an overlay was loaded, the result contains the basepage of the overlay. With a negative result, an error has arisen.
 
Availability: All GEMDOS versions.
 
Group: Process functions
 
See also: Binding   shel_write   Program flags   ARGV procedure
 

5.11.3.1 Bindings for Pexec

C: int32_t Pexec ( uint16_t mode, ... );
 
Assembler:
 
pea       env          ; Offset 12
pea       cmdline      ; Offset  8
pea       name         ; Offset  4
move.w    mode,-(sp)   ; Offset  2
move.w    #75,-(sp)    ; Offset  0
trap      #1           ; GEMDOS
lea       $10(sp),sp   ; Correct stack
GFA-Basic Adresse%=Gemdos(&H4B,W:mode%,L:name%,L:cmdline%,L:env)
 

5.11.4 Pfork

Name: »Pfork« - Create a copy of the current process.
 
Opcode: 283
 
Syntax: int16_t Pfork ( void );
 
Description: The function Pfork creates a copy of the current process. The child process inherits a copy of the address space of the parent process, i.e. changes made to variables by the child have no effect on the parent.
 
The newly created process starts its work when the function Pfork returns.
 
If the parent is in supervisor-mode when this call is made, the child is launched in user-mode anyway.
 
New processes launched with this call should not use Mshrink, but are required to do any GEM initialisation such as appl_init and v_openvwk again (if they need to use GEM). Both parent and child use Pterm or Pterm0 to terminate themselves.
 
Return value: The function can return the following results:
 
E_OK  : In child process
>0    : New process ID in parent process
ENSMEM: Not enough memory available to create the new process
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Pexec   Pvfork   Threads
 

5.11.4.1 Bindings for Pfork

C: int16_t Pfork ( void );
 
Assembler:
 
move.w    #283,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.5 Pgetauid

Name: »Pgetauid« - Get user ID of a process at the start.
 
Opcode: 325 (0x0145)
 
Syntax: int16_t Pgetauid ( void );
 
Description: The function Pgetauid obtains the start user ID of the current process. Together with Psetauid one can use it in a multi-user environment to ascertain who was the first logged-in user.
 
Return value: The return value is the start user ID of the process.
 
Availability: From MiNT 1.11 onwards.
 
Group: Process functions
 
See also: Binding   Psetauid
 

5.11.5.1 Bindings for Pgetauid

C: int16_t Pgetauid ( void );
 
Assembler:
 
move.w    #325,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.6 Pgetegid

Name: »Pgetegid« - Get effective group ID of a process.
 
Opcode: 313
 
Syntax: int32_t Pgetegid ( void );
 
Description: The function Pgetegid returns the effective group ID of the current process and resembles the system call Pgetgid. The difference lies in that here the effective group ID is returned.
 
This is normally identical to the actual group ID; however, if a program is running that has set the setgid bit, its effective group ID is equal to the (actual) ID of the owner of this program file.
 
File accesses are based, among other things, on the effective group ID, so that the setgid mechanism allows users (particularly the super-user) to permit access by other users.
 
Return value: The return value is the effective group ID of the process.
 
Availability: Available when a 'MiNT' cookie with a version of at least 0.95 exists.
 
Group: Process functions
 
See also: Binding   Pgetuid   Pgetgid   Pgeteuid
 

5.11.6.1 Bindings for Pgetegid

C: int32_t Pgetegid ( void );
 
Assembler:
 
move.w    #313,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.7 Pgeteuid

Name: »Pgeteuid« - Get effective user ID of a process.
 
Opcode: 312
 
Syntax: int32_t Pgeteuid ( void );
 
Description: The function Pgeteuid returns the effective user ID of the current process and resembles the system call Pgetuid. The difference lies in that here the effective user ID is returned.
 
This is normally identical to the actual user ID; however, if a program is running that has set the setuid bit, its effective user ID is equal to the (actual) ID of the owner of this program file.
 
File accesses are based, among other things, on the effective user ID, so that the setuid mechanism allows users (particularly the super-user) to permit access by other users.
 
Return value: The return value is the effective user ID of the process.
 
Availability: Available when a 'MiNT' cookie with a version of at least 0.95 exists.
 
Group: Process functions
 
See also: Binding   Pgetuid   Pgetgid   Pgetegid
 

5.11.7.1 Bindings for Pgeteuid

C: int32_t Pgeteuid ( void );
 
Assembler:
 
move.w    #312,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.8 Pgetgid

Name: »Pgetgid« - Get group ID of a processes.
 
Opcode: 276
 
Syntax: int16_t Pgetgid ( void );
 
Description: The function Pgetgid returns the actual group ID of the current calling processes. This is as number between 0 and 255, which sets the rights of the process group.
 
Return value: The return value is the actual group ID of the process.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Pgetuid   Pgeteuid   Pgetegid
 

5.11.8.1 Bindings for Pgetgid

C: int16_t Pgetgid ( void );
 
Assembler:
 
move.w    #276,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.9 Pgetgroups

Name: »Pgetgroups« - Gets the supplementary group IDs for the calling process.
 
Opcode: 327 (0x0147)
 
Syntax: int32_t Pgetgroups( int16_t len, int16_t *gidset);
 
Description: The function Pgetgroups obtains the supplementary group IDs for the calling process.
 
len specifies the length (in words) of the array to be filled with the supplementary group IDs available. This value must be a positive number not greater than NGROUPS_MAX. If len is a zero, the call will return the number of supplementary group ids currently available for the calling process.
 
gidset is a pointer to a word array to be filled with retrieved ids.
 
The NGROUPS_MAX value is returned by Sysconf().
 
Return value: Returns a number of supplementary group IDs for the process on success or a negative GEMDOS error code otherwise.
 
Availability: This function is available from MiNT 1.11 onwards.
 
Group: Process functions
 
See also: Binding   Psetgroups   Sysconf
 

5.11.9.1 Bindings for Pgetgroups

C: int32_t Pgetgroups( int16_t len, int16_t *gidset);
 
Assembler:
 
pea       gidset       ; Offset 4
move.w    len,-(sp)    ; Offset 2
move.w    #327,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.11.10 Pgetpgrp

Name: »Pgetpgrp« - Get current group number.
 
Opcode: 269
 
Syntax: int16_t Pgetpgrp ( void );
 
Description: The function Pgetpgrp returns the group number code of the currently active process. Process groups are normally used for job-control and similar purposes.
 
Return value: Process group number of the active process.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Bindings for Pgetpgrp   Pkill   Pgetpid   Psetpgrp
 

5.11.10.1 Bindings for Pgetpgrp

C: int16_t Pgetpgrp ( void );
 
Assembler:
 
move.w    #269,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.11 Pgetpid

Name: »Pgetpid« - Get current process ID.
 
Opcode: 267 (0x010b)
 
Syntax: int16_t Pgetpid ( void );
 
Description: The function Pgetpid returns the PID of the currently active (calling) process, i.e. the one that currently 'owns' the CPU; this is the filetype under which the current process is administered in the directory U:\PROC.
 
A PID is dynamically assigned to a process when it is created. You should make no assumption on the PID a process may have. For the kernel, the PID is a WORD but when you program in C, you should use the pid_t type, which complies with the POSIX standard. The FreeMiNT kernel's PID is always 0.
 
The PID is useful when it is important to identify a process among others in the system. Knowing the PID of a program, it is possible to do a lot of things: send it a signal with Psignal(), look for its name in /proc by searching with a "*.xxx" mask (xxx is the PID of the program which name we wanna know), etc.
 
Return value: PID of the active processes.
 
Availability: The function is available in MagiC from Version 3.0 on and under MiNT.
 
Group: Process functions
 
See also: Binding   Pgetpgrp   Pgetppid
 

5.11.11.1 Bindings for Pgetpid

C: int16_t Pgetpid ( void );
 
Assembler:
 
move.w    #267,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.12 Pgetppid

Name: »Pgetppid« - Get process ID for parent process.
 
Opcode: 268 (0x010c)
 
Syntax: int16_t Pgetppid ( void );
 
Description: The function Pgetppid returns the PID of the parent process of the currently active (calling) process.
 
In the FreeMiNT kernel, processes are represented as a tree. The root of the tree is the kernel itself (PID 0). At boot time, the kernel launches another process (which can be 'init' in case of a Unix-like setup, or an AES, a shell or whatever) specified by the INIT or GEM keyword in the mint.cnf file. This process will launch other processes (daemons, accessories, programs etc) that are its so-called children.
 
Therefore, every process (but the kernel, obviously) is created by its so-called parent. The Pgetppid() (get parent's PID) call allows determination the PID of the parent of the calling process. To have a good illustration of this, you can use the 'ps' command in your shell. You will see that all accessories parent is the AES, and that the daemons are started by the 'init' program.
 
Return value: Process ID of the parent (positive). If the current process was started directly from the kernel, 0 will be returned. A return value of -1 signals that the process has no parent.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and MagiC as of Version 3.0.
 
Group: Process functions
 
See also: Binding   Pgetpgrp   Pgetpid
 

5.11.12.1 Bindings for Pgetppid

C: int16_t Pgetppid ( void );
 
Assembler:
 
move.w    #268,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.13 Pgetpriority

Name: »Pgetpriority« - Get the current priority value for a process.
 
Opcode: 344 (0x0158)
 
Syntax: int32_t Pgetpriority ( int16_t which, int16_t who);
 
Description: The function Pgetpriority obtains the priority of the processes specified by which and who. The interpretation of parameter who depends on which:
 
PRIO_PROCESS (0) reads the priority of process with process ID who. A who of 0 implies the process id of the calling process.
 
PRIO_PGRP (1) reads the priority of the process group with process group ID who. If the priorities of the process differ, the lowest valued priority (i.e. the highest CPU usage priority) is returned. A who of 0 implies the process group id of the calling process.
 
PRIO_USER (2) reads the priority of the process of the user with user ID who. For multiple processes the lowest valued priority is returned. A who of 0 implies the user id of the calling process.
 
Library functions should first check for an error condition and then decrement the returned value by 20.
 
This call makes calls Pnice and Prenice obsolete.
 
Return value: Return value is either a negative error number in case of failure or the requested priority + 20 on success.
 
Availability: MiNT 1.15.0
 
Group: Process functions
 
See also: Binding   Psetpriority
 

5.11.13.1 Bindings for Pgetpriority

C: int32_t Pgetpriority ( int16_t which, int16_t who);
 
Assembler:
 
move.w    who,-(sp)    ; Offset 4
move.w    which,-(sp)  ; Offset 2
move.w    #344,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.14 Pgetuid

Name: »Pgetuid« - Get user ID of a process.
 
Opcode: 271
 
Syntax: int16_t Pgetuid ( void );
 
Description: The function Pgetuid returns the actual user ID of the current (calling) process. This is a number between 0 and 255 that determines the access rights permissions of the process, and can be used to differentiate the individual users in multi-user systems.
 
Return value: The return value is the actual user ID of the process.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Pgetgid   Pgeteuid   Pgetegid
 

5.11.14.1 Bindings for Pgetuid

C: int16_t Pgetuid ( void );
 
Assembler:
 
move.w    #271,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.15 Pkill

Name: »Pkill« - Send a signal to one or more processes.
 
Opcode: 273
 
Syntax: int32_t Pkill ( int16_t pid, int16_t sig );
 
Description: The function Pkill sends the signal sig to one or more processes. The following apply for the parameter pid:
 
pid Meaning
   
> 0 The signal will be sent to the process with the specified pid
= 0 The signal will be sent to all processes of the corresponding process group (this includes the caller itself too!)
< 0 The signal will be sent to all processes with the group number -pid

The signal SIGNULL is not handled by Pkill in the usual way. It can be used to test the existence of a process. For this one sends it a SIGNULL, and checks whether Pkill returns with the value 0.
 
Since MagiC 6.01 (1998.10.10) are also PIDs < 0 supported.
 
Return value: The function can return the following results:
 
E_OK  : No error has arisen
EFILNF: If pid > 0 and the specified process no longer exists, or if pid < 0 and the specified process group has no members any more
EACCDN: If pid > 0, and the sending process has no EUID of 0 and in addition if the UID of the receiving process differs from the sending one
ERANGE: sig is an invalid signal

Note: If the current process receives the signal iself and is terminated, the function does not return!
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Psetpgrp   Psignal   Signals
 

5.11.15.1 Bindings for Pkill

C: int32_t Pkill ( int16_t pid, int16_t sig );
 
Assembler:
 
move.w    sig,-(sp)    ; Offset 4
move.w    pid,-(sp)    ; Offset 2
move.w    #273,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.16 Pmsg

Name: »Pmsg« - Send and receive messages.
 
Opcode: 293
 
Syntax: int32_t Pmsg ( int16_t mode, int32_t mbox, void *msg );
 
Description: The function Pmsg sends or receives a message to or from a 'mail box'. The operation to be executed in each case can be set with the bits of the parameter mode. The following apply:
 
mode Operation
   
0x0000 Block the process and don't return until a message is read from the specified mailbox mbox and placed in the structure pointed to by msg.
0x0001 Block the process and don't return until a process waiting for a message with mailbox ID mbox has received the message from the structure pointed to by msg.
0x0002 Block the process until a process waiting for a message with the mailbox ID mbox has received the message held in the structure pointed to by msg and a return message is received with mailbox ID 0xffffxxxx (where xxxx is the PID of the current process).
0x8000 An OR combination with this value allows the operation to be performed in a non-blocking mode.

The messages are 5 words long, namely two LONGwords and one SHORT (in that order). For this the two LONGs can be filled with any desired information by the process, while the SHORT should have the PID of the sender entered in it.
 
After the message has been sent, this SHORT contains the PID of the process that has read the message. Conversely, after reading a message it contains the PID of the processes that wrote the message.
 
If mode has the highest bit set and no readers or writers for the mailbox mbox exist, then the value -1 will be returned. Otherwise a read operation waits until a message has been written, or a write operation waits until a read process is ready.
 
Im mode 2 the writer says that it would like to wait for a reply. The idea behind this is that the process can put itself to sleep, and can be reawakened later by the process that receives the message. This will guarantee that the process that contains the original message is not blocked when writing the reply.
 
Return value: The function can return the following results:
 
E_OK : No error has arisen
EINVFN : Invalid value for the parameter mode
-1 : Bit 15 is set, and Pmsg would block
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists.
 
Group: Process functions
 
See also: Binding
 

5.11.16.1 Bindings for Pmsg

C: int32_t Pmsg ( int16_t mode, int32_t mbox, void *msg );
 
Assembler:
 
pea       msg          ; Offset 8
move.l    mbox,-(sp)   ; Offset 4
move.w    mode,-(sp)   ; Offset 2
move.w    #293,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $C(sp),sp    ; Correct stack

5.11.17 Pnice

Name: »Pnice« - Alter priority of the calling process.
 
Opcode: 266
 
Syntax: int16_t Pnice ( int16_t delta );
 
Description: The function Pnice alters the priority of the process calling it by the value delta. A higher priority means that the process receives a larger time-slice, i.e. it is not switched over so often. In the same way, a lower priority means that the time-slice of the process is reduced, and so it must yield time to the CPU more often.
 
For the parameter delta the following must apply:
- 20 <= delta <= 20.
 
The function Pnice corresponds to Prenice (Pgetpid, delta) and is implemented for backwards compatibility.
 
Return value: The function returns the current process switching priority. This is set to 0 by default. Higher or lower values mean that the process is allocated respectively a larger or smaller time-slice.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and MagiC since Version 6.20 (2000-01-02).
 
Group: Process functions
 
See also: Binding   Prenice
 

5.11.17.1 Bindings for Pnice

C: int16_t Pnice ( int16_t delta );
 
Assembler:
 
move.w    delta,-(sp)  ; Offset 2
move.w    #266,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.18 Prenice

Name: »Prenice« - Adjust priority of a specified process.
 
Opcode: 295
 
Syntax: int32_t Prenice ( int16_t pid, int16_t delta );
 
Description: The function Prenice alters the priority of the process with the ID pid by the value delta. A higher priority means that the process receives a larger time-slice, i.e. it is not switched over so often. In the same way, a lower priority means that the time-slice of the process is reduced, and so it must yield time to the CPU more often.
 
For the parameter delta the following must apply:
- 20 <= delta <= 20.
 
Return value: The function returns the current process switching priority. This is set to 0 by default. Higher or lower values mean that the process is allocated respectively a larger or smaller time-slice.
 
In case of error the function returns:
 
EFILNF: The specified process does not exist
EACCDN: The specified process has a different user ID than the calling process
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists and MagiC since version 6.20 (2000-01-02).
 
Group: Process functions
 
See also: Bindings for Prenice   Pnice
 

5.11.18.1 Bindings for Prenice

C: int32_t Prenice ( int16_t pid, int16_t delta );
 
Assembler:
 
move.w    delta,-(sp)  ; Offset 4
move.w    pid,-(sp)    ; Offset 2
move.w    #295,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.19 Prusage

Name: »Prusage« - Obtain resource information about current process.
 
Opcode: 286
 
Syntax: int32_t Prusage ( int32_t *r );
 
Description: The function Prusage returns information about the system resources required by the current process.
 
The information is passed to the outside by a pointer r to an array of 8 LONGs; the allocation is as follows:
 
r[0]: Process time spent in MiNT kernel
r[1]: Process time spent in its own program code
r[2]: Total process time spent by children of this process in MiNT kernel
r[3]: Total process time spent by children of this process in their own program code
r[4]: Memory allocated by process (in bytes)
r[5]: Reserved for future use
r[6]: Reserved
r[7]: Reserved

All times are given in milliseconds.
 
Return value: The function has no direct result.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Psetlimit
 

5.11.19.1 Bindings for Prusage

C: int32_t Prusage ( int32_t *r );
 
Assembler:
 
pea       r            ; Offset 2
move.w    #286,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.20 Psemaphore

Name: »Psemaphore« - Create, use or destroy a semaphore.
 
Opcode: 308
 
Syntax: int32_t Psemaphore ( int16_t mode, int32_t id, int32_t timeout );
 
Description: The function Psemaphore implements non-counting semaphores. Only one process can access a semaphore at the same time.
 
Semaphores can be used, for instance, to synchronise accesses to data structures in shared memory by different subprocesses: Hence a subprocess must try, before it accesses memory, to obtain possession of the semaphore. This can be created during initialisation, for instance, and removed again at program termination.
 
Semaphores are identified by a name. This name is a LONGword that may contain four ASCII characters. Semaphores whose name starts with an underscore '_' are reserved for the operating system.
 
The parameter timeout is only used in mode 2. The following assignments apply:
 
timeout =  0: Return immediately.
  = -1: No timeout (wait indefinitely).

Other values for timeout specify the delay time in milliseconds before a timeout occurs.
 
The following values are possible for the parameter mode:
 
mode Meaning
   
0 Create a semaphore with the ID id (and grant ownership to the calling process)
1 Destroy semaphore with the ID id; this works only if the semaphore is owned by the caller
2 Request ownership of the semaphore with the ID id; this blocks the caller until the semaphore becomes available, or a timeout occurs
3 Release ownership of semaphore with the ID id; this works only if the semaphore is owned by the caller

Note: When a process creates a semaphore, it also owns it immediately. So that other processes may use it, it must first be released. As the creation of a semphore has to reserve internal memory, the function should be used frugally.
 
If a blocked process is waiting for a semaphore (before the timeout occurs), and a different process destroys the semaphore, then the function Psemaphore returns with the message ERANGE, as the requested semaphore no longer exists.
 
When a process terminates, all semaphores owned by it are released automatically (but not destroyed). The ownership of a semaphore can not be inherited (say with Pfork). If a process creates a semaphore and then crashes, the semaphore remains and cannot be removed any more.
 
In MagiC, plausibility checks ensure that no system semaphores can be released; in addition, only modes 2 and 3 are supported at present.
 
Return value: The function can return the following results:
 
E_OK  : No error has arisen
ERROR : A semaphore was requested that the caller already owns
EACCDN: An attempt was made to create a semaphore that already esists, the caller is not the owner of the semaphore or a timeout has occurred
ERANGE: The specified semaphore does not exist
Availability: Available when a 'MiNT' cookie with a version of at least 0.92 exists and MagiC as of version 3.0.
 
Group: Process functions
 
See also: Binding   Semaphores in MagiC
 

5.11.20.1 Bindings for Psemaphore

C: int32_t Psemaphore ( int16_t mode, int32_t id, int32_t timeout );
 
Assembler:
 
move.l    timeout,-(sp)  ; Offset 8
move.l    id,-(sp)       ; Offset 4
move.w    mode,-(sp)     ; Offset 2
move.w    #308,-(sp)     ; Offset 0
trap      #1             ; GEMDOS
lea       $C(sp),sp      ; Correct stack

5.11.21 Psetauid

Name: »Psetauid« - Set user ID of a process at the start.
 
Opcode: 326 (0x0146)
 
Syntax: int16_t Psetauid ( int16_t id );
 
Description: The function Psetauid sets the starting user ID of the current process. This can only happen once. Together with Pgetauid one can ascertian who was the first logged-in user in a multi-user environment. The parameter id is the desired start ID.
 
Warning: This function is optional, hence a call may be answered with EINVFN.
 
Return value: Unknown at present.
 
Availability: Available when a 'MiNT' cookie with a version of at least 0.92 exists.
 
Group: Process functions
 
See also: Binding   Pgetauid
 

5.11.21.1 Bindings for Psetauid

C: int16_t Psetauid ( int16_t id );
 
Assembler:
 
move.w    id,-(sp)     ; Offset 2
move.w    #326,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.22 Psetegid

Name: »Psetegid« - Set the effective group ID for the calling process.
 
Opcode: 324 (0x0144)
 
Syntax: int32_t Psetegid ( int16_t egid );
 
Description: egid specifies the new effective group ID for the calling process.
 
Prior to MiNT version 1.12, this call contained a bug affecting its functionality. Setting effective group id needs root privileges.
 
This call is often used by daemon processes to downgrade their privileges to user level.
 
Return value: Returns new egid on success or a negative GEMDOS error-code otherwise.
 
Availability: MiNT 1.11
 
Group: Process functions
 
See also: Binding   Pseteuid   Psetgid   Psetregid
 

5.11.22.1 Bindings for Psetegid

C: int32_t Psetegid ( int16_t egid );
 
Assembler:
 
move.w    egid,-(sp)   ; Offset 2
move.w    #324,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.23 Pseteuid

Name: »Pseteuid« - Sets the effective user ID for the calling process.
 
Opcode: 323 (0x0143)
 
Syntax: int32_t Pseteuid ( int16_t euid );
 
Description: euid specifies the new effective user ID for the calling process.
 
Prior to MiNT version 1.12 this call contained a bug affecting its functionality. Setting effective user ID needs root privileges.
 
This call is often used by daemon processes to downgrade their privileges to user level.
 
Return value: Returns new euid on success or a negative GEMDOS error code otherwise.
 
Availability: As of MiNT 1.11.
 
Group: Process functions
 
See also: Binding   Psetegid   Psetuid   Psetreuid
 

5.11.23.1 Bindings for Pseteuid

C: int32_t Pseteuid ( int16_t euid );
 
Assembler:
 
move.w    euid,-(sp)   ; Offset 2
move.w    #323,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.24 Psetgid

Name: »Psetgid« - Alter the group ID of the calling process.
 
Opcode: 277
 
Syntax: int16_t Psetgid ( int16_t id );
 
Description: The function Psetgid sets the group ID of the current process to id. This must be a number between 0 and 255.
 
Return value: The function can return the following results:
 
0-255 : No error has occurred (the new ID)
EACCDN: The process does not have the authority to alter its ID
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Psetuid
 

5.11.24.1 Bindings for Psetgid

C: int16_t Psetgid ( int16_t id );
 
Assembler:
 
move.w    id,-(sp)     ; Offset 2
move.w    #277,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.25 Psetgroups

Name: »Psetgroups« - Sets the supplementary group IDs for the calling process.
 
Opcode: 328 (0x0148)
 
Syntax: int32_t Psetgroups( int16_t len, int16_t *gidset);
 
Description: The function Psetgroups sets the supplementary group IDs for the calling process.
 
len specifies the length (in words) of the array containing the supplementary group IDs to be set. This value must be a positive number not greater than NGROUPS_MAX. If len is a zero, the call will return the number of supplementary group ids those have been set.
 
gidset is a pointer to a word array containing the new supplementary group IDs for the process.
 
Setting new supplementary group IDs needs root privileges.
 
The NGROUPS_MAX value is returned by Sysconf().
 
Return value: Returns a number of new supplementary group IDs for the process on success or a negative GEMDOS error code otherwise.
 
Availability: Available from MiNT 1.11 onwards.
 
Group: Process functions
 
See also: Binding   Pgetgroups   Sysconf
 

5.11.25.1 Bindings for Psetgroups

C: int32_t Psetgroups( int16_t len, int16_t *gidset);
 
Assembler:
 
peam      gidset       ; Offset 4
move.w    len,-(sp)    ; Offset 2
move.w    #328,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.11.26 Psetlimit

Name: »Psetlimit« - Set or obtain allocation limits of the system resources.
 
Opcode: 287
 
Syntax: int32_t Psetlimit ( int16_t lim, int32_t value );
 
Description: The function Psetlimit serves for setting or obtaining resource allocation limits for the current process. The parameter lim determines the desired resource type:
 
lim Meaning
   
1 Max. CPU-time for the process (milliseconds)
2 Max. total memory allowed for process in bytes
3 Max. allocatable memory for the process (in bytes)

The difference between 2 and 3 is that the total memory also includes the TEXT, DATA and BSS segments of the process.
 
With the help of this function the resource allocation limits are set both for the current process as well as individually for all child processes created later. So if a process sets a CPU limit and later creates several child processes, then this CPU limit applies also for each individual child process, and not, say, for all child processes together.
 
The parameter value determines the maximum value that a resource is allowed to take. A value of 0 here means that the resource is unlimited. A negative value here returns the current value, leaving it unaltered.
 
Note: There are no restrictions on increasing the limits. Each process may alter any of its limits or even set it to unlimited.
 
Memory allocation limits do not apply for Pexec. If, say, a process is limited to 256 kbyte, it can nevertheless use Pexec to launch a child process that uses more memory. Warning: This does not apply in MagiC; here memory limits are inherited at Pexec!
 
Memory limitations are not valid retrospectively. If, for instance, a process owns 256 kbyte and then calls Psetlimit to reduce its requirements to 128 kbyte, then though it will not be terminated, it can not allocate any memory any more until its size falls under the specified 128 kbyte.
 
Limitations of the CPU-time on the other hand do act retrospectively. If a process reduces its CPU-time below the previously valid value, then it will receive a SIGXCPU signal immediately.
 
Warning: Invalid function numbers and those that are not supported by MagiC return EINVFN.
 
Note about MagiC: If a program has been modified with the utility program LIMITMEM, then this setting takes precedence over the calling process' memory limit. Psetlimit is supported by the extended shel_write mode; due to this, memory-limited applications may also be started in parallel.
 
Return value: The function returns the old limit value.
 
Availability: MagiC from Version 4.0 (17.09.1996) onwards and as of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Prusage   Signals
 

5.11.26.1 Bindings for Psetlimit

C: int32_t Psetlimit ( int16_t lim, int32_t value );
 
Assembler:
 
move.l    value,-(sp)  ; Offset 4
move.w    lim,-(sp)    ; Offset 2
move.w    #287,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.11.27 Psetpgrp

Name: »Psetpgrp« - Get/Set process group number of a process.
 
Opcode: 270
 
Syntax: int16_t Psetpgrp ( int16_t pid, int16_t newgrp );
 
Description: The function Psetpgrp alters the group number of the process with the ID pid to the value newgrp, or inquires the group number if newgrp is negative. The process must have the same UID as the current process, or be the parent of it.
 
If pid = 0, the process group of the current process will be set. If newgrp = 0, the process group will be set to the value of the PID of the current process.
 
Return value: The function can return the following results:
 
>= 0  : No error (new or current process group number)
EFILNF: The process pid does not exist
EACCDN: The process pid has a different UID, and is not a child of the calling process
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Pkill   Pgetpgrp   Pgetpid
 

5.11.27.1 Bindings for Psetpgrp

C: int16_t Psetpgrp ( int16_t pid, int16_t newgrp );
 
Assembler:
 
move.w    newgrp,-(sp)  ; Offset 4
move.w    pid,-(sp)     ; Offset 2
move.w    #270,-(sp)    ; Offset 0
trap      #1            ; GEMDOS
addq.l    #6,sp         ; Correct stack

5.11.28 Psetpriority

Name: »Psetpriority« - Set the current priority value for a process.
 
Opcode: 345 (0x0159)
 
Syntax: int32_t Psetpriority ( int16_t which, int16_t who, int16_t pri );
 
Description: The function Psetpriority sets the priority pri (not an increment but an absolute value) for the processes specified by which and who. The interpretation of parameter who depends on which:
 
PRIO_PROCESS (0) sets the priority of process with process ID who. A who of 0 implies the process ID of the calling process.
 
PRIO_PGRP (1) sets the priority of the process group with process group ID who. A who of 0 implies the process group ID of the calling process.
 
PRIO_USER (2) sets the priority of the process of the user with user ID who. A who of 0 implies the user ID of the calling process.
 
The pri argument is silently changed to the maximum (resp. minimum) possible value if it is not in the range between PRIO_MIN (-20) and PRIO_MAX (+20).
 
This call makes calls Pnice and Prenice obsolete.
 
Return value: The function returns E_OK on success or a negative error-code otherwise. The following error conditions are defined:
 
EINVAL, invalid argument for who, which or pri.
 
EACCES, the calling process is not an owner of one or more of the selected processes; the other selected processes are still affected
 
EPERM, the calling process does not have privileges to change the priority of one or more of the selected processes; this can only happen if an attempt was made to change the priority of a process to a positive value
 
ESRCH, the combination of which and who does not match any existing process.
 
The error condition reported is the last error condition encountered (in other words if both EACCES and EPERM occur the return value is arbitrary).
 
Availability: As of MiNT 1.15.0
 
Group: Process functions
 
See also: Binding   Pgetpriority
 

5.11.28.1 Bindings for Psetpriority

C: int32_t Psetpriority ( int16_t which, int16_t who, int16_t pri );
 
Assembler:
 
move.w    pri,-(sp)    ; Offset 6
move.w    who,-(sp)    ; Offset 4
move.w    which,-(sp)  ; Offset 2
move.w    #345,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.11.29 Psetregid

Name: »Psetregid« - Set the real and/or effective group ID for the calling process.
 
Opcode: 335 (0x014f)
 
Syntax: int32_t Psetregid ( int16_t rgid, int16_t egid);
 
Description: The function Psetregid sets the real and/or effective group ID for the calling process.
 
rgid specifies the new real group ID and egid specifies the new effective group ID for the calling process. If either argument is -1, only the other gets changed
 
Setting group IDs needs root privileges.
 
This call is often used by daemon processes to downgrade their privileges to user level.
 
Return value: Returns E_OK on success or a negative error-code otherwise.
 
Availability: As of MiNT 1.12.
 
Group: Process functions
 
See also: Binding   Psetreuid   Psetegid
 

5.11.29.1 Bindings for Psetregid

C: int32_t Psetregid ( int16_t rgid, int16_t egid);
 
Assembler:
 
move.w    egid,-(sp)   ; Offset 4
move.w    rgid,-(sp)   ; Offset 2
move.w    #335,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.30 Psetreuid

Name: »Psetreuid« - Sets the real and/or effective user ID for the calling process.
 
Opcode: 334 (0x014e)
 
Syntax: int32_t Psetreuid ( int16_t ruid, int16_t euid);
 
Description: The function Psetreuid sets the real and/or effective user ID for the calling process.
 
ruid specifies the new real user ID and euid specifies the new effective user ID for the calling process. If either argument is -1, only the other gets changed.
 
Setting user ids needs root privileges.
 
This call is often used by daemon processes to downgrade their privileges to user level.
 
Return value: Returns E_OK on success or a negative GEMDOS error code otherwise.
 
Availability: As of MiNT 1.12.
 
Group: Process functions
 
See also: Binding   Psetregid   Pseteuid
 

5.11.30.1 Bindings for Psetreuid

C: int32_t Psetreuid ( int16_t ruid, int16_t euid);
 
Assembler:
 
move.w    euid,-(sp)   ; Offset 4
move.w    ruid,-(sp)   ; Offset 2
move.w    #334,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.31 Psetuid

Name: »Psetuid« - Alter the user ID of a process.
 
Opcode: 272
 
Syntax: int16_t Psetuid ( int16_t id );
 
Description: The function Psetuid sets the user ID of the current process to id. This must be a number between 0 and 255. The function fails if the user ID of the process does not have the value 0, i.e. once set, the user ID can no longer be altered.
 
Return value: The function can return the following results:
 
0-255 : No error has occurred (the new ID)
EACCDN: The process does not have authority to alter its ID
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Psetgid
 

5.11.31.1 Bindings for Psetuid

C: int16_t Psetuid ( int16_t id );
 
Assembler:
 
move.w    id,-(sp)     ; Offset 2
move.w    #272,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.32 Psigaction

Name: »Psigaction« - Set default action for a specified signal.
 
Opcode: 311
 
Syntax: int32_t Psigaction ( int16_t sig, struct sigaction *act, struct sigaction *oact );
 
Description: The function Psigaction alters the response to the signal sig. The parameter act for this is either NULL, or points to a sigaction structure that describes the behaviour of the signal handling. The following applies for the component sa_handler:
 
sa_handler Meaning
   
0 On arrival of the signal the default action for the signal will be executed
1 The signal sig will be ignored; If it currently present, it will be deleted

Any other value of sa_handler is interpreted as an address of a function that will be called when the signal occurs. This function is passed a LONG value via the stack that corresponds to the relevant signal number. In this way it is possible to use the signal-handler for several signals.
 
While a signal is being processed, it cannot be sent again. Furthermore, one should note that (in contrast to some Unix versions) the signal handling before the execution of the handler is not reset to the default handler.
 
The signal-handler must either be terminated with RTS (Return To Sender), or Psigreturn called to indicate that the signal handling has been concluded. Following this, the blocking of the signal will be lifted. Psigreturn additionally performs some internal mopping up in the kernel, necessary in case the signal-handler is not terminated (longjump).
 
Signal-handlers can make any BIOS, XBIOS and GEMDOS calls. AES or VDI calls on the other hand are not permitted. However this does not apply in MagiC; here one needs to heed several differences.
 
A Psigaction call has the side effect that the signal will be unmasked (i.e. released). In this way a process, while handling a signal, can reset it and then send it to itself again - for instance to suspend itself while a signal for job-control is processed. The signal handling is secured against Pfork/Pvfork.
 
Signals that are ignored by a process will also be ignored by its child after a Pexec call. Additionally, signals that are intercepted by a signal-handler will be reset in the child process to the default value.
 
The component sa_flags of the sigaction structure defines an additional, signal-specific behaviour: If sig is the signal SIGCHLD, and the SA_NOCLDSTOP bit is set in sa_flags, then SIGCHLD is sent to the process only when one of its children terminates (and not just when a child is suspended by a job-control signal).
 
Return value: The function can return the following results:
 
E_OK  : No error has arisen
EACCDN: Signal cannot be intercepted by the user
ERANGE: sig is an invalid signal
Availability: Available when a 'MiNT' cookie with a version of at least 0.95 exists, and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Pkill   Psigblock   Psignal   Psigreturn   Signals
 

5.11.32.1 Bindings for Psigaction

C: int32_t Psigaction ( int16_t sig, struct sigaction *act, struct sigaction *oact );
 
Assembler:
 
pea       oact         ; Offset 8
pea       act          ; Offset 4
move.w    sig,-(sp)    ; Offset 2
move.w    #311,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $C(sp),sp    ; Correct stack

5.11.33 Psigblock

Name: »Psigblock« - Alter signal mask.
 
Opcode: 278
 
Syntax: int32_t Psigblock ( int32_t mask );
 
Description: The function Psigblock blocks selected signals from delivery. It adds the signals specified in mask to the set of currently blocking signals. For this, each bit of the parameter mask represents one signal. If bit n in mask is set, it means that the signal with the number n will be blocked.
 
One should note that some signals (e.g. SIGKILL) can not be blocked. The kernel will delete these signals from mask before any change of the signal set is performed.
 
Furthermore it should be pointed out that blocked signals also remain blocked via Pfork/Pvfork calls. After a Pexec call the child always starts with an empty set of signals to be blocked, irrespective of which signals were blocked by its parent.
 
Warning: This function is optional, hence a call may be answered with EINVFN.
 
Return value: The function returns the set of blocked signals that were valid before the call. So with a Psigsetmask call the old set can be recovered again.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and in MagiC from Version 4.50 onwards.
 
Group: Process functions
 
See also: Binding   Psigsetmask   Signals
 

5.11.33.1 Bindings for Psigblock

C: int32_t Psigblock ( int32_t mask );
 
Assembler:
 
move.l    mask,-(sp)   ; Offset 2
move.w    #278,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.34 Psigintr

Name: »Psigintr« - Assigns a signal to a particular exception vector.
 
Opcode: 318 (0x013e)
 
Syntax: int32_t Psigintr ( int16_t vec, int16_t sig );
 
Description: The function Psigintr assigns a signal to a particular exception vector. When the exception occurs, the kernel will send the signal to the process.
 
vec specifies the exception vector. This is the same value as specified for Setexc() call. sig specifies the signal number that is supposed to be delivered when an exception assigned to the vector vec occurs. When both sig and vec are zero, all handlers installed by your program are removed.
 
You should install a signal-handler prior to making this call, otherwise your process will most probably get killed by the first occurrence of the interrupt assigned to vec vector.
Also notice that the function is not available on machines equipped with 68000 and 68010 processors.
 
This function has been totally rewritten as of MiNT version 1.15.1. However, the only change visible to programs is that the old value of vec is no longer returned (it had little use anyway). Also, since long stack frames are needed, a 68020 or newer processor is required.
 
The handler set up by Psigintr gets removed when your process terminates.
 
Return value: Returns E_OK on success, or a negative GEMDOS error code otherwise:
 
EBADARG: A signal or vector number was specified outside the allowed range. Only autovectors ($60-$7c), traps ($80-$bc) and user defined interrupts ($0100-$03fc) are allowed (other interrupts already generate fixed signals).
ENOMEM: The kernel ran out of memory while trying to allocate RAM for internal structures needed by this call.
ENXIO: The interrupt you want to register has no service routine installed.
ENOSYS: The function is not available (wrong architecture).
Availability: When a 'MiNT' cookie with a version of at least 1.11 exists. As of MiNT version 1.15.1 this call is available only on machines equipped with 68020 processor or higher.
 
This function has been disabled as of FreeMiNT 1.16.
 
Group: Process functions
 
See also: Binding   Pause   Pkill   Psigsetmask   Psignal   Signals
 

5.11.34.1 Bindings for Psigintr

C: int32_t Psigintr ( int16_t vec, int16_t sig );
 
Assembler:
 
move.w    sig,-(sp)    ; Offset 4
move.w    vec,-(sp)    ; Offset 2
move.w    #318,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.35 Psignal

Name: »Psignal« - Alter manner of signal handling.
 
Opcode: 274
 
Syntax: int32_t Psignal ( int16_t sig, int32_t handler );
 
Description: The function Psignal alters the action to be taken when the signal sig arrives. The parameter handler can assume 3 possible values:
 
handler Meaning
   
0 The signal will be answered with the default action
1 The signal will be ignored by the process; if currently present, it will be deleted

Any other value will be interpreted as the address of a user function that will be called when the signal sig appears. This function is passed a LONG value (via the stack) that corresponds to the signal number. In this way it is possible to use the signal-handler for several signals.
 
While a signal is being processed, it cannot be sent again. Furthermore, one should note that (in contrast to some Unix versions) the signal handling before the execution of the handler is not reset to the default handler.
 
The signal-handler must either be terminated with RTS (Return To Sender), or Psigreturn called to indicate that the signal handling has been concluded. Following this, the blocking of the signal will be lifted. Psigreturn additionally performs some internal mopping up in the kernel, necessary in case the signal-handler is not terminated (longjump).
 
Signal-handlers can make any BIOS, XBIOS and GEMDOS calls. AES or VDI calls on the other hand are not permitted. However this does not apply in MagiC; here one needs to heed several differences.
 
A Psigaction call has the side effect that the signal will be unmasked (i.e. released). In this way a process, while handling a signal, can reset it and then send it to itself again - for instance to suspend itself while a signal for job-control is processed. The signal handling is secured against Pfork/Pvfork.
 
Signals that are ignored by a process will also be ignored by its child after a Pexec call. Additionally, signals that are intercepted by a signal-handler will be reset in the child process to the default value.
 
Return value: The function returns the old value of the signal-handler. This is either 0, 1 or the address of the handler.
 
Im case of error, the following results are returned:
 
EACCDN: Signal cannot be intercepted by the user
ERANGE: sig is an invalid signal
Availability: As of the first in MultiTOS integrated MiNT version 1.04 and MagiC as of Version 4.50.
 
Group: Process Functions
 
See also: Binding   Pkill   Psigaction   Psigblock   Psigreturn   Signals
 

5.11.35.1 Bindings for Psignal

C: int32_t Psignal ( int16_t sig, int32_t handler );
 
Assembler:
 
move.l    handler,-(sp)  ; Offset 4
move.w    sig,-(sp)      ; Offset 2
move.w    #274,-(sp)     ; Offset 0
trap      #1             ; GEMDOS
addq.l    #8,sp          ; Correct stack

5.11.36 Psigpause

Name: »Psigpause« - Set a new signal mask and then suspend process until the arrival of a signal.
 
Opcode: 310
 
Syntax: void Psigpause ( int32_t mask );
 
Description: The function Psigpause sets a new signal mask mask, and suspends the called process until a signal arrives that is not masked or ignored.
 
If a handler has been installed for this signal with Psignal, then this will be called before the function returns. If the handler executes a longjump to another part of the program, or the process terminates, then the function will never return.
 
Note: When the function returns, the signal mask will be reset to the value that applied before the call of Psigpause. Thus the signal mask set by the function is only valid temporarily. In MagiC, problems may arise if several threads call this function at the same time, as the signal mask here is process-global.
 
Return value: The function returns always 0.
 
Availability: Available when a 'MiNT' cookie with a version of at least 0.95 exists, and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Pause   Psigblock   Psignal   Psigsetmask   Signals
 

5.11.36.1 Bindings for Psigpause

C: void Psigpause ( int32_t mask );
 
Assembler:
 
move.w    mask,-(sp)   ; Offset 2
move.w    #310,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.37 Psigpending

Name: »Psigpending« - Check which signals have been sent but not yet processed.
 
Opcode: 291
 
Syntax: int32_t Psigpending ( void );
 
Description: The function Psigpending returns the signals that have been sent to the calling process, but not yet handled (say because they are blocked with Psigblock or because they are currently being processed).
 
Return value: The function returns the desired signals as a bit-mask in a LONG; for each bit n set, signal n is waiting to be processed.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Psigblock   Psignal   Psigsetmask   Signals
 

5.11.37.1 Bindings for Psigpending

C: int32_t Psigpending ( void );
 
Assembler:
 
move.w    #291,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.38 Psigreturn

Name: »Psigreturn« - Prepare exit from a signal-handler.
 
Opcode: 282
 
Syntax: void Psigreturn ( void );
 
Description: The function Psigreturn prepares for the exit from a signal-handler. As this happens automatically when the handler returns, calling Psigreturn is only necessary if the handler executes a non-local jump (perhaps with longjump) rather than using RTS.
 
The call has no effect when no signal is being processed at the time.
 
In MagiC, the thread of the active signal-handler will become the main thread of the process and then be removed. All other signal processes will be removed as well (nesting). The locked semaphores of the main thread will be released, and the supervisor stack will be reset to the value at process start.
 
Return value: The function has no direct result under MiNT/MultiTOS; in MagiC the value EACCDN will be returned if the caller is not a signal-handling routine, or the value E_OK otherwise.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Psignal   Signals   Signal-handler in MagiC
 

5.11.38.1 Bindings for Psigreturn

C: void Psigreturn ( void );
int32_t Psigreturn ( void );
 
Assembler:
 
move.w    #282,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.39 Psigsetmask

Name: »Psigsetmask« - Set/replace a signal mask.
 
Opcode: 279
 
Syntax: int32_t Psigsetmask ( int32_t mask );
 
Description: The function Psigsetmask replaces the set of signals that are currently to be blocked completely by the signals specified in the parameter mask.
 
One should note that some signals (e.g. SIGKILL) can not be blocked. The kernel will delete these signals from mask before any change of the signal set is performed.
 
Furthermore it should be pointed out that blocked signals also remain blocked via Pfork/Pvfork calls. After a Pexec call the child always starts with an empty set of signals to be blocked, irrespective of which signals were blocked by its parent.
 
Return value: The function returns the set of the blocked signals that were valid before the call.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and MagiC as of Version 4.50.
 
Group: Process functions
 
See also: Binding   Psigblock   Signals   Signal-handler in MagiC
 

5.11.39.1 Bindings for Psigsetmask

C: int32_t Psigsetmask ( int32_t mask );
 
Assembler:
 
move.l    mask,-(sp)   ; Offset 2
move.w    #279,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.40 Psysctl

Name: »Psysctl« - Get or set system information.
 
Opcode: 350 (0x015e)
 
Syntax: int32_t Psysctl ( int32_t *name, uint32_t namelen, void *old, uint32_t *oldlenp, void *new, uint32_t newlen );
 
Description: The function Psysctl retrieves system information and allows processes with appropriate privileges to set system information. The system information may be an integer, a string or a structure.
 
name and namelen specify the system information to retrieve. name is an array of longwords which defines a path to the actual value. The first longword holds the top level name, the second longword is the second level name... namelen is the size of this array.
 
The information is copied into the buffer specified by old and oldlenp.
 
Before the call, oldlenp points to a long specifiying the size of the buffer. After the call, this long word is set to the amount of copied data.
 
If both old and oldlenp are set to NULL, the old value is not returned.
 
If only old is set to NULL, oldlenp will be set to the amount of available data.
 
To set a new value, new is set to a pointer to a buffer of lenght newlen. Otherwise, new should be set to NULL and newlen set to 0.
 
The top level names are defined with the following CTL_ prefix.
 
CTL_KERN (1): Kernel
 
KERN_OSTYPE=1 (string) System version
KERN_OSRELEASE=2 (string) System release
KERN_OSREV=3 (integer) System revision
KERN_VERSION=4 (string) Compile time information
KERN_HOSTNAME=5 (string) Hostname
KERN_DOMAINNAME=6 (string) (YP) Domainname
KERN_SECURELVL=7 (integer) System security level
KERN_MAXPROC=8 (integer) Max processes
KERN_MAXFILES=9 (integer) Max open files
KERN_NGROUPS=10 (integer) Number of supplemental group IDs
KERN_IOV_MAX=11 (integer) Max iovec's for readv(2) etc.
KERN_LOGIN_NAME_MAX=12 (integer) Max length login name + NUL
KERN_BOOTTIME=13 (struct timeval) Time kernel was booted
KERN_INITIALTPA=14 (integer) Max TPA size of a process
KERN_SYSDIR=15 (string) The system directory

CTL_HW (2): Generic CPU/IO
 
HW_MACHINE=1 (string) Machine class
HW_MACHINE_ARCH=2 (string) Machine architecture
HW_MODEL=3 (string) Specific machine model
HW_NCPU=4 (integer) Number of CPUs
HW_BYTEORDER=5 (integer) Machine byte order
HW_PAGESIZE=6 (integer) Software page size
HW_FREEPHYSMEM=7 (integer) Free physical memory

CTL_MACHDEP (3): Machine dependent (not yet implemented)
 
CTL_DEBUG (4): Debugging parameters (not yet implemented)
 
CTL_PROC (5): Per-proc attributes
The second level name specifies the process ID (PROC_CURPROC or any PID), the third level name specifies the system information (PROC_PID_DEBUG).
 
PROC_CURPROC=0x7fffffff (2^31-1) (integer) Select the current process
Other value (integer) ID of specified process
PROC_PID_DEBUG=1 (integer) Process debug level

CTL_KBD (6): Keyboard configuration
 
KBD_PC_STYLE_CAPS=1 (integer) CAPS key operate in PC style mode
KBD_MOUSE_PIXELS=2 (integer) Keyboard mouse movement pixels
KBD_PIXELS_FINE=3 (integer) Keyboard mouse movement pixels 'fine'
Return value: The function can return the following results:
 
E_OK  : No error has arisen
ENOMEM : The amount of data available is greater than the size of the buffer supplied
EACCDN: An attempt was made to change a read-only value or was made by a process with insufficient privilege
ERANGE: The name array was less than two or greater than CTL_MAXNAME
ENOTDIR: name specifies an intermediate rather than terminal name
EOPNOTSUPP: name not found
ESRCH Process not found
Availability: This function is available as of FreeMiNT 1.15.12.
 
Group: Process functions
 
See also: Binding   Sysconf
 

5.11.40.1 Bindings for Psysctl

C: int32_t Psysctl ( int32_t *name, uint32_t namelen, void *old, uint32_t *oldlenp, void *new, uint32_t newlen );
 
Assembler:
 
move.l    newlen,-(sp)   ; Offset 22
pea       new,-(sp)      ; Offset 18
pea       oldlenp,-(sp)  ; Offset 14
pea       old,-(sp)      ; Offset 10
move.l    namelen,-(sp)  ; Offset 6
pea       name,-(sp)     ; Offset 2
move.w    #350,-(sp)     ; Offset 0
trap      #1             ; GEMDOS
lea       $1A(sp),sp     ; Correct stack

5.11.41 Pterm

Name: »Process termination« - Terminate a TOS program.
 
Opcode: 76
 
Syntax: void Pterm ( uint16_t retcode );
 
Description: The GEMDOS routine Pterm terminates a running process, and removes it from memory. The following apply:
 
Parameter Meaning
   
retcode Status that is returned to the calling program.
-32 = Should not be used, as one obtains this value for programs terminated by Control-C
 -1 = Should not be used, as one obtains this value from GEMDOS 0.15 onwards if a process crashes
  0 = No error has arisen
  1 = General error
  2 = Error in the parameters

Note about MagiC: Before any steps are taken, the vector etv_term is located via Setexc and jumped over. Subsequently, the process is cleaned up properly (including VDI workstations, informing all XFSs via xfs_pterm, closing of all opened files and current paths, and deleting the process file in directory U:\PROC).
 
Return value: The function does not return a result.
 
Availability: All GEMDOS versions.
 
Group: Process functions
 
See also: Binding   Pexec   Pterm0   Ptermres   XFS-concept in MagiC
 

5.11.41.1 Bindings for Pterm

C: void Pterm ( uint16_t retcode );
 
Assembler:
 
move.w    retcode,-(sp)  ; Offset 2
move.w    #76,-(sp)      ; Offset 0
trap      #1             ; GEMDOS
addq.l    #4,sp          ; Correct stack

5.11.42 Pterm0

Name: »Process termination« - Terminate a TOS program and return 0 to caller.
 
Opcode: 0
 
Syntax: void Pterm0 ( void );
 
Description: The GEMDOS routine Pterm0 terminates a TOS program and does not return again. The routine returns an exit code of 0.
 
Note: In MagiC this function is executed directly as Pterm(0).
 
Return value: The function does not return a result.
 
Availability: All GEMDOS versions.
 
Group: Process functions
 
See also: Binding   Pexec   Pterm   Ptermres
 

5.11.42.1 Bindings for Pterm0

C: void Pterm0 ( void );
 
Assembler:
 
move.w    #0,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.43 Ptermres

Name: »Terminate and stay resident« - Terminate a program but leave it in memory.
 
Opcode: 49
 
Syntax: void Ptermres ( int32_t keepcnt, int16_t retcode );
 
Description: The GEMDOS routine Ptermres terminates a program, yet leaves a part of the program's TPA intact and removes the memory left from GEMDOS's memory list. The following apply:
 
Parameter Meaning
   
keepcnt Number of bytes that are to be retained (applies from the start of the basepage and includes the length of the TEXT, DATA and BSS segments of the application plus length of the stack; minimum is 128 bytes). Important: The memory retained by this call may not be freed later since it has been removed completely from the GEMDOS memory list.
retcode Status that is returned to the calling program
-32 = Should not be used, as one obtains this value for programs terminated by Control-C
 -1 = Should not be used, as one obtains this value from GEMDOS 0.15 onwards if a process crashes
  0 = No error has arisen
  1 = General error
  2 = Error in the parameters

Note: In a network all lockings of the processes will be lifted.
 
Return value: The function does not return a result.
 
Availability: All GEMDOS versions.
 
Group: Process functions
 
See also: Binding   Pexec   Pterm   Pterm0
 

5.11.43.1 Bindings for Ptermres

C: void Ptermres ( int32_t keepcnt, int16_t retcode );
 
Assembler:
 
move.w    retcode,-(sp)  ; Offset 6
move.l    keepcnt,-(sp)  ; Offset 2
move.w    #49,-(sp)      ; Offset 0
trap      #1             ; GEMDOS
addq.l    #8,sp          ; Correct stack

5.11.44 Ptrace

Name: »Ptrace« - Process tracing and debugging
 
Opcode: 320
 
Syntax: int16_t Ptrace(int16_t request, int16_t pid, void * addr, int32_t data)
 
Description: Ptrace provides tracing and debugging facilities. It allows one process (the tracing process) to control another (the traced process). Most of the time, the traced process runs normally, but when it receives a signal (see sigaction(2)), it stops. The tracing process is expected to notice this via wait(2) or the delivery of a SIGCHLD signal, examine the state of the stopped process, and cause it to terminate or continue as appropriate. Ptrace is the mechanism by which all this happens.
 
The request argument specifies what operation is being performed; the meaning of the rest of the arguments depends on the operation, but except for one special case noted below, all ptrace calls are made by the tracing process, and the pid argument specifies the process ID of the traced process. request can be:
 
PT_TRACE_ME (0) This request is the only one used by the traced process; it declares that the process expects to be traced by its parent. All the other arguments are ignored. (If the parent process does not expect to trace the child, it will probably be rather confused by the results; once the traced process stops, it cannot be made to continue except via ptrace.) When a process has used this request and calls execve(2) or any of the routines built on it (such as execv(3)), it will stop before executing the first instruction of the new image. Also, any setuid or setgid bits on the executable being executed will be ignored.
 
PT_READ_I (1), PT_READ_D (2)
These requests read a single int of data from the traced process' address space. Traditionally, ptrace has allowed for machines with distinct address spaces for instruction and data, which is why there are two requests: conceptually, PT_READ_I reads from the instruction space and PT_READ_D reads from the data space. In the current NetBSD implementation, these two requests are completely identical. The addr argument specifies the address (in the traced process' virtual address space) at which the read is to be done. This address does not have to meet any alignment constraints. The value read is returned as the return value from ptrace.
 
PT_WRITE_I (4), PT_WRITE_D (5)
These requests parallel PT_READ_I and PT_READ_D, except that they write rather than read. The data argument supplies the value to be written.
 
PT_CONTINUE (7) The traced process continues execution. addr is an address specifying the place where execution is to be resumed (a new value for the program counter), or (caddr_t)1 to indicate that execution is to pick up where it left off. data provides a signal number to be delivered to the traced process as it resumes execution, or 0 if no signal is to be sent.
 
PT_KILL (8) The traced process terminates, as if PT_CONTINUE had been used with SIGKILL given as the signal to be delivered.
 
PT_ATTACH (9) This request allows a process to gain control of an otherwise unrelated process and begin tracing it. It does not need any cooperation from the to-be-traced process. In this case, pid specifies the process ID of the to-be-traced process, and the other two arguments are ignored. This request requires that the target process must have the same real UID as the tracing process, and that it must not be executing a setuid or setgid executable. (If the tracing process is running as root, these restrictions do not apply.) The tracing process will see the newly-traced process stop and may then control it as if it had been traced all along.
 
Two other restrictions apply to all tracing processes, even those running as root. First, no process may trace the process running init(8). Second, if a process has its root directory set with chroot(2), it may not trace another process unless that process' root directory is at or below the tracing process' root.
 
PT_DETACH (10) This request is like PT_CONTINUE, except that it does not allow specifying an alternative place to continue execution, and after it succeeds, the traced process is no longer traced and continues execution normally.
 
PT_SYSCALL (11) Continue and stop at next return from syscall.
 

Additionally, machine-specific requests can exist. On the SPARC, these are:
 
PT_GETREGS This request reads the traced process' machine registers into the struct reg (defined in <machine/reg.h>) pointed to by addr.
 
PT_SETREGS This request is the converse of PT_GETREGS; it loads the traced process' machine registers from the struct reg (defined in <machine/reg.h>) pointed to by addr.
 
PT_GETFPREGS This request reads the traced process' floating-point registers into the struct fpreg (defined in <machine/reg.h>) pointed to by addr.
 
PT_SETFPREGS This request is the converse of PT_GETFPREGS; it loads the traced process' floating-point registers from the struct fpreg (defined in <machine/reg.h>) pointed to by addr.
 
Return alue: Some requests can cause ptrace to return -1 as a non-error value; to disambiguate, errno can be set to 0 before the call and checked afterwards. The possible errors are:
 
ww No process having the specified process ID exists.
 
EINVAL
 
  • A process attempted to use PT_ATTACH on itself.
  • The request was not one of the legal requests.
  • The signal number (in data) to PT_CONTINUE was neither 0 nor a legal signal number.
  • PT_GETREGS, PT_SETREGS, PT_GETFPREGS, or PT_SETFPREGS was attempted on a process with no valid register set. (This is normally true only of system processes.)
EBUSY
 
  • PT_ATTACH was attempted on a process that was already being traced.
  • A request attempted to manipulate a process that was being traced by some process other than the one making the request.
  • A request (other than PT_ATTACH) specified a process that wasn't stopped.
EPERM
 
  • A request (other than PT_ATTACH) attempted to manipulate a process that wasn't being traced at all.
  • An attempt was made to use PT_ATTACH on a process in violation of the requirements listed under PT_ATTACH above.
Availability: This function is available as of FreeMiNT 1.15.11.
 
Group: Process functions
 
See also: Binding
 

5.11.44.1 Bindings for Ptrace

C: int16_t Ptrace(int16_t request, int16_t pid, void *addr, int32_t data);
 
Assembler:
 
move.l    data,-(sp)    ; Offset 10
pea       addr          ; Offset 6
move.w    pid,-(sp)     ; Offset 4
move.w    request,-(sp) ; Offset 2
move.w    #320,-(sp)    ; Offset 0
trap      #1            ; GEMDOS
lea       14(sp),sp     ; Correct stack

5.11.45 Pumask

Name: »Pumask« - Set initial creation mask for files and directories.
 
Opcode: 307
 
Syntax: int16_t Pumask ( int16_t mode );
 
Description: The function Pumask alters the file/directory creation mask of the current process to mode, which is a WORD bitmask of various access permission flags as defined in Fchmod. The new value of the mask is inherited by child processes.
 
When a new file or a new directory is created (with Fcreate or Dcreate respectively), the access rights are normally set so that full access is permitted. (Exception: New files are normally not executable.)
 
With the aid of Pumask one can specify which access rights during creation of a file are not (!) to be permitted.
 
Explicit Fchmod calls are not affected by Pumask.
 
Warning: In MagiC however the mask is not evaluated by any internal XFS of MagiC, and finds use exclusively in UNIX-like file-systems.
 
Return value: The function returns the value of the old creation mask.
 
Availability: Available when a 'MiNT' cookie with a version of at least 0.92 exists, and MagiC as of Version 5.04.
 
Group: Process functions
 
See also: Binding   Dcreate   Fchmod   Fcreate
 

5.11.45.1 Bindings for Pumask

C: int16_t Pumask ( int16_t mode );
 
Assembler:
 
move.w    mode,-(sp)   ; Offset 2
move.w    #307,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.11.46 Pusrval

Name: »Pusrval« - Set/interrogate specific process information.
 
Opcode: 280
 
Syntax: int32_t Pusrval ( int32_t val );
 
Description: The function Pusrval permits the setting or interrogation of process-specific information. These are stored in a LONGword, and inherited by all child processes.
 
The meaning of the value can be freely determined by the calling program.
 
Return value: The function returns the old value.
 
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and MagiC as of Version 5.04.
 
Group: Process functions
 
See also: Binding
 

5.11.46.1 Bindings for Pusrval

C: int32_t Pusrval ( int32_t val );
 
Assembler:
 
move.l    val,-(sp)    ; Offset 2
move.w    #280,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.11.47 Pvfork

Name: »Pvfork« - Create copy of the current process.
 
Opcode: 275
 
Syntax: int16_t Pvfork ( void );
 
Description: The function Pvfork creates a copy of the current process. Parent and child process share the same address and data space, i.e. every change that the child makes to variables will also affect the parent. The new process starts its work when the function Pvfork returns.
 
Note that if the parent is in supervisor-mode when the call is made, the child is placed in user-mode anyway.
 
As both processes share the same address space (and stack), problems would arise if both ran at the same time. For this reason the parent is paused until the child process is either terminated or uses Pexec (mode 200) to write itself as a new process to a new address space.
 
Return value: The function can return the following results:
 
E_OK  : In child process
>0    : New process ID in parent process
ENSMEM: Not enough memory available to create a new process
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
 
Group: Process functions
 
See also: Binding   Pexec   Pfork   Threads
 

5.11.47.1 Bindings for Pvfork

C: int16_t Pvfork ( void );
 
Assembler:
 
move.w    #275,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.48 Pwait

Name: »Pwait« - Try to obtain exit code of waiting or terminated child process.
 
Opcode: 265
 
Syntax: int32_t Pwait ( void );
 
Description: The function Pwait is equivalent to Pwait3 (2, NULL) and is offered for reasons of backwards compatibility.
 
According to POSIX, the library function 'wait' should be implemented as Pwaitpid (-1, 0, NULL). Hence Pwait should not be used for a POSIX-compatible library.
 
Warning: In MagiC the function is implemented as Pwaitpid (-1, 2, NULL).
 
Return value: The function can return the following results:
 
>0    : Exit status and PID of the child in the lower and upper 16 bits respectively of a 32-bit return code
 0    : No child processes have terminated.
EFILNF: No child processes exist
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and MagiC as of Version 5.04.
 
Group: Process functions
 
See also: Binding   Pwait3   Pwaitpid
 

5.11.48.1 Bindings for Pwait

C: int32_t Pwait ( void );
 
Assembler:
 
move.w    #265,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.11.49 Pwait3

Name: »Pwait3« - Get exit code of any waiting or terminated children of the calling process.
 
Opcode: 284
 
Syntax: int32_t Pwait3 ( int16_t flag, int32_t *rusage );
 
Description: The function Pwait3 is equivalent to a call of Pwaitpid (-1, flag, rusage) and determines with it the exit code as well as the CPU load of a terminated or stopped child process.
 
flag is a bit-mask showing the specifics of this call as follows:
 
Value Meaning
   
1 If set, the function will not block the calling process if no child has been stopped or terminated, but will just return 0; if not set (clear), the process will be blocked until a child of the process has been terminated or stopped
2 If set, returns exit codes for processes that have been terminated as well as stopped; if clear, only returns exit codes for processes that have actually terminated

rusage points to an array of two LONGs that are filled in with information about resource usage of the stopped or terminated process. The first LONG holds the number of milliseconds used by the child in user space; the second LONG shows the number of milliseconds spent by the process in kernel space. If this information is not required, rusage may be set to NULL.
 
Return value: The function can return the following results:
 
>0    : Exit status and PID of the child in the lower and upper 16 bits respectively of a 32-bit return code
 0    : No child processes have been stopped and/or terminated, or, if bit 0 of the parameter flag is set, the function would be blocked when waiting for the exit or the stopping of the child process
EFILNF: No child processes exist
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and MagiC as of Version 5.04.
 
Group: Process functions
 
See also: Binding   Pwait   Pwaitpid
 

5.11.49.1 Bindings for Pwait3

C: int32_t Pwait3 ( int16_t flag, int32_t *rusage );
 
Assembler:
 
pea       rusage       ; Offset 4
move.w    flag,-(sp)   ; Offset 2
move.w    #284,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.11.50 Pwaitpid

Name: »Pwaitpid« - Get exit code information about one or more child processes.
 
Opcode: 314
 
Syntax: int32_t Pwaitpid ( int16_t pid, int16_t flag, int32_t *rusage );
 
Description: The function Pwaitpid tries to obtain the exit code of child processes that have been stopped or terminated. If bit 1 of the parameter flag is set, then the child processes currently stopped will be reported; if clear, child processes newly terminated or stopped by tracing will be reported.
 
A stopped process will be reported once, as a rule, (as long as it has not been restarted and stopped again). Equally, a terminated process will be reported only once.
 
If child processes are present that have neither been stopped nor terminated (or are waiting for such an event), then the further behaviour of the function is determined by bit 0 of the parameter flag. The following applies here:
 
Bit-0 = 0: Wait until child is stopped or terminated
Bit-0 = 1: Return immediately

With the parameter pid the children whose exit codes are of interest can be specified more exactly:
 
pid Meaning
   
-1 Inquire status for all children
>0 pid is the process ID of the child whose status is to be established
=0 Inquire status for all children whose group ID is the same as that of the calling process
< -1 Inquire status for all children whose group ID corresponds to the absolute value of pid

With the parameter rusage information about the usage of CPU time of the child is accounted for:
 
rusage[0]: Time spent in user space (msec)
rusage[1]: Time spent in kernel space (msec)

If a child process was found, its PID will be given in the upper 16 bits and its exit status in the lower 16 bits of the return value. If the process was stopped or terminated by a signal with the number n, its exit status will be 256*n+x, where:
 
x = 127, if the process was stopped
x = 0, If the process was terminated

Warning: In MagiC, stopped child-processes are not yet recognized, but only terminated child processes. In addition, only NULL-values are returned at present in the parameter rusage.
 
Process groups, too, are not properly supported at present because the function Psetpgrp is missing.
 
Return value: The function can return the following values:
 
>0    : Exit status and PID of the child in the lower and upper 16 bits respectively of a 32-bit return code
 0    : No child processes have been stopped and/or terminated, or, if bit 0 of the parameter flag is set, the function would be blocked when waiting for the exit or the stopping of the child process
EFILNF: No child processes exist
Availability: Available when a 'MiNT' cookie with a version of at least 0.96 exists, and MagiC as of Version 5.04.
 
Group: Process functions
 
See also: Binding   Pwait   Pwait3
 

5.11.50.1 Bindings for Pwaitpid

C: int32_t Pwaitpid ( int16_t pid, int16_t flag, int32_t *rusage );
 
Assembler:
 
pea       rusage       ; Offset 6
move.w    flag,-(sp)   ; Offset 4
move.w    pid,-(sp)    ; Offset 2
move.w    #314,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $A(sp),sp    ; Correct stack

Home GEMDOSGEMDOS Date and TimeDate and Time Memory managementMemory management