1.\" Copyright (c) 2020 M. Warner Losh <imp@FreeBSD.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 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.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd November 20, 2020 28.Dt disk 4 29.Os 30.Sh NAME 31.Nm disk 32.Nd common disk interfaces 33.Sh SYNOPSIS 34.Cd device cd 35.Sh DESCRIPTION 36Common block device IOCTLs 37.Pp 38All the block devices in the system should support these disk 39.Xr ioctl 2 40commands defined here. 41Much of this information is also available via the 42.Xr geom 2 43attributes. 44.Sh IOCTLS 45The following 46.Xr ioctl 2 47calls apply to disk drives, and are defined 48in the 49.In sys/disk.h 50header file. 51.Bl -tag -width DIOCGPROVIDERNAME 52.It Dv DIOCGSECTORSIZE 53.Pq Li "u_int" 54Get the sector or block size of the device in bytes. 55The sector size is the smallest unit of data which can be transferred 56from this device. 57This is usually a power of 2 but it might not be (e.g. CDROM audio). 58Operations to block devices such as 59.Xr lseek 2 , 60.Xr read 2 , 61and 62.Xr write 63may only be performed at file offsets that are integral multiple of 64this size. 65.It Dv DIOCGMEDIASIZE 66.Pq Li "off_t" 67Get the size of the entire device in bytes. 68This should be a multiple of the sector size. 69.It Dv DIOCGFWSECTORS 70.Pq Li "u_int" 71Return the firmware's notion of number of sectors per track. 72This value is mostly used for compatibility with various ill designed 73disk label formats. 74Use this value only when absolutely required. 75Its interpretation and use is largely obsolete. 76.It Dv DIOCGFWHEADS 77.Pq Li "u_int" 78Return the firmware's notion of number of heads per cylinder. 79This value is mostly used for compatibility with various ill designed 80disk label formats. 81Use this value only when absolutely required. 82Its interpretation and use is largely obsolete. 83.It Dv DIOCGFLUSH 84Flush write cache of the device. 85.It Dv DIOCGDELETE 86.Pq Li "off_t[2]" 87Mark data on the device as unused. 88The first element is the offset to start deleting. 89The second element is the length to delete. 90Providers may use this information to free storage or instruct storage 91devices the contents can be discarded. 92.It Dv DIOCGIDENT 93.Pq Li "char[DISK_IDENT_SIZE]" 94Get the ident for this provider. 95Ident is a unique and fixed identifier for this provider. 96Ident's properties are as follow: 97.Bl -bullet 98.It 99preserved between reboots, 100.It 101preserved across a provider being detached/attached, 102.It 103provider's name can change - ident can't, 104.It 105ident value should not be based on on-disk metadata; in other 106words, copying whole data from one disk to another should not 107yield the same ident for the other disk, 108.It 109there can be more than one provider with the same ident, but 110only if they point at exactly the same physical storage, this is 111the case for multipathing for example, 112.It 113GEOM classes that consume a single provider and provide single 114provider, like 115.Xr geli 8 , 116and 117.Xr gbde 8 , 118the identifier should be formed by attaching that provider's class 119name to the ident of the underlying provider, 120.It 121ident is an NUL-terminated ASCII string (is printable), 122.It 123ident is optional and applications can't relay on its presence. 124.El 125.It Dv DIOCGPROVIDERNAME 126.Pq Li "char[MAXPATHLEN]" 127Store the provider name for the device in a buffer. 128The buffer must be at least MAXPATHLEN bytes long. 129.It Dv DIOCGSTRIPESIZE 130.Pq Li "off_t" 131Get the size of the device's optimal access block in bytes. 132This should be a multiple of the sector size. 133.It Dv DIOCGSTRIPEOFFSET 134.Pq Li "off_t" 135Get the offset of the first device's optimal access block in bytes. 136This should be a multiple of the sector size. 137.It Dv DIOCGPHYSPATH 138.Pq Li "char[MAXPATHLEN]" 139Get a string defining the physical path for a given provider. 140This has similar rules to ident, but is intended to uniquely 141identify the physical location of the device, not the current 142occupant of that location. 143The buffer must be at least MAXPATHLEN bytes long. 144.It Dv DIOCGATTR 145.Pq Li "struct diocgattr_arg" 146.Bd -literal -offset indent 147struct diocgattr_arg { 148 char name[64]; 149 int len; 150 union { 151 char str[DISK_IDENT_SIZE]; 152 off_t off; 153 int i; 154 uint16_t u16; 155 } value; 156}; 157.Ed 158Get a geom attribute from the provider. 159Format of the returned data is specific to the attribute. 160.It Dv DIOCZONECMD 161.Pq Li "struct disk_zone_arg" 162Send disk zone commands. 163.It Dv DIOCSKERNELDUMP 164.Pq Li "struct diocskerneldump_arg" 165Enable/Disable the device for kernel core dumps. 166.It Dv DIOCGKERNELDUMP 167.Pq Li "struct diocskerneldump_arg" 168Get current kernel netdump configuration details for a given index. 169.Bd -literal -offset indent 170/* 171 * Sentinel values for kda_index. 172 * 173 * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared. 174 * 175 * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified 176 * device are cleared. 177 * 178 * If kda_index is KDA_REMOVE, only the specified dump configuration for the 179 * given device is removed from the list of fallback dump configurations. 180 * 181 * If kda_index is KDA_APPEND, the dump configuration is added after all 182 * existing dump configurations. 183 * 184 * Otherwise, the new configuration is inserted into the fallback dump list at 185 * index 'kda_index'. 186 */ 187#define KDA_REMOVE UINT8_MAX 188#define KDA_REMOVE_ALL (UINT8_MAX - 1) 189#define KDA_REMOVE_DEV (UINT8_MAX - 2) 190#define KDA_APPEND (UINT8_MAX - 3) 191struct diocskerneldump_arg { 192 uint8_t kda_index; 193 uint8_t kda_compression; 194 uint8_t kda_encryption; 195 uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE]; 196 uint32_t kda_encryptedkeysize; 197 uint8_t *kda_encryptedkey; 198 char kda_iface[IFNAMSIZ]; 199 union kd_ip kda_server; 200 union kd_ip kda_client; 201 union kd_ip kda_gateway; 202 uint8_t kda_af; 203}; 204.Ed 205.El 206.Sh HISTORY 207The manual page was written by 208.An M Warner Losh Aq Mt imp@FreeBSD.org 209from text largely derived from 210.In sys/disk.h . 211