1.\" $OpenBSD: sigio_init.9,v 1.3 2018/11/12 18:27:31 jmc 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: November 12 2018 $ 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" "pid_t pgid" 37.Ft pid_t 38.Fn "sigio_getown" "struct sigio_ref *sir" 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. 63If 64.Fa pgid 65is positive, the ID is taken as a process ID. 66If 67.Fa pgid 68is negative, the ID is taken as a process group ID. 69The reference 70.Fa sir 71is cleared if 72.Fa pgid 73is zero. 74.Pp 75When 76.Fn sigio_setown 77is called, the invoking process' credentials are stored in the reference. 78These credentials are checked when the reference is used with 79.Xr pgsigio 9 . 80.Pp 81.Fn sigio_getown 82returns the ID of the process or process group associated with the reference 83.Fa sir . 84.Sh CONTEXT 85.Fn sigio_init , 86.Fn sigio_free , 87.Fn sigio_copy , 88.Fn sigio_setown 89and 90.Fn sigio_getown 91can be called during autoconf, or from process context. 92.Sh RETURN VALUES 93.Fn sigio_setown 94returns 0 on success. 95Otherwise, the following error values are returned: 96.Bl -tag -width [EPERM] 97.It Bq Er EPERM 98The invoking process belongs to another session than the process 99or process group 100.Fa pgid . 101.It Bq Er ESRCH 102The process or process group 103.Fa pgid 104does not exist. 105.It Bq Er ESRCH 106The process 107.Fa pgid 108is exiting. 109.El 110.Pp 111The function 112.Fn sigio_getown 113returns the ID of the process or process group associated with reference 114.Fa sir , 115or zero if no signal target has been registered. 116.Sh SEE ALSO 117.Xr pgsigio 9 118.Sh HISTORY 119The sigio routines were adapted from 120.Fx 121and first appeared in 122.Ox 6.5 . 123