[unix-history] / usr / src / lib / libc / gen / siginterrupt.3

.\" Copyright (c) 1985, 1991 Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)siginterrupt.3	6.2 (Berkeley) %G%
.\"
.Dd 
.Dt SIGINTERRUPT 3
.Os BSD 4.3
.Sh NAME
.Nm siginterrupt
.Nd allow signals to interrupt system calls
.Sh SYNOPSIS
.Fd #include <signal.h>
.Ft int
.Fn siginterrupt "int sig" "int flag"
.Sh DESCRIPTION
The
.Fn siginterrupt
function
is used to change the system call restart
behavior when a system call is interrupted by the specified signal.
If the flag is false (0), then system calls will be restarted if
they are interrupted by the specified signal
and no data has been transferred yet.
System call restart is the default behavior on
.Bx 4.2 .
.Pp
If the flag is true (1),
then restarting of system calls is disabled.
If a system call is interrupted by the specified signal
and no data has been transferred,
the system call will return \-1 with the global variable
.Va errno
set to
.Dv EINTR . 
Interrupted system calls that have started transferring
data will return the amount of data actually transferred.
System call interrupt is the signal behavior found on
.Bx 4.1
and
.At V
systems.
.Pp
Note that the new
.Bx 4.2
signal handling semantics are not
altered in any other way.
Most notably, signal handlers always remain installed until
explicitly changed by a subsequent
.Xr sigaction 2
call, and the signal mask operates as documented in
.Xr sigaction 2 .
Programs may switch between restartable and interruptible
system call operation as often as desired in the execution of a program.
.Pp
Issuing a
.Fn siginterrupt 3
call during the execution of a signal handler will cause
the new action to take place on the next signal to be caught.
.Sh NOTES
This library routine uses an extension of the
.Xr sigaction 2
system call that is not available in
.Bx 4.2 ,
hence it should not be used if backward compatibility is needed.
.Sh RETURN VALUES
A 0 value indicates that the call succeeded.
A \-1 value indicates that an invalid signal number has been supplied.
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr sigblock 2 ,
.Xr sigpause 2 ,
.Xr sigsetmask 2 .
.Sh HISTORY
The
.Fn siginterrupt
function appeared in 
.Bx 4.3 .
Commit	Line	Data
ae59e04c CL	1	.\" Copyright (c) 1985, 1991 Regents of the University of California.
ae59e04c CL	2	.\" All rights reserved.
53e9b2ee	3	.\"
ae59e04c	4	.\" %sccs.include.redist.man%
53e9b2ee	5	.\"
ae59e04c CL	6	.\" @(#)siginterrupt.3 6.2 (Berkeley) %G%
	7	.\"
	8	.Dd
	9	.Dt SIGINTERRUPT 3
	10	.Os BSD 4.3
	11	.Sh NAME
	12	.Nm siginterrupt
	13	.Nd allow signals to interrupt system calls
	14	.Sh SYNOPSIS
	15	.Fd #include <signal.h>
	16	.Ft int
	17	.Fn siginterrupt "int sig" "int flag"
	18	.Sh DESCRIPTION
	19	The
	20	.Fn siginterrupt
	21	function
53e9b2ee KM	22	is used to change the system call restart
	23	behavior when a system call is interrupted by the specified signal.
	24	If the flag is false (0), then system calls will be restarted if
	25	they are interrupted by the specified signal
	26	and no data has been transferred yet.
ae59e04c CL	27	System call restart is the default behavior on
	28	.Bx 4.2 .
	29	.Pp
	30	If the flag is true (1),
	31	then restarting of system calls is disabled.
53e9b2ee KM	32	If a system call is interrupted by the specified signal
53e9b2ee KM	33	and no data has been transferred,
ae59e04c CL	34	the system call will return \-1 with the global variable
	35	.Va errno
	36	set to
	37	.Dv EINTR .
53e9b2ee KM	38	Interrupted system calls that have started transferring
53e9b2ee KM	39	data will return the amount of data actually transferred.
ae59e04c CL	40	System call interrupt is the signal behavior found on
	41	.Bx 4.1
	42	and
	43	.At V
	44	systems.
	45	.Pp
	46	Note that the new
	47	.Bx 4.2
	48	signal handling semantics are not
53e9b2ee KM	49	altered in any other way.
	50	Most notably, signal handlers always remain installed until
	51	explicitly changed by a subsequent
ae59e04c	52	.Xr sigaction 2
53e9b2ee	53	call, and the signal mask operates as documented in
ae59e04c	54	.Xr sigaction 2 .
53e9b2ee KM	55	Programs may switch between restartable and interruptible
53e9b2ee KM	56	system call operation as often as desired in the execution of a program.
ae59e04c	57	.Pp
53e9b2ee	58	Issuing a
ae59e04c	59	.Fn siginterrupt 3
53e9b2ee KM	60	call during the execution of a signal handler will cause
53e9b2ee KM	61	the new action to take place on the next signal to be caught.
ae59e04c	62	.Sh NOTES
53e9b2ee	63	This library routine uses an extension of the
ae59e04c CL	64	.Xr sigaction 2
	65	system call that is not available in
	66	.Bx 4.2 ,
53e9b2ee	67	hence it should not be used if backward compatibility is needed.
ae59e04c	68	.Sh RETURN VALUES
53e9b2ee	69	A 0 value indicates that the call succeeded.
ae59e04c CL	70	A \-1 value indicates that an invalid signal number has been supplied.
	71	.Sh SEE ALSO
	72	.Xr sigaction 2 ,
	73	.Xr sigblock 2 ,
	74	.Xr sigpause 2 ,
	75	.Xr sigsetmask 2 .
	76	.Sh HISTORY
	77	The
	78	.Fn siginterrupt
	79	function appeared in
	80	.Bx 4.3 .