GEMDOS
Date and Time
Memory management
| • 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
| 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
|
| C: | void Pause ( void );
|
| Assembler: |
move.w #289,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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:
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
|
| 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 |
| 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:
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
|
| 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)
|
| 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:
| ||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||||
| Group: | Process functions
| ||||||
| See also: | Binding Pexec Pvfork Threads
|
| C: | int16_t Pfork ( void );
|
| Assembler: |
move.w #283,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | int16_t Pgetauid ( void );
|
| Assembler: |
move.w #325,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | int32_t Pgetegid ( void );
|
| Assembler: |
move.w #313,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | int32_t Pgeteuid ( void );
|
| Assembler: |
move.w #312,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | int16_t Pgetgid ( void );
|
| Assembler: |
move.w #276,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| 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 |
| 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
|
| C: | int16_t Pgetpgrp ( void );
|
| Assembler: |
move.w #269,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | int16_t Pgetpid ( void );
|
| Assembler: |
move.w #267,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | int16_t Pgetppid ( void );
|
| Assembler: |
move.w #268,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| 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 |
| 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
|
| C: | int16_t Pgetuid ( void );
|
| Assembler: |
move.w #271,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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:
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:
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
|
| 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 |
| 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:
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:
| ||||||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists.
| ||||||||||||
| Group: | Process functions
| ||||||||||||
| See also: | Binding
|
| 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 |
| 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
|
| 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 |
| 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:
| ||||
| 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
|
| 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 |
| 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:
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
|
| 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 |
| 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:
Other values for timeout specify the delay time in milliseconds before a timeout occurs. The following values are possible for the parameter mode:
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:
| ||||||||||||||||
| 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
|
| 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 |
| 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
|
| 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 |
| 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
|
| 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 |
| 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
|
| 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 |
| 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:
| ||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||
| Group: | Process functions
| ||||
| See also: | Binding Psetuid
|
| 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 |
| 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
|
| 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 |
| 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:
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
|
| 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 |
| 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:
| ||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||||
| Group: | Process functions
| ||||||
| See also: | Binding Pkill Pgetpgrp Pgetpid
|
| 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 |
| 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
|
| 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 |
| 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
|
| 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 |
| 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
|
| 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 |
| 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:
| ||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||
| Group: | Process functions
| ||||
| See also: | Binding Psetgid
|
| 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 |
| 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:
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:
| ||||||||
| 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
|
| 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 |
| 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
|
| 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 |
| 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:
| ||||||||
| 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
|
| 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 |
| 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:
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.
In case of error, the following results are returned:
| ||||||||
| 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
|
| 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 |
| 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
|
| 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 |
| 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
|
| C: | int32_t Psigpending ( void );
|
| Assembler: |
move.w #291,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| C: | void Psigreturn ( void );
int32_t Psigreturn ( void ); |
| Assembler: |
move.w #282,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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
|
| 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 |
| 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
CTL_HW (2): Generic CPU/IO
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).
CTL_KBD (6): Keyboard configuration
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return value: | The function can return the following results:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Availability: | This function is available as of FreeMiNT 1.15.12.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Group: | Process functions
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See also: | Binding Sysconf
|
| 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 |
| 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:
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
|
| 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 |
| 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
|
| C: | void Pterm0 ( void );
|
| Assembler: |
move.w #0,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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:
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
|
| 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 |
| 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:
Additionally, machine-specific requests can exist. On the SPARC, these are:
| ||||||||||||||||||||||||
| 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:
| ||||||||||||||||||||||||
| Availability: | This function is available as of FreeMiNT 1.15.11.
| ||||||||||||||||||||||||
| Group: | Process functions
| ||||||||||||||||||||||||
| See also: | Binding
|
| 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 |
| 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
|
| 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 |
| 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
|
| 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 |
| 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:
| ||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||||
| Group: | Process functions
| ||||||
| See also: | Binding Pexec Pfork Threads
|
| C: | int16_t Pvfork ( void );
|
| Assembler: |
move.w #275,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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:
| ||||||
| 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
|
| C: | int32_t Pwait ( void );
|
| Assembler: |
move.w #265,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| 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:
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:
| ||||||||
| 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
|
| 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 |
| 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:
With the parameter pid the children whose exit codes are of interest can be specified more exactly:
With the parameter rusage information about the usage of CPU time of the child is accounted for:
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:
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:
| ||||||||||||||||||||||||
| 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
|
| 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 |
GEMDOS
Date and Time
Memory management