1.\" $OpenBSD: sigio_init.9,v 1.4 2020/01/08 16:27:40 visa Exp $ 2.\" 3.\" Copyright (c) 2018 Visa Hankala 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 8 2020 $ 18.Dt SIGIO_INIT 9 19.Os 20.Sh NAME 21.Nm sigio_init , 22.Nm sigio_free , 23.Nm sigio_copy , 24.Nm sigio_setown , 25.Nm sigio_getown 26.Nd asynchronous IO signal API 27.Sh SYNOPSIS 28.In sys/sigio.h 29.Ft void 30.Fn "sigio_init" "struct sigio_ref *sir" 31.Ft void 32.Fn "sigio_free" "struct sigio_ref *sir" 33.Ft void 34.Fn "sigio_copy" "struct sigio_ref *dst" "struct sigio_ref *src" 35.Ft int 36.Fn "sigio_setown" "struct sigio_ref *sir" "u_long cmd" "caddr_t data" 37.Ft pid_t 38.Fn "sigio_getown" "struct sigio_ref *sir" "u_long cmd" "caddr_t data" 39.Sh DESCRIPTION 40The asynchronous IO signal API provides a means to manage signal registrations. 41It associates a process or process group with a signal source. 42The association is revoked automatically when the process or process group 43is deleted. 44.Pp 45.Fn sigio_init 46initializes the sigio reference 47.Fa sir . 48.Pp 49.Fn sigio_free 50clears any process or process group associated with reference 51.Fa sir . 52.Pp 53.Fn sigio_copy 54copies registration from reference 55.Fa src 56to reference 57.Fa dst . 58.Pp 59.Fn sigio_setown 60associates the reference 61.Fa sir 62with a process or process group. 63.Fa cmd 64is one of ioctl commands 65.Dv FIOSETOWN , 66.Dv SIOCSPGRP 67and 68.Dv TIOCSPGRP . 69.Fa data 70is a pointer to a signed integer that represents the ID of the owner 71of the registration. 72For 73.Dv FIOSETOWN 74and 75.Dv SIOCSPGRP , 76a positive ID is taken as a process ID, 77and a negative ID is taken as a process group ID. 78If 79.Fa cmd 80is 81.Dv TIOCSPGRP , 82a positive ID is taken as a process group ID, 83and negative ID values are not allowed. 84For all values of 85.Fa cmd , 86the reference 87.Fa sir 88is cleared if the ID is zero. 89.Pp 90When 91.Fn sigio_setown 92is called, the invoking process' credentials are stored in the reference. 93These credentials are checked when the reference is used with 94.Xr pgsigio 9 . 95.Pp 96.Fn sigio_getown 97stores the ID of the process or process group associated with the reference 98.Fa sir 99to the signed integer pointed by 100.Fa data . 101.Fa cmd 102is one of ioctl commands 103.Dv FIOGETOWN , 104.Dv SIOCGPGRP 105and 106.Dv TIOCGPGRP . 107For 108.Dv FIOGETOWN 109and 110.Dv SIOCGPGRP , 111a process ID is stored as a positive ID, 112and a process group ID is stored as a negative ID. 113For 114.Dv TIOCGPGRP , 115a process ID is stored as a negative ID, 116and a process group ID is stored as a positive ID. 117If there is no registered owner, a zero is stored in the integer. 118.Sh CONTEXT 119.Fn sigio_init , 120.Fn sigio_free , 121.Fn sigio_copy , 122.Fn sigio_setown 123and 124.Fn sigio_getown 125can be called during autoconf, or from process context. 126.Sh RETURN VALUES 127.Fn sigio_setown 128returns 0 on success. 129Otherwise, the following error values are returned: 130.Bl -tag -width [EINVAL] 131.It Bq Er EINVAL 132The process group ID is invalid. 133.It Bq Er EPERM 134The invoking process belongs to another session than the process 135or process group. 136.It Bq Er ESRCH 137The process or process group does not exist. 138.It Bq Er ESRCH 139The process is exiting. 140.El 141.Sh SEE ALSO 142.Xr pgsigio 9 143.Sh HISTORY 144The sigio routines were adapted from 145.Fx 146and first appeared in 147.Ox 6.5 . 148