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 .\"
  35 .Dd June 4, 1993
  36 .Dt SIGINTERRUPT 3
  37 .Os
  38 .Sh NAME
  39 .Nm siginterrupt
  40 .Nd allow signals to interrupt system calls
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In signal.h
  45 .Ft int
  46 .Fn siginterrupt "int sig" "int flag"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn siginterrupt
  50 function
  51 is used to change the system call restart
  52 behavior when a system call is interrupted by the specified signal.
  53 If the flag is false (0), then system calls will be restarted if
  54 they are interrupted by the specified signal
  55 and no data has been transferred yet.
  56 System call restart has been the default behavior since
  57 .Bx 4.2 ,
  58 and is the default behaviour for
  59 .Xr signal 3
  60 on
  61 .Dx .
  62 .Pp
  63 If the flag is true (1),
  64 then restarting of system calls is disabled.
  65 If a system call is interrupted by the specified signal
  66 and no data has been transferred,
  67 the system call will return \-1 with the global variable
  68 .Va errno
  69 set to
  70 .Er EINTR .
  71 Interrupted system calls that have started transferring
  72 data will return the amount of data actually transferred.
  73 System call interrupt is the signal behavior found on
  74 .Bx 4.1
  75 and
  76 .At V
  77 systems.
  78 .Pp
  79 Note that the new
  80 .Bx 4.2
  81 signal handling semantics are not
  82 altered in any other way.
  83 Most notably, signal handlers always remain installed until
  84 explicitly changed by a subsequent
  85 .Xr sigaction 2
  86 call, and the signal mask operates as documented in
  87 .Xr sigaction 2 .
  88 Programs may switch between restartable and interruptible
  89 system call operation as often as desired in the execution of a program.
  90 .Pp
  91 Issuing a
  92 .Fn siginterrupt 3
  93 call during the execution of a signal handler will cause
  94 the new action to take place on the next signal to be caught.
  95 .Sh NOTES
  96 This library routine uses an extension of the
  97 .Xr sigaction 2
  98 system call that is not available in
  99 .Bx 4.2 ,
 100 hence it should not be used if backward compatibility is needed.
 101 .Sh RETURN VALUES
 102 .Rv -std siginterrupt
 103 .Sh ERRORS
 104 The
 105 .Fn siginterrupt
 106 call fails if:
 107 .Bl -tag -width Er
 108 .It Bq Er EINVAL
 109 .Fa sig
 110 is not a valid signal number.
 111 .El
 112 .Sh SEE ALSO
 113 .Xr sigaction 2 ,
 114 .Xr sigprocmask 2 ,
 115 .Xr sigsuspend 2 ,
 116 .Xr signal 3
 117 .Sh HISTORY
 118 The
 119 .Fn siginterrupt
 120 function appeared in
 121 .Bx 4.3 .