Document disk ioctl
First stab at documenting the different disk ioctl commands defined in sys/disk.h. Reviewed by: phk (prior version) Differential Revision: https://reviews.freebsd.org/D26994
This commit is contained in:
Warner Losh
parent
c78a221821
commit
24d79e9b63
@ -130,6 +130,7 @@ MAN= aac.4 \
|
||||
ddb.4 \
|
||||
devctl.4 \
|
||||
disc.4 \
|
||||
disk.4 \
|
||||
divert.4 \
|
||||
${_dpms.4} \
|
||||
ds1307.4 \
|
||||
|
||||
210
share/man/man4/disk.4
Normal file
210
share/man/man4/disk.4
Normal file
@ -0,0 +1,210 @@
|
||||
.\" Copyright (c) 2020 M. Warner Losh <imp@FreeBSD.org>
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\"
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd November 20, 2020
|
||||
.Dt disk 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm disk
|
||||
.Nd common disk interfaces
|
||||
.Sh SYNOPSIS
|
||||
.Cd device cd
|
||||
.Sh DESCRIPTION
|
||||
Common block device IOCTLs
|
||||
.Pp
|
||||
All the block devices in the system should support these disk
|
||||
.Xr ioctl 2
|
||||
commands defined here.
|
||||
Much of this information is also available via the
|
||||
.Xr geom 2
|
||||
attributes.
|
||||
.Sh IOCTLS
|
||||
The following
|
||||
.Xr ioctl 2
|
||||
calls apply to disk drives, and are defined
|
||||
in the
|
||||
.In sys/disk.h
|
||||
header file.
|
||||
.Bl -tag -width DIOCGPROVIDERNAME
|
||||
.It Dv DIOCGSECTORSIZE
|
||||
.Pq Li "u_int"
|
||||
Get the sector or block size of the device in bytes.
|
||||
The sector size is the smallest unit of data which can be transferred
|
||||
from this device.
|
||||
This is usually a power of 2 but it might not be (e.g. CDROM audio).
|
||||
Operations to block devices such as
|
||||
.Xr lseek 2 ,
|
||||
.Xr read 2 ,
|
||||
and
|
||||
.Xr write
|
||||
may only be performed at file offsets that are integral multiple of
|
||||
this size.
|
||||
.It Dv DIOCGMEDIASIZE
|
||||
.Pq Li "off_t"
|
||||
Get the size of the entire device in bytes.
|
||||
This should be a multiple of the sector size.
|
||||
.It Dv DIOCGFWSECTORS
|
||||
.Pq Li "u_int"
|
||||
Return the firmware's notion of number of sectors per track.
|
||||
This value is mostly used for compatibility with various ill designed
|
||||
disk label formats.
|
||||
Use this value only when absolutely required.
|
||||
Its interpretation and use is largely obsolete.
|
||||
.It Dv DIOCGFWHEADS
|
||||
.Pq Li "u_int"
|
||||
Return the firmware's notion of number of heads per cylinder.
|
||||
This value is mostly used for compatibility with various ill designed
|
||||
disk label formats.
|
||||
Use this value only when absolutely required.
|
||||
Its interpretation and use is largely obsolete.
|
||||
.It Dv DIOCGFLUSH
|
||||
Flush write cache of the device.
|
||||
.It Dv DIOCGDELETE
|
||||
.Pq Li "off_t[2]"
|
||||
Mark data on the device as unused.
|
||||
The first element is the offset to start deleting.
|
||||
The second element is the length to delete.
|
||||
Providers may use this information to free storage or instruct storage
|
||||
devices the contents can be discarded.
|
||||
.It Dv DIOCGIDENT
|
||||
.Pq Li "char[DISK_IDENT_SIZE]"
|
||||
Get the ident for this provider.
|
||||
Ident is a unique and fixed identifier for this provider.
|
||||
Ident's properties are as follow:
|
||||
.Bl -bullet
|
||||
.It
|
||||
preserved between reboots,
|
||||
.It
|
||||
preserved across a provider being detached/attached,
|
||||
.It
|
||||
provider's name can change - ident can't,
|
||||
.It
|
||||
ident value should not be based on on-disk metadata; in other
|
||||
words, copying whole data from one disk to another should not
|
||||
yield the same ident for the other disk,
|
||||
.It
|
||||
there can be more than one provider with the same ident, but
|
||||
only if they point at exactly the same physical storage, this is
|
||||
the case for multipathing for example,
|
||||
.It
|
||||
GEOM classes that consume a single provider and provide single
|
||||
provider, like
|
||||
.Xr geli 8 ,
|
||||
and
|
||||
.Xr gbde 8 ,
|
||||
the identifier should be formed by attaching that provider's class
|
||||
name to the ident of the underlying provider,
|
||||
.It
|
||||
ident is an NUL-terminated ASCII string (is printable),
|
||||
.It
|
||||
ident is optional and applications can't relay on its presence.
|
||||
.El
|
||||
.It Dv DIOCGPROVIDERNAME
|
||||
.Pq Li "char[MAXPATHLEN]"
|
||||
Store the provider name for the device in a buffer.
|
||||
The buffer must be at least MAXPATHLEN bytes long.
|
||||
.It Dv DIOCGSTRIPESIZE
|
||||
.Pq Li "off_t"
|
||||
Get the size of the device's optimal access block in bytes.
|
||||
This should be a multiple of the sector size.
|
||||
.It Dv DIOCGSTRIPEOFFSET
|
||||
.Pq Li "off_t"
|
||||
Get the offset of the first device's optimal access block in bytes.
|
||||
This should be a multiple of the sector size.
|
||||
.It Dv DIOCGPHYSPATH
|
||||
.Pq Li "char[MAXPATHLEN]"
|
||||
Get a string defining the physical path for a given provider.
|
||||
This has similar rules to ident, but is intended to uniquely
|
||||
identify the physical location of the device, not the current
|
||||
occupant of that location.
|
||||
The buffer must be at least MAXPATHLEN bytes long.
|
||||
.It Dv DIOCGATTR
|
||||
.Pq Li "struct diocgattr_arg"
|
||||
.Bd -literal -offset indent
|
||||
struct diocgattr_arg {
|
||||
char name[64];
|
||||
int len;
|
||||
union {
|
||||
char str[DISK_IDENT_SIZE];
|
||||
off_t off;
|
||||
int i;
|
||||
uint16_t u16;
|
||||
} value;
|
||||
};
|
||||
.Ed
|
||||
Get a geom attribute from the provider.
|
||||
Format of the returned data is specific to the attribute.
|
||||
.It Dv DIOCZONECMD
|
||||
.Pq Li "struct disk_zone_arg"
|
||||
Send disk zone commands.
|
||||
.It Dv DIOCSKERNELDUMP
|
||||
.Pq Li "struct diocskerneldump_arg"
|
||||
Enable/Disable the device for kernel core dumps.
|
||||
.It Dv DIOCGKERNELDUMP
|
||||
.Pq Li "struct diocskerneldump_arg"
|
||||
Get current kernel netdump configuration details for a given index.
|
||||
.Bd -literal -offset indent
|
||||
/*
|
||||
* Sentinel values for kda_index.
|
||||
*
|
||||
* If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared.
|
||||
*
|
||||
* If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified
|
||||
* device are cleared.
|
||||
*
|
||||
* If kda_index is KDA_REMOVE, only the specified dump configuration for the
|
||||
* given device is removed from the list of fallback dump configurations.
|
||||
*
|
||||
* If kda_index is KDA_APPEND, the dump configuration is added after all
|
||||
* existing dump configurations.
|
||||
*
|
||||
* Otherwise, the new configuration is inserted into the fallback dump list at
|
||||
* index 'kda_index'.
|
||||
*/
|
||||
#define KDA_REMOVE UINT8_MAX
|
||||
#define KDA_REMOVE_ALL (UINT8_MAX - 1)
|
||||
#define KDA_REMOVE_DEV (UINT8_MAX - 2)
|
||||
#define KDA_APPEND (UINT8_MAX - 3)
|
||||
struct diocskerneldump_arg {
|
||||
uint8_t kda_index;
|
||||
uint8_t kda_compression;
|
||||
uint8_t kda_encryption;
|
||||
uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE];
|
||||
uint32_t kda_encryptedkeysize;
|
||||
uint8_t *kda_encryptedkey;
|
||||
char kda_iface[IFNAMSIZ];
|
||||
union kd_ip kda_server;
|
||||
union kd_ip kda_client;
|
||||
union kd_ip kda_gateway;
|
||||
uint8_t kda_af;
|
||||
};
|
||||
.Ed
|
||||
.El
|
||||
.Sh HISTORY
|
||||
The manual page was written by
|
||||
.An M Warner Losh Aq Mt imp@FreeBSD.org
|
||||
from text largely derived from
|
||||
.In sys/disk.h .
|
||||
Loading…
Reference in New Issue
Block a user