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 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 , 114and 115.Xr gbde 8 , 116the identifier should be formed by attaching that provider's class 117name to the ident of the underlying provider, 118.It 119ident is an NUL-terminated ASCII string (is printable), 120.It 121ident is optional and applications can't relay on its presence. 122.El 123.It Dv DIOCGPROVIDERNAME 124.Pq Li "char[MAXPATHLEN]" 125Store the provider name for the device in a buffer. 126The buffer must be at least MAXPATHLEN bytes long. 127.It Dv DIOCGSTRIPESIZE 128.Pq Li "off_t" 129Get the size of the device's optimal access block in bytes. 130This should be a multiple of the sector size. 131.It Dv DIOCGSTRIPEOFFSET 132.Pq Li "off_t" 133Get the offset of the first device's optimal access block in bytes. 134This should be a multiple of the sector size. 135.It Dv DIOCGPHYSPATH 136.Pq Li "char[MAXPATHLEN]" 137Get a string defining the physical path for a given provider. 138This has similar rules to ident, but is intended to uniquely 139identify the physical location of the device, not the current 140occupant of that location. 141The buffer must be at least MAXPATHLEN bytes long. 142.It Dv DIOCGATTR 143.Pq Li "struct diocgattr_arg" 144.Bd -literal -offset indent 145struct diocgattr_arg { 146 char name[64]; 147 int len; 148 union { 149 char str[DISK_IDENT_SIZE]; 150 off_t off; 151 int i; 152 uint16_t u16; 153 } value; 154}; 155.Ed 156Get a geom attribute from the provider. 157Format of the returned data is specific to the attribute. 158.It Dv DIOCZONECMD 159.Pq Li "struct disk_zone_arg" 160Send disk zone commands. 161.It Dv DIOCSKERNELDUMP 162.Pq Li "struct diocskerneldump_arg" 163Enable/Disable the device for kernel core dumps. 164.It Dv DIOCGKERNELDUMP 165.Pq Li "struct diocskerneldump_arg" 166Get current kernel netdump configuration details for a given index. 167.Bd -literal -offset indent 168/* 169 * Sentinel values for kda_index. 170 * 171 * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared. 172 * 173 * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified 174 * device are cleared. 175 * 176 * If kda_index is KDA_REMOVE, only the specified dump configuration for the 177 * given device is removed from the list of fallback dump configurations. 178 * 179 * If kda_index is KDA_APPEND, the dump configuration is added after all 180 * existing dump configurations. 181 * 182 * Otherwise, the new configuration is inserted into the fallback dump list at 183 * index 'kda_index'. 184 */ 185#define KDA_REMOVE UINT8_MAX 186#define KDA_REMOVE_ALL (UINT8_MAX - 1) 187#define KDA_REMOVE_DEV (UINT8_MAX - 2) 188#define KDA_APPEND (UINT8_MAX - 3) 189struct diocskerneldump_arg { 190 uint8_t kda_index; 191 uint8_t kda_compression; 192 uint8_t kda_encryption; 193 uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE]; 194 uint32_t kda_encryptedkeysize; 195 uint8_t *kda_encryptedkey; 196 char kda_iface[IFNAMSIZ]; 197 union kd_ip kda_server; 198 union kd_ip kda_client; 199 union kd_ip kda_gateway; 200 uint8_t kda_af; 201}; 202.Ed 203.El 204.Sh HISTORY 205The manual page was written by 206.An M Warner Losh Aq Mt imp@FreeBSD.org 207from text largely derived from 208.In sys/disk.h . 209