1.\" $NetBSD: opendisk.3,v 1.17 2024/10/13 14:56:31 rillig Exp $ 2.\" 3.\" Copyright (c) 1997, 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 13, 2024 31.Dt OPENDISK 3 32.Os 33.Sh NAME 34.Nm opendisk , 35.Nm opendisk1 36.Nd open a disk partition 37.Sh LIBRARY 38.Lb libutil 39.Sh SYNOPSIS 40.In util.h 41.Ft int 42.Fo opendisk 43.Fa "const char *path" 44.Fa "int flags" 45.Fa "char *buf" 46.Fa "size_t buflen" 47.Fa "int iscooked" 48.Fc 49.Ft int 50.Fo opendisk1 51.Fa "const char *path" 52.Fa "int flags" 53.Fa "char *buf" 54.Fa "size_t buflen" 55.Fa "int iscooked" 56.Fa "int (*ofn)(const char *, int, ...)" 57.Fc 58.Sh DESCRIPTION 59.Fn opendisk 60opens 61.Fa path , 62for reading and/or writing as specified by the argument 63.Fa flags 64using 65.Xr open 2 , 66and the file descriptor is returned to the caller. 67.Fa buf 68is used to store the resultant filename. 69.Fa buflen 70is the size, in bytes, of the array referenced by 71.Fa buf 72(usually 73.Dv MAXPATHLEN 74bytes). 75.Fa iscooked 76controls which paths in 77.Pa /dev 78are tried. 79.Pp 80.Fn opendisk 81attempts to open the following variations of 82.Fa path , 83in order: 84.Pp 85If 86.Fa path 87does not contain a 88slash 89.Pq Dq / , 90the following variations are attempted: 91.Pp 92.Bl -dash -compact 93.It 94If 95.Fa iscooked 96is zero: 97.Bl -tag -compact -width "/dev/rpathX" 98.It Pa /dev/rpath 99.Fa path 100with a prefix of 101.Dq Pa /dev/r . 102.It Pa /dev/rpath Ns Em X 103.Fa path 104with a prefix of 105.Dq Pa /dev/r 106and a suffix of 107.Sq Em X 108(q.v.). 109.El 110.It 111If 112.Fa iscooked 113is non-zero: 114.Bl -tag -compact -width "/dev/rpathX" 115.It Pa /dev/path 116.Fa path 117with a prefix of 118.Dq Pa /dev/ . 119.It Pa /dev/path Ns Em X 120.Fa path 121with a prefix of 122.Dq Pa /dev/ 123and a suffix of 124.Sq Em X 125(q.v.). 126.El 127.El 128.Pp 129If the above fails, then the original 130.Fa path 131is tried using the following two variations: 132.Pp 133.Bl -dash -compact 134.It 135The 136.Fa iscooked 137value is ignored: 138.Bl -tag -compact -width "/dev/rpathX" 139.It Pa path 140The pathname as given. 141.It Pa path Ns Em X 142.Fa path 143with a suffix of 144.Sq Em X , 145where 146.Sq Em X 147represents the raw partition of the device, as determined by 148.Xr getrawpartition 3 , 149usually 150.Dq c 151or 152.Dq d . 153.El 154.El 155.Pp 156.Fn opendisk1 157is identical to 158.Fn opendisk 159except uses the supplied 160.Fa ofn 161function instead of 162.Xr open 2 . 163This function must be compatible 164with 165.Xr open 2 166in the parameters it takes, 167the value it returns, 168and way that errors are indicated. 169.Sh RETURN VALUES 170An open file descriptor, or -1 if the 171.Xr open 2 172failed. 173.Sh ERRORS 174.Fn opendisk 175and 176.Fn opendisk1 177may set 178.Va errno 179to one of the following values: 180.Bl -tag -width Er 181.It Bq Er EFAULT 182.Fa buf 183was the 184.Dv NULL 185pointer. 186.It Bq Er EINVAL 187.Dv O_CREAT 188was set in 189.Fa flags , 190or 191.Xr getrawpartition 3 192didn't return a valid partition. 193.El 194.Pp 195The 196.Fn opendisk 197function 198may also set 199.Va errno 200to any value specified by the 201.Xr open 2 202function. 203.Pp 204The 205.Fn opendisk1 206function may also set 207.Va errno 208to any value set by the 209.Fa ofn 210function. 211.Sh SEE ALSO 212.Xr open 2 , 213.Xr getrawpartition 3 214.Sh HISTORY 215The 216.Fn opendisk 217function first appeared in 218.Nx 1.3 . 219.Pp 220The 221.Fn opendisk1 222function first appeared in 223.Nx 6.0 , 224and was documented in 225.Nx 8.0 . 226.Pp 227The lookup order of 228.Fn opendisk 229was changed in 230.Nx 7.1 231to first look in 232.Pa /dev 233in order to avoid opening random files in the current working directory. 234