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