lib/libc/gen/siginterrupt.3

   1 .\" Copyright (c) 1985, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)siginterrupt.3      8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/siginterrupt.3,v 1.6.2.4 2001/12/14 18:33:51 ru Exp $
  34 .\" $DragonFly: src/lib/libc/gen/siginterrupt.3,v 1.3 2004/03/11 12:28:50 hmp Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt SIGINTERRUPT 3
  38 .Os
  39 .Sh NAME
  40 .Nm siginterrupt
  41 .Nd allow signals to interrupt system calls
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In signal.h
  46 .Ft int
  47 .Fn siginterrupt "int sig" "int flag"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn siginterrupt
  51 function
  52 is used to change the system call restart
  53 behavior when a system call is interrupted by the specified signal.
  54 If the flag is false (0), then system calls will be restarted if
  55 they are interrupted by the specified signal
  56 and no data has been transferred yet.
  57 System call restart has been the default behavior since
  58 .Bx 4.2 ,
  59 and is the default behaviour for
  60 .Xr signal 3
  61 on
  62 .Dx .
  63 .Pp
  64 If the flag is true (1),
  65 then restarting of system calls is disabled.
  66 If a system call is interrupted by the specified signal
  67 and no data has been transferred,
  68 the system call will return \-1 with the global variable
  69 .Va errno
  70 set to
  71 .Er EINTR .
  72 Interrupted system calls that have started transferring
  73 data will return the amount of data actually transferred.
  74 System call interrupt is the signal behavior found on
  75 .Bx 4.1
  76 and
  77 .At V
  78 systems.
  79 .Pp
  80 Note that the new
  81 .Bx 4.2
  82 signal handling semantics are not
  83 altered in any other way.
  84 Most notably, signal handlers always remain installed until
  85 explicitly changed by a subsequent
  86 .Xr sigaction 2
  87 call, and the signal mask operates as documented in
  88 .Xr sigaction 2 .
  89 Programs may switch between restartable and interruptible
  90 system call operation as often as desired in the execution of a program.
  91 .Pp
  92 Issuing a
  93 .Fn siginterrupt 3
  94 call during the execution of a signal handler will cause
  95 the new action to take place on the next signal to be caught.
  96 .Sh NOTES
  97 This library routine uses an extension of the
  98 .Xr sigaction 2
  99 system call that is not available in
 100 .Bx 4.2 ,
 101 hence it should not be used if backward compatibility is needed.
 102 .Sh RETURN VALUES
 103 .Rv -std siginterrupt
 104 .Sh ERRORS
 105 The
 106 .Fn siginterrupt
 107 call fails if:
 108 .Bl -tag -width Er
 109 .It Bq Er EINVAL
 110 .Fa sig
 111 is not a valid signal number.
 112 .El
 113 .Sh SEE ALSO
 114 .Xr sigaction 2 ,
 115 .Xr sigblock 2 ,
 116 .Xr sigpause 2 ,
 117 .Xr sigsetmask 2 ,
 118 .Xr signal 3
 119 .Sh HISTORY
 120 The
 121 .Fn siginterrupt
 122 function appeared in
 123 .Bx 4.3 .