GEMDOS

Program launch and TPA

gemdos-trap

5.7 Signals

The "signal" concept, originating from the U*NIX world, is also available in the operating systems MultiTOS (actually the underlying MiNT) and MagiC (as of Version 4.50). Signals can be thought of as natural number messages that represent a given exception condition. They are comparable to an interrupt or a CPU exception, but with the difference that they deal with a pure software implementation.

Each process possesses:

• A bit-vector of the pending signal. This describes those signals that are still waiting to be processed, perhaps because they are currently blocked by the signal mask, or because the process is in a state where it cannot process signals.
   

• A signal mask. This 32-bit value defines those signals that are currently blocked as a bit-vector; if, say, bit 30 is set in this vector, then the signal SIGUSR2 is blocked. The signal mask is not just impacted explicitly (i.e. by system calls) but also implicitly by other processes. During the processing of a signal, for instance, it is blocked, yet others may occur. After the signal has been processed it is released again and any signals waiting can then be processed. One should note that some signals (e.g. SIGKILL, SIGSTOP, SIGCONT) can not be masked.
   

• A table in the form struct sigaction.
   

At a Pexec the signal mask and the pending value (see above) of the child process will be zeroed. The element sa_handler of the sigaction structure is inherited, during which a non-0 or 1 value is always set to 0. The elements sa_mask and sa_flags of the structure are zeroed.

Most signals can be caught by a program (perhaps to call up a given routine on receipt), ignored, or also blocked. Blocked signals will be ignored until the blockade is lifted again. Re terminology: One says that a signal is sent to a process when the exception that is represented by the signal occurs, or the signal is sent by another process via Pkill. On the other hand a signal is caught by a process when the corresponding process awakes and starts the actions matching the signal. One should note that the signal handling takes up time: Between sending a signal and the execution of the matching action a considerable period of time may pass.

In total there are 31 possible signals (0 to 30) available, not all of which however have been assigned a fixed meaning. The following list describes (as far as known) all possible signals in the form: Signal number, Name of the signal, Meaning of the signal for the receiving process. Unless explicitly noted otherwise, the default action on the receipt of a signal is the killing (termination) of the receiving process.

See also:
Signal-handler in MagiC   Process functions   Sample code   Psigaction   Psignal   Pkill   Test for pipes

5.7.1 Signal-handler in MagiC

As MagiC's signal-handlers differ somewhat from those in MiNT or in MultiTOS, we will deal here with the most important differences and features. First of all it must be realised that in MagiC, AES and VDI calls from within a signal-handler are permitted (quite in contrast to MiNT).

A signal-handler runs in user-mode and employs the user stack of the main thread, while this sleeps. In MiNT the supervisor stack of the process is used. Hence, according to the MiNT documentation, the nesting of signals more than 4 deep makes a process crash due to stack overflow. In MagiC each signal-handler is its own thread with its own supervisor stack, so that the worst that can happen is the extremely rare case of user stack overflow. However, if too little memory is available for a new thread when handling a signal, then an "Out of internal memory" alert will appear, and one should terminate a program as soon as possible. MagiC requires about 7 kb of memory for handling each signal.

In MagiC, the same applies for signals as for threads (a signal-handler is a thread), i.e. the corresponding system libraries have to be reentrant. However, there is a complication because the main thread is halted while processing the signal. So if the main thread has set a signal (wind_update for example), a deadlock occurs if the signal-handler also wants to set these signals. Furthermore, in MagiC a process may be interrupted at almost any point (MagiC is reentrant, even DOS is interruptible), so that the main thread may in some cases block important areas of the system (files, directories, semaphores). Due to this it is possible that certain files cannot be deleted or opened, for instance.

With normal termination of a signal-handler all semaphores blocked by the handler are released automatically. Furthermore, windows, screen background and menu bar of the signal-handler will be released if appropriate. Note that a signal-handler has its own AES message-queue, i.e. evnt_message and appl_write should be used with care.

On Psigreturn the semaphores of all signal-handlers as well as those of the main thread will be released. However the windows, screen background and menu bar of the signal-handler will not be released. Though this would not have been much of a problem, it may not be necessary in practice. Psigreturn restores the supervisor stack of the main thread, i.e. a setjmp/longjmp mechanism only needs to set the USP. This is not sufficiently documented in the MiNT documentation, and also works only if the main thread is waiting via a GEMDOS call. If AES comes into play, MultiTOS crashes! Hence Psigreturn should be avoided if possible. Psigreturn in MagiC is not of the type VOID as in MiNT, but of the type LONG. If the function is called from a non-signal-handler, Psigreturn returns the value EACCDN, otherwise E_OK. If Psigreturn has returned E_OK, then (as in MiNT) under no circumstances should the handling procedure be terminated in the normal way via rts, because the jump-back address on the user stack is invalid after execution of Psigreturn.

A problem exists in MagiC with the existing versions of VT52. A signal-handler cannot yet perform keyboard scans in VT52; the keys will not be received. This may alter in a later version, however.

See also: Process functions   Signals   Threads

5.7.2 Sample code for signals

The first program installs a signal-handler for the two signals SIGUSR1 and SIGUSR2. With that one can test the nesting of both signals, if both are sent consecutively. The program should run in VT52 or in MINIWIN. If one presses Ctrl-Alt-Esc during the "for()" delay loop, one can see that MagiC creates its own thread for each signal-handler. This has the advantage that under MagiC no events (mouse, timer, ...) will be lost while a signal is being processed.

------------------------------ snip --------------------------
#include <tos.h>
#include <stdio.h>

void cdecl handler(long signr)
{
    long i;

    printf("Handler: Signal %ld received.\n", signr);
    Cconws("Wait...");
    for (i = 0; i < 7000000L; i++)
        ;
    Cconws("...OK\r\n");
}

int main( void )
{
    long ret;

    printf("My ProcID is %d.\n", Pgetpid());
    ret = (long) Psignal(SIGUSR1, handler);
    printf("Psignal => %ld\n", ret);
    ret = (long) Psignal(SIGUSR2, handler);
    printf("Psignal => %ld\n", ret);
    Cconin();
    return(0);
}
------------------------------ snap --------------------------

The second program shows the treatment of the Psigreturn call. Under MiNT this program only works if one doesn't use any AES calls (evnt_keybd or evnt_multi), but uses, say, Cconin. This means that the following program works under MagiC but crashes under MultiTOS (MiNT 1.08+AES 4.1). The problem lies probably in the restoration of the supervisor stack (system stack pointer), where MultiTOS fails due to the non-homogenous concept AES<->MiNT.

------------------------------ snip ---------------------------
#include <tos.h>
#include <aes.h>
#include <setjmp.h>
#include <tosdefs.h>
#include <stdio.h>

jmp_buf env;

void cdecl handler(long signr)
{
    printf("Handler: Signal %ld received.\n", signr);
    Cconws("Perform Psigreturn()\r\n");
    Psigreturn();
    longjmp(env, 1);
}

int main( void )
{
    long ssp;

    appl_init();
    printf("My ProcID is %d.\n", Pgetpid());
    Psignal(SIGUSR1, handler);

    if  (setjmp(env))
        Cconws("Coming from longjmp.\r\n");
    else    Cconws("Coming from setjmp.\r\n");
    ssp = Super(0L);
    Super((void *) ssp);
    printf("ssp = 0%08lx\n", ssp);
    evnt_keybd();
    return(0);
}

See also: Signals   Process functions   GEMDOS

GEMDOS

Program launch and TPA

gemdos-trap