share/man/man4/disk.4

   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
  36 Common block device IOCTLs
  37 .Pp
  38 All the block devices in the system should support these disk
  39 .Xr ioctl 2
  40 commands defined here.
  41 Much of this information is also available via the
  42 .Xr geom 2
  43 attributes.
  44 .Sh IOCTLS
  45 The following
  46 .Xr ioctl 2
  47 calls apply to disk drives, and are defined
  48 in the
  49 .In sys/disk.h
  50 header file.
  51 .Bl -tag -width DIOCGPROVIDERNAME
  52 .It Dv DIOCGSECTORSIZE
  53 .Pq Li "u_int"
  54 Get the sector or block size of the device in bytes.
  55 The sector size is the smallest unit of data which can be transferred
  56 from this device.
  57 This is usually a power of 2 but it might not be (e.g. CDROM audio).
  58 Operations to block devices such as
  59 .Xr lseek 2 ,
  60 .Xr read 2 ,
  61 and
  62 .Xr write
  63 may only be performed at file offsets that are integral multiple of
  64 this size.
  65 .It Dv DIOCGMEDIASIZE
  66 .Pq Li "off_t"
  67 Get the size of the entire device in bytes.
  68 This should be a multiple of the sector size.
  69 .It Dv DIOCGFWSECTORS
  70 .Pq Li "u_int"
  71 Return the firmware's notion of number of sectors per track.
  72 This value is mostly used for compatibility with various ill designed
  73 disk label formats.
  74 Use this value only when absolutely required.
  75 Its interpretation and use is largely obsolete.
  76 .It Dv DIOCGFWHEADS
  77 .Pq Li "u_int"
  78 Return the firmware's notion of number of heads per cylinder.
  79 This value is mostly used for compatibility with various ill designed
  80 disk label formats.
  81 Use this value only when absolutely required.
  82 Its interpretation and use is largely obsolete.
  83 .It Dv DIOCGFLUSH
  84 Flush write cache of the device.
  85 .It Dv DIOCGDELETE
  86 .Pq Li "off_t[2]"
  87 Mark data on the device as unused.
  88 The first element is the offset to start deleting.
  89 The second element is the length to delete.
  90 Providers may use this information to free storage or instruct storage
  91 devices the contents can be discarded.
  92 .It Dv DIOCGIDENT
  93 .Pq Li "char[DISK_IDENT_SIZE]"
  94 Get the ident for this provider.
  95 Ident is a unique and fixed identifier for this provider.
  96 Ident's properties are as follow:
  97 .Bl -bullet
  98 .It
  99 preserved between reboots,
 100 .It
 101 preserved across a provider being detached/attached,
 102 .It
 103 provider's name can change - ident can't,
 104 .It
 105 ident value should not be based on on-disk metadata; in other
 106 words, copying whole data from one disk to another should not
 107 yield the same ident for the other disk,
 108 .It
 109 there can be more than one provider with the same ident, but
 110 only if they point at exactly the same physical storage, this is
 111 the case for multipathing for example,
 112 .It
 113 GEOM classes that consume a single provider and provide single
 114 provider, like
 115 .Xr geli 8 ,
 116 and
 117 .Xr gbde 8 ,
 118 the identifier should be formed by attaching that provider's class
 119 name to the ident of the underlying provider,
 120 .It
 121 ident is an NUL-terminated ASCII string (is printable),
 122 .It
 123 ident is optional and applications can't relay on its presence.
 124 .El
 125 .It Dv DIOCGPROVIDERNAME
 126 .Pq Li "char[MAXPATHLEN]"
 127 Store the provider name for the device in a buffer.
 128 The buffer must be at least MAXPATHLEN bytes long.
 129 .It Dv DIOCGSTRIPESIZE
 130 .Pq Li "off_t"
 131 Get the size of the device's optimal access block in bytes.
 132 This should be a multiple of the sector size.
 133 .It Dv DIOCGSTRIPEOFFSET
 134 .Pq Li "off_t"
 135 Get the offset of the first device's optimal access block in bytes.
 136 This should be a multiple of the sector size.
 137 .It Dv DIOCGPHYSPATH
 138 .Pq Li "char[MAXPATHLEN]"
 139 Get a string defining the physical path for a given provider.
 140 This has similar rules to ident, but is intended to uniquely
 141 identify the physical location of the device, not the current
 142 occupant of that location.
 143 The buffer must be at least MAXPATHLEN bytes long.
 144 .It Dv DIOCGATTR
 145 .Pq Li "struct diocgattr_arg"
 146 .Bd -literal -offset indent
 147 struct 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
 158 Get a geom attribute from the provider.
 159 Format of the returned data is specific to the attribute.
 160 .It Dv DIOCZONECMD
 161 .Pq Li "struct disk_zone_arg"
 162 Send disk zone commands.
 163 .It Dv DIOCSKERNELDUMP
 164 .Pq Li "struct diocskerneldump_arg"
 165 Enable/Disable the device for kernel core dumps.
 166 .It Dv DIOCGKERNELDUMP
 167 .Pq Li "struct diocskerneldump_arg"
 168 Get 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)
 191 struct 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
 207 The manual page was written by
 208 .An M Warner Losh Aq Mt imp@FreeBSD.org
 209 from text largely derived from
 210 .In sys/disk.h .