Return to sigaction.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/sigaction.2, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980, 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"    @(#)sigaction.2 6.1 (Berkeley) 7/1/90
        !            19: .\"
        !            20: .TH SIGACTION 2 "July 1, 1990"
        !            21: .UC 7
        !            22: .ie t .ds d \(dg
        !            23: .el .ds d \z'|+'
        !            24: .ie t .ds p \(dd
        !            25: .el .ds p \z'|='
        !            26: .ie t .ds b \(bu
        !            27: .el .ds b @
        !            28: .SH NAME
        !            29: sigaction \- software signal facilities
        !            30: .SH SYNOPSIS
        !            31: .nf
        !            32: .B #include <signal.h>
        !            33: .PP
        !            34: .B struct sigaction {
        !            35: .B     void    (*sa_handler)();
        !            36: .B     sigset_t        sa_mask;
        !            37: .B     int     sa_flags;
        !            38: .B };
        !            39: .PP
        !            40: .B sigaction(sig, act, oact)
        !            41: .B int sig;
        !            42: .B struct sigaction *act, *oact;
        !            43: .fi
        !            44: .SH DESCRIPTION
        !            45: The system defines a set of signals that may be delivered to a process.
        !            46: Signal delivery resembles the occurence of a hardware interrupt:
        !            47: the signal is blocked from further occurrence, the current process 
        !            48: context is saved, and a new one is built.  A process may specify a
        !            49: .I handler
        !            50: to which a signal is delivered, or specify that a signal is to be 
        !            51: .IR ignored .
        !            52: A process may also specify that a default action is to be taken
        !            53: by the system when a signal occurs.
        !            54: A signal may also be
        !            55: .IR blocked ,
        !            56: in which case its delivery is postponed until it is
        !            57: .IR unblocked .
        !            58: The action to be taken on delivery is determined at the time
        !            59: of delivery.
        !            60: Normally, signal handlers execute on the current stack
        !            61: of the process.  This may be changed, on a per-handler basis,
        !            62: so that signals are taken on a special
        !            63: .IR "signal stack" .
        !            64: .PP
        !            65: Signal routines execute with the signal that caused their
        !            66: invocation
        !            67: .IR blocked ,
        !            68: but other signals may yet occur.
        !            69: A global 
        !            70: .I "signal mask"
        !            71: defines the set of signals currently blocked from delivery
        !            72: to a process.  The signal mask for a process is initialized
        !            73: from that of its parent (normally empty).  It
        !            74: may be changed with a
        !            75: .IR sigprocmask (2)
        !            76: call, or when a signal is delivered to the process.
        !            77: .PP
        !            78: When a signal
        !            79: condition arises for a process, the signal is added to a set of
        !            80: signals pending for the process.
        !            81: If the signal is not currently
        !            82: .I blocked
        !            83: by the process then it is delivered to the process.
        !            84: Signals may be delivered any time a process enters the operating system
        !            85: (e.g., during a system call, page fault or trap, or clock interrupt).
        !            86: If multiple signals are ready to be delivered at the same time,
        !            87: any signals that could be caused by traps are delivered first.
        !            88: Additional signals may be processed at the same time, with each
        !            89: appearing to interrupt the handlers for the previous signals
        !            90: before their first instructions.
        !            91: The set of pending signals is returned by the
        !            92: .IR sigpending (2)
        !            93: function.
        !            94: When a caught signal
        !            95: is delivered, the current state of the process is saved,
        !            96: a new signal mask is calculated (as described below), 
        !            97: and the signal handler is invoked.  The call to the handler
        !            98: is arranged so that if the signal handling routine returns
        !            99: normally the process will resume execution in the context
        !           100: from before the signal's delivery.
        !           101: If the process wishes to resume in a different context, then it
        !           102: must arrange to restore the previous context itself.
        !           103: .PP
        !           104: When a signal is delivered to a process a new signal mask is
        !           105: installed for the duration of the process' signal handler
        !           106: (or until a
        !           107: .I sigprocmask
        !           108: call is made).
        !           109: This mask is formed by taking the union of the current signal mask set,
        !           110: the signal to be delivered, and 
        !           111: the signal mask associated with the handler to be invoked.
        !           112: .PP
        !           113: .I Sigaction
        !           114: assigns an action for a specific signal.
        !           115: If
        !           116: .I act
        !           117: is non-zero, it
        !           118: specifies an action (SIG_DFL, SIG_IGN, or a handler routine) and mask
        !           119: to be used when delivering the specified signal.
        !           120: If 
        !           121: .I oact
        !           122: is non-zero, the previous handling information for the signal
        !           123: is returned to the user.
        !           124: .PP
        !           125: Once a signal handler is installed, it remains installed
        !           126: until another
        !           127: .I sigaction
        !           128: call is made, or an 
        !           129: .IR execve (2)
        !           130: is performed.
        !           131: The default action for a signal may be reinstated by setting
        !           132: .I sa_handler
        !           133: to SIG_DFL.
        !           134: The default actions are termination, possibly with a core image;
        !           135: no action; stopping the process; or continuing the process.
        !           136: See the signal list below for each signal's default action.
        !           137: If
        !           138: .I sa_handler
        !           139: is SIG_IGN the signal is subsequently ignored,
        !           140: and pending instances of the signal are discarded.
        !           141: .PP
        !           142: Options may be specified by setting
        !           143: .IR sa_flags .
        !           144: If the SA_NOCLDSTOP bit is set when installing a catching function
        !           145: for the SIGCHLD signal,
        !           146: the SIGCHLD signal will be generated only when a child process exits,
        !           147: not when a child process stops.
        !           148: Further, if the SA_ONSTACK bit is set in
        !           149: .I sa_flags,
        !           150: the system will deliver the signal to the process on a
        !           151: .IR "signal stack" ,
        !           152: specified with
        !           153: .IR sigstack (2).
        !           154: .PP
        !           155: If a caught signal occurs during certain system calls,
        !           156: the call may be forced to terminate prematurely
        !           157: with an EINTR error return,
        !           158: or the call may be restarted.
        !           159: Restart of pending calls is requested
        !           160: by setting the SA_RESTART bit in
        !           161: .I sa_flags.
        !           162: The affected system calls include
        !           163: .IR read (2),
        !           164: .IR write (2),
        !           165: .IR sendto (2),
        !           166: .IR recvfrom (2),
        !           167: .IR sendmsg (2)
        !           168: and
        !           169: .IR recvmsg (2)
        !           170: on a communications channel or a slow device (such as a terminal,
        !           171: but not a regular file)
        !           172: and during a
        !           173: .IR wait (2)
        !           174: or
        !           175: .IR ioctl (2).
        !           176: However, calls that have already committed are not restarted,
        !           177: but instead return a partial success (for example, a short read count).
        !           178: .PP
        !           179: After a
        !           180: .IR fork (2)
        !           181: or
        !           182: .IR vfork (2)
        !           183: the child inherits
        !           184: all signals, the signal mask, the signal stack,
        !           185: and the restart/interrupt flags.
        !           186: .PP
        !           187: .IR  Execve (2)
        !           188: resets all
        !           189: caught signals to default action and
        !           190: resets all signals to be caught on the user stack.
        !           191: Ignored signals remain ignored;
        !           192: the signal mask remains the same;
        !           193: signals that restart pending system calls continue to do so.
        !           194: .PP
        !           195: The following is a list of all signals
        !           196: with names as in the include file
        !           197: .RI < signal.h >:
        !           198: .LP
        !           199: .nf
        !           200: .RS
        !           201: .ta \w'SIGVTALRM\0\0\0'u +\w'15*\*p\0\0'u
        !           202: SIGHUP 1       hangup
        !           203: SIGINT 2       interrupt
        !           204: SIGQUIT        3*      quit
        !           205: SIGILL 4*      illegal instruction
        !           206: SIGTRAP        5*\*p   trace trap
        !           207: SIGABRT        6*      \fIabort\fP() call (formerly SIGIOT)
        !           208: SIGEMT 7*\*p   EMT instruction
        !           209: SIGFPE 8*      floating point exception
        !           210: SIGKILL        9       kill (cannot be caught, blocked, or ignored)
        !           211: SIGBUS 10*\*p  bus error
        !           212: SIGSEGV        11*     segmentation violation
        !           213: SIGSYS 12*\*p  bad argument to system call
        !           214: SIGPIPE        13      write on a pipe with no one to read it
        !           215: SIGALRM        14      alarm clock
        !           216: SIGTERM        15      software termination signal
        !           217: SIGURG 16\*b\*p        urgent condition present on socket
        !           218: SIGSTOP        17\*d   stop (cannot be caught, blocked, or ignored)
        !           219: SIGTSTP        18\*d   stop signal generated from keyboard
        !           220: SIGCONT        19\*b   continue after stop
        !           221: SIGCHLD        20\*b   child status has changed
        !           222: SIGTTIN        21\*d   background read attempted from control terminal
        !           223: SIGTTOU        22\*d   background write attempted to control terminal
        !           224: SIGIO  23\*b\*p        i/o is possible on a descriptor (see \fIfcntl\fP(2))
        !           225: SIGXCPU        24\*p   cpu time limit exceeded (see \fIsetrlimit\fP(2))
        !           226: SIGXFSZ        25\*p   file size limit exceeded (see \fIsetrlimit\fP(2))
        !           227: SIGVTALRM      26\*p   virtual time alarm (see \fIsetitimer\fP(2))
        !           228: SIGPROF        27\*p   profiling timer alarm (see \fIsetitimer\fP(2))
        !           229: SIGWINCH       28\*b\*p        window size change
        !           230: SIGINFO        29\*b\*p        status request from keyboard
        !           231: SIGUSR1        30      user-defined signal 1
        !           232: SIGUSR2        31      user-defined signal 2
        !           233: .RE
        !           234: .fi
        !           235: .PP
        !           236: The default signal action is termination
        !           237: if the signal is not caught or ignored,
        !           238: except for signals marked with \*b or \*d.
        !           239: The starred signals in the list above cause termination with a core image.
        !           240: Signals marked with \*b are discarded if the action
        !           241: is SIG_DFL; signals marked
        !           242: with \*d cause the process to stop.
        !           243: The signals marked with \*p are not defined by POSIX.
        !           244: .SH NOTES
        !           245: The mask specified in 
        !           246: .I act
        !           247: is not allowed to block SIGKILL or SIGSTOP.
        !           248: This is done silently by the system.
        !           249: .SH "RETURN VALUE
        !           250: A 0 value indicated that the call succeeded.  A \-1 return value
        !           251: indicates an error occurred and
        !           252: .I errno
        !           253: is set to indicated the reason.
        !           254: .SH ERRORS
        !           255: .I Sigaction
        !           256: will fail and no new signal handler will be installed if one
        !           257: of the following occurs:
        !           258: .TP 15
        !           259: [EFAULT]
        !           260: Either
        !           261: .I act
        !           262: or 
        !           263: .I oact
        !           264: points to memory that is not a valid part of the process
        !           265: address space.
        !           266: .TP 15
        !           267: [EINVAL]
        !           268: .I Sig
        !           269: is not a valid signal number.
        !           270: .TP 15
        !           271: [EINVAL]
        !           272: An attempt is made to ignore or supply a handler for SIGKILL
        !           273: or SIGSTOP.
        !           274: .SH STANDARDS
        !           275: The
        !           276: .I sigaction
        !           277: function is defined by POSIX.1.
        !           278: The SA_ONSTACK and SA_RESTART flags are Berkeley extensions,
        !           279: as are the signals marked with \*p.
        !           280: Most of those signals are available on most BSD-derived systems.
        !           281: .SH "SEE ALSO"
        !           282: kill(1), ptrace(2), kill(2),
        !           283: sigaction(2), sigprocmask(2), sigsetops(2), sigsuspend(2),
        !           284: sigblock(2), sigsetmask(2), sigpause(2),
        !           285: sigstack(2), sigvec(2), setjmp(3), siginterrupt(3), tty(4)
        !           286: .SH "NOTES  (VAX-11)"
        !           287: The handler routine can be declared:
        !           288: .PP
        !           289:     void handler(sig, code, scp)
        !           290:     int sig, code;
        !           291:     struct sigcontext *scp;
        !           292: .PP
        !           293: Here
        !           294: .I sig
        !           295: is the signal number, into which the hardware faults and traps are
        !           296: mapped as defined below. 
        !           297: .I Code
        !           298: is a parameter that is either a constant
        !           299: as given below or, for compatibility mode faults, the code provided by
        !           300: the hardware (Compatibility mode faults are distinguished from the
        !           301: other SIGILL traps by having PSL_CM set in the psl).
        !           302: .I Scp
        !           303: is a pointer to the
        !           304: .I sigcontext
        !           305: structure (defined in
        !           306: .RI < signal.h >),
        !           307: used to restore the context from before the signal.
        !           308: .PP
        !           309: The following defines the mapping of hardware traps to signals
        !           310: and codes.  All of these symbols are defined in
        !           311: .RI < signal.h >:
        !           312: .LP
        !           313: .ta \w'     Floating/decimal divide by zero   'u +\w'15*  'u +8n
        !           314: .nf
        !           315:    Hardware condition  Signal  Code
        !           316: 
        !           317: Arithmetic traps:
        !           318:    Integer overflow    SIGFPE  FPE_INTOVF_TRAP
        !           319:    Integer division by zero    SIGFPE  FPE_INTDIV_TRAP
        !           320:    Floating overflow trap      SIGFPE  FPE_FLTOVF_TRAP
        !           321:    Floating/decimal division by zero   SIGFPE  FPE_FLTDIV_TRAP
        !           322:    Floating underflow trap     SIGFPE  FPE_FLTUND_TRAP
        !           323:    Decimal overflow trap       SIGFPE  FPE_DECOVF_TRAP
        !           324:    Subscript-range     SIGFPE  FPE_SUBRNG_TRAP
        !           325:    Floating overflow fault     SIGFPE  FPE_FLTOVF_FAULT
        !           326:    Floating divide by zero fault       SIGFPE  FPE_FLTDIV_FAULT
        !           327:    Floating underflow fault    SIGFPE  FPE_FLTUND_FAULT
        !           328: Length access control  SIGSEGV
        !           329: Protection violation   SIGBUS
        !           330: Reserved instruction   SIGILL  ILL_RESAD_FAULT
        !           331: Customer-reserved instr.       SIGEMT
        !           332: Reserved operand       SIGILL  ILL_PRIVIN_FAULT
        !           333: Reserved addressing    SIGILL  ILL_RESOP_FAULT
        !           334: Trace pending  SIGTRAP
        !           335: Bpt instruction        SIGTRAP
        !           336: Compatibility-mode     SIGILL  hardware supplied code
        !           337: Chme   SIGSEGV
        !           338: Chms   SIGSEGV
        !           339: Chmu   SIGSEGV
        !           340: .fi
        !           341: .SH BUGS
        !           342: This manual page is still confusing.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.