GEMini Atari

home *** CD-ROM | disk | FTP | other *** search

/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / mint / mint095b / signal.doc < prev next >

Wrap

Text File | 1993-08-03 | 20.4 KB | 472 lines

An Introduction to Signals Under MiNT MiNT introduces the new (to TOS) concept of a signal. If you're familiar with Unix/Posix signals, then MiNT signals will will be easy to learn; but note that there are some (not so subtle) differences between MiNT and Unix! What is a Signal? A signal is a small non-negative integer that represents an exceptional event; something that is very urgent. It's somewhat like an interrupt or exception to the CPU, only it's implemented in the operating system instead of in the hardware. Like many exceptions (bus errors, etc.) signals are usually fatal. Most signals can be caught by programs (so that a program-defined routine is called) or ignored; if a signal is caught or ignored, it is no longer fatal. Signals can also be blocked; a blocked signal is not acted upon until it is unblocked. A signal is said to be sent to a process when the exceptional condition related to that signal occurs, or when another process sends the signal with the Pkill system call. The signal is said to be delivered to the process when that process wakes up and begins to take whatever actions are appropriate for the signal. Note that there may be a considerable time interval between the sending of a signal and its delivery. For example, if process A has blocked the SIGHUP signal (signal 1), then no SIGHUP will be delivered to it until it has unblocked that signal, even if process B sends it SIGHUP with the Pkill system call. Note also that a signal is not necessarily delivered the same number of times that it is sent. If both process B and process C send SIGHUP to process A, when process A unblocks SIGHUP only one SIGHUP will be delivered. This is because signals are like flags; once a flag has been set (the signal is sent) setting the flag again will have no effect until it has been cleared (the signal is delivered). What Signals Are There? There are 32 possible signals, 0-31. Not all of these have been assigned a meaning under MiNT. Here are the ones that have been given a meaning; we give the symbolic name for the signal, the corresponding integer, and the "traditional" meaning for the process that the signal is sent to. Any signal not listed here should be considered as "reserved" and should not be used by applications. Unless otherwise noted, the default action for signals is to terminate the process. #define SIGNULL 0 [no default action, signal is never delivered] This isn't really a signal at all; it is never delivered to processes and has no effect. It exists only so that processes can test to see if a particular child process has exited, by attempting to send SIGNULL to the child. If the child exists, the attempt will succeed but nothing will be done. If the child has terminated, the caller will get an error. It is not possible to catch or block this signal, since it is never sent to processes anyway. #define SIGHUP 1 "The terminal that you're connected to is no longer valid." This signal is commonly sent by, for example, window managers when the user has closed the window. Processes should not attempt any I/O to their controlling terminal after receiving this signal, and indeed should probably exit unless the user has specifically asked them to continue. #define SIGINT 2 "Please stop what you're doing." This signal is sent when the user presses control-C. It usually means that the process should exit; interactive processes may wish to catch SIGINT so that the user can use it to break out of time-consuming tasks. #define SIGQUIT 3 "Stop what you're doing, something's gone wrong!" This signal is sent when the user presses control-\. It usually indicates a desire to immediately abort the process because of an error that the user has noticed. It is generally thought to be "stronger" than SIGINT, and exiting (perhaps after cleaning up data structures) is an appropriate response to this. #define SIGILL 4 "An illegal instruction has been encountered." This corresponds to the 680x0 illegal instruction trap, and usually indicates a very serious error; catching this signal is generally unwise. #define SIGTRAP 5 "The single-step trace trap has been encountered." This corresponds to the 680x0 trace trap, and is usually activated (and handled) by debuggers; user programs shouldn't catch this. #define SIGABRT 6 "An awful error has occured." This is commonly sent by the abort library function, and indicates that something has gone very, very wrong (for example, data structures have been unexpectedly corrupted). It is unlikely that anything useful can be done after this signal is sent; programs should not normally catch or ignore SIGABRT. #define SIGPRIV 7 "Privilege violation." An attempt has been made to execute an instruction in user mode that is normally restricted to supervisor mode; this corresponds to the 680x0 privilege violation exception, and indicates a serious error. #define SIGFPE 8 "Division by zero or a floating point error has occured." Processes may ignore or catch this signal (which corresponds to the 680x0 division by zero trap) and deal with it as they see fit. #define SIGKILL 9 [cannot be blocked or caught] "Die!" This signal will never be seen by a process; nor can processes block it. Sending SIGKILL is a way to be sure of killing a run-away process. Use it only as a last resort, since it gives the process no chance to clean up and exit gracefully. #define SIGBUS 10 "Bus error." Corresponds to the 680x0 bus error exception, and indicates a very serious error; programs should generally not attempt to ignore or catch this signal. #define SIGSEGV 11 "Illegal memory reference." Corresponds to the 680x0 address error exception, and indicates a very serious error; catching or ignoring this signal is not recommended. #define SIGSYS 12 "Bad argument to a system call." This signal is sent when an illegal (usually, out of range) parameter is sent to a system call, and when that system call does not have any "nice" way to report errors. For example, Super(0L) when the system is already in supervisor mode causes SIGSYS to be raised. Note that the kernel does not always detect illegal/out of range arguments to system calls, only sometimes. #define SIGPIPE 13 "A pipe you were writing to has no readers." Programs may catch this signal and attempt to exit gracefully after receiving it; note that exiting is appropriate because the standard output is probably no longer connected to anything. #define SIGALRM 14 "The alarm you set earlier has happened." This signal is sent to processes when the alarm clock set by Talarm (q.v.) expires. It's very common to catch this signal and from the signal handler jump to a known point in the program; for example, to indicate a timeout while attempting to communicate over a serial line. #define SIGTERM 15 "Please die." This is a polite form of SIGKILL (#9). Programs should respect this nice request; they may want to catch the signal to perform some cleanup actions, but they should then exit (since if they don't, the user will probably get mad and send SIGKILL later anyway...). This is the signal that is sent when a process is dragged to the trashcan on the desktop. #define SIGSTOP 17 [default action: suspend the process] "Suspend yourself." This signal is sent to a process when it should be stopped temporarily. SIGSTOP is used primarily by debuggers and similar programs; suspensions requested directly by the user usually are signalled by SIGTSTP (q.v.) This signal cannot be ignored, blocked, or caught. #define SIGTSTP 18 [default action: suspend the process] "The user is asking you to suspend yourself." This signal is sent immediately when the user presses the control-Z key, and is sent when the process tries to read a control-Y key in cooked mode (for a delayed stop). In both cases, the process should suspend itself. Since this is the default action, no special handling is normally required, although some programs may wish to save the screen state and restore it when they are unsuspended. #define SIGCONT 19 [default action: continue a stopped process] "You are being restarted after having been suspended." This signal is sent by shells to resume a suspended process. If the process is not suspended, the signal does nothing. This signal cannot be blocked, but it *is* possible to install a handler for it (this is rarely necessary, though). #define SIGCHLD 20 [default action: no action taken] "One of your children has been suspended or has exited." This signal is sent by the kernel to the parent of any process that is terminated (either because of a signal or by a Pterm, Pterm0, or Ptermres system call) or which is suspended because of a signal. Programs that are concerned with the status of their children (for example, shells) may wish to catch this signal; after a SIGCHLD has been received, the Pwait3 system call may be used to determine exactly which child has exited or been suspended. Note that the Psigaction system call may be used to force SIGCHLD to be delivered only when a child process terminates (so that suspension of child processes, for example via job control, does not raise SIGCHLD. #define SIGTTIN 21 [default action: suspended the process] "Attempt to read from a terminal you don't own." This signal is sent to any process that attempts to do input from a terminal with a different process group than their own. Usually, this happens if the user has started the job in the background; the process will be suspended until the user explicitly brings it to the foreground with the appropriate shell command (at which time the shell will reset the terminal's process group and send the stopped process a SIGCONT signal to tell it to continue). [NOTE: in fact, SIGTTIN and SIGTTOU are sent to all processes in the same process group as the process that attempted to do the i/o; this is for compatibility with Unix, and it simplifies the implementation of job control shells.] #define SIGTTOU 22 [default action: suspend the process] "Attempt to write to a terminal that you don't own." Similar to SIGTTIN (q.v.). Processes should normally respect the user's job control and should override or ignore SIGTTOU only in situations where a very critical error has occured and a message must be printed immediately. #define SIGXCPU 24 "Your CPU time limit has been exhausted." Sent to processes when they have consumed more than the maximum number of milliseconds of CPU time allowed by the Psetlimit() system call. The signal will continue to be sent to the process until it exits; if a process does catch this signal, it should do whatever clean up actions are necessary and then terminate. #define SIGWINCH 28 [default action: no action taken] "The window you were running in has changed size." This signal is sent to processes by some window managers to indicate that the user has changed the size of the window the process is running in. If the process cares about the window size, it may catch this signal and use an Fcntl call to inquire about the new window size when the signal is received. (See the documentation for Fcntl for details.) #define SIGUSR1 29 #define SIGUSR2 30 These two signals are reserved for applications, which may define whatever meaning they wish for them. Note, however, that these signals do terminate processes by default, so don't send them to a process which isn't prepared to deal with them. System Calls Dealing With Signals WORD Pkill( WORD pid, WORD sig ) If pid > 0, then the given signal (see the numbers above) is sent to the process with that pid. If pid == 0, then the given signal is sent to all members of the process group of the process making the Pkill call. This includes, of course, the process itself. If pid < 0, the signal is sent to all members of process group (-pid). Returns: 0 for successful sending of the signal (Note that if the current process is a recipient of the signal, and the signal proves to be fatal, then Pkill will never return.) ERANGE if "sig" is less than 0 or greater than 31 EFILNF if pid > 0 and the indicated process has terminated or does not exist, or if pid < 0 and there are no processes in the given process group EACCDN if the sending process is not authorized to send signals to the specified receiving process or group (for example, they belong to different users) #define SIG_DFL (0L) #define SIG_IGN (1L) LONG Psignal( WORD sig, LONG handler ) Change the handling of the indicated signal. If "handler" is SIG_DFL, then the default action for the signal will occur when the signal is delivered to the current process. If "handler" is SIG_IGN, then the signal will be ignored by the process, and delivery of the signal will have no noticeable effect (in particular, the signal will not interrupt the Pause system call, q.v.). If the signal is pending at the time of the Psignal call, it is discarded. If "handler" is any other value, it is assumed to be the address of a user function that will be called when the signal is delivered to the process. The user function is called with a single LONG argument on the stack, which is the number of the signal being delivered (this is done so that processes may use the same handler for a number of different signals). While the signal is being handled, it is blocked from delivery; thus, signal handling is "reliable" (unlike Version 7 and early System V Unix implementations, in which delivery of a second signal while it was being handled could kill the process). Also note that, unlike some versions of Unix, the signal handling is *not* reset to the default action before the handler is called; it remains set to the given signal handler. The signal handler must either return (via a normal 680x0 rts instruction) or call the Psigreturn system call to indicate when signal handling is complete; in both cases, the signal will be unblocked. Psigreturn also performs some internal clean-up of the kernel stack that is necessary if the signal handler is not planning to return (for example, if the C longjmp() function is to be used to continue execution at another point in the program). Signal handlers may make any GEMDOS, BIOS, or XBIOS system calls freely. GEM AES and VDI calls should not be made in a signal handler. Note that calling Psignal to change behavior of a signal has the side effect of unmasking that signal, so that delivery is possible. This is done so that processes may, while handling a signal, reset the behavior and send themselves another instance of the signal, for example in order to suspend themselves while handling a job control signal. Signal handling is preserved across Pfork and Pvfork calls. Signals that are ignored by the parent are also ignored by the child after a Pexec call; signals that were being caught for handling in a function are reset in the child to the default behavior. Returns: The old value of handler on success. ERANGE if sig < 1 or sig > 31 EACCDN if sig cannot be caught by the user (i.e. SIGKILL or SIGSTOP) Bugs: Signal handling can be nested only a small (around 3) number of times, i.e. if 4 signals are delivered to a process, and the process has established handlers for all 4, and none of the handlers has returned or called Psigreturn, then there is a very good chance of a stack overflow killing the process off. In practice, this is unlikely to happen. LONG Psigblock( LONG amask ) Block receipt of some signals. The "amask" argument is added to the current set of signals being masked, i.e. the new set of blocked signals is the union of the old set and the set represented by amask. Sets of blocked signals are represented by a 32 bit unsigned long quantity, with bit (1L << sig) set if signal "sig" is to be blocked, and clear if not. Blocked signals remain blocked across Pfork and Pvfork calls. For Pexec calls, children always start out with an empty set of blocked signals, regardless of which signals are blocked in the parent. Returns: The old set of blocked signals (i.e. the set as it was before amask was added to it). NOTE: Certain signals (SIGKILL, SIGSTOP, SIGCONT) cannot be blocked; if the corresponding bits are set in amask, the kernel will clear them but will not report an error. LONG Psigsetmask( LONG mask ) Decide which signals are to be blocked from delivery. Unlike Psigblock (which adds to the set of blocked signals) Psigsetmask changes the entire set, replacing the old set of blocked signals with the one specified in "mask". As with Psigblock, signal n is blocked from delivery if bit (1L << n) is set in mask. Note that certain signals cannot be blocked, and if the corresponding bits are set in the mask the kernel will clear them. Returns: The old set of blocked signals. Usage: Typically, Psigblock and Psigsetmask are used together to temporarily block signals, e.g.: oldmask = Psigblock( (1L << SIGINT) ); ... do some things with SIGINT blocked from delivery ... (void) Psigsetmask(oldmask); LONG Psigpending() Give an indication of what signals are pending (i.e. have been sent to the process but not yet delivered, probably because they are blocked from delivery). Returns: A 32 bit unsigned long representing the set of signals that are pending. Signal n is pending if bit (1L << n) is set in the returned value. void Psigreturn() Terminate signal handling. This call should be used by any signal handler that is not planning to return to the kernel (i.e. if the handler is going to execute a non-local jump to another point in the program). It cleans up the signal delivery stack and unblocks the signal that was being delivered. Calling Psigreturn when no signal is being delivered is harmless. Bugs: Calling Psigreturn from a signal handler, and then actually returning from that handler, is likely to produce extremely unpleasant results. Don't do it. void Pause() Wait until a signal is delivered. This call will return after any (non-fatal) signal has been delivered to the process. Note that signals that are being ignored are never delivered. void Psigpause( LONG mask ) Block the set of signals specified by "mask", and then wait until a signal is delivered. This call will return after any (non-fatal) signal has been delivered to the process. Before returning, the signal mask is restored to its original value. struct sigaction { LONG sa_handler; LONG sa_mask; WORD sa_flags; #define SA_NOCLDSTOP 1; } WORD Psigaction( WORD sig, struct sigaction *act, struct sigaction *act ) Like Psignal, this call changes the handling of the indicated signal. If "act" is non-zero, it is a pointer to a structure which describes the new signal handling behavior, as follows: sa_handler is the function to be called when the signal is delivered, or SIG_DFL, or SIG_IGN. For further information about signal handling functions, see Psignal. sa_mask is a set of additional signals to mask while the signal is being delivered. The signal itself is always masked, but sometimes it might be desireable to mask some other signals as well; this allows a "prioritization" of signals sa_flags extra flags which can affect the behavior of the signal. This field should normally be set to 0. If "sig" is SIGCHLD and "flags" is SA_NOCLDSTOP, then the SIGCHLD signal will not be delivered to this process when one of its children are stopped. If "oact" is non-zero, then the old signal handling behavior is copied into "oact" and returned. Returns: 0 on success ERANGE if sig < 1 or sig > 31 EACCDN if sig cannot be caught by the user Usage: If "sig" is a valid signal, the call: foo = Psignal(sig, newfunc) is equivalent to: struct sigaction newact, oact; newact->sa_mask=0L; newact->sa_flags=0; newact->sa_handler = newfunc; Psigaction(sig, &newact, &oact); foo = oact->sa_handler; LONG Talarm( LONG s ) If s > 0, schedule a SIGALRM signal to occur in s seconds. This alarm will replace any previously scheduled alarm. If s = 0, cancel any previously scheduled alarm. If s < 0, inquire about a scheduled alarm but do not change it. Returns: If an alarm was previously scheduled, returns the number of seconds remaining until that previously scheduled alarm. Otherwise, returns 0. Bugs: Internal calculations are done in milliseconds, not seconds, so the returned value is not exactly accurate. For the same reason, setting an alarm more than 2 million seconds or so into the future will not work correctly.