fd

title: fd(4)

summary: floppy disk device

text:
# fd(4)

## NAME
fd - floppy disk device

## CONFIGURATION
Floppy drives are block devices with major number 2. Typically they are owned by root:floppy (i.e., user root, group floppy) and have either mode 0660 (access checking via group membership) or mode 0666 (everybody has access). The minor numbers encode the device type, drive number, and controller number. For each device type (that is, combination of density and track count) there is a base minor number. To this base number, add the drive's number on its controller and 128 if the drive is on the secondary controller. In the following device tables, n represents the drive number.

Warning: if you use formats with more tracks than supported by your drive, you may cause it mechanical damage. Trying once if more tracks than the usual 40/80 are supported should not damage it, but no warranty is given for that. If you are not sure, don't create device entries for those formats, so as to prevent their usage.

Drive-independent device files which automatically detect the media format and capacity:

Name

Base

minor #

fdn

0

5.25 inch double-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnd360

360

40

9

2

4

5.25 inch high-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnh360

360

40

9

2

20

fdnh410

410

41

10

2

48

fdnh420

420

42

10

2

64

fdnh720

720

80

9

2

24

fdnh880

880

80

11

2

80

fdnh1200

1200

80

15

2

8

fdnh1440

1440

80

18

2

40

fdnh1476

1476

82

18

2

56

fdnh1494

1494

83

18

2

72

fdnh1600

1600

80

20

2

92

3.5 inch double-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnu360

360

80

9

1

12

fdnu720

720

80

9

2

16

fdnu800

800

80

10

2

120

fdnu1040

1040

80

13

2

84

fdnu1120

1120

80

14

2

88

3.5 inch high-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnu360

360

40

9

2

12

fdnu720

720

80

9

2

16

fdnu820

820

82

10

2

52

fdnu830

830

83

10

2

68

fdnu1440

1440

80

18

2

28

fdnu1600

1600

80

20

2

124

fdnu1680

1680

80

21

2

44

fdnu1722

1722

82

21

2

60

fdnu1743

1743

83

21

2

76

fdnu1760

1760

80

22

2

96

fdnu1840

1840

80

23

2

116

fdnu1920

1920

80

24

2

100

3.5 inch extra-density device files:

Name

Capacity

Cyl.

Sect.

Heads

Base

KiB

minor #

fdnu2880

2880

80

36

2

32

fdnCompaQ

2880

80

36

2

36

fdnu3200

3200

80

40

2

104

fdnu3520

3520

80

44

2

108

fdnu3840

3840

80

48

2

112

## DESCRIPTION
fd special files access the floppy disk drives in raw mode. The following ioctl(2) calls are supported by fd devices:

FDCLRPRM

clears the media information of a drive (geometry of disk in drive).

FDSETPRM

sets the media information of a drive. The media information will be lost when the media is changed.

FDDEFPRM

sets the media information of a drive (geometry of disk in drive). The media information will not be lost when the media is changed. This will disable autodetection. In order to reenable autodetection, you have to issue an FDCLRPRM.

FDGETDRVTYP

returns the type of a drive (name parameter). For formats which work in several drive types, FDGETDRVTYP returns a name which is appropriate for the oldest drive type which supports this format.

FDFLUSH

invalidates the buffer cache for the given drive.

FDSETMAXERRS

sets the error thresholds for reporting errors, aborting the operation, recalibrating, resetting, and reading sector by sector.

FDSETMAXERRS

gets the current error thresholds.

FDGETDRVTYP

gets the internal name of the drive.

FDWERRORCLR

clears the write error statistics.

FDWERRORGET

reads the write error statistics. These include the total number of write errors, the location and disk of the first write error, and the location and disk of the last write error. Disks are identified by a generation number which is incremented at (almost) each disk change.

FDTWADDLE

Switch the drive motor off for a few microseconds. This might be needed in order to access a disk whose sectors are too close together.

FDSETDRVPRM

sets various drive parameters.

FDGETDRVPRM

reads these parameters back.

FDGETDRVSTAT

gets the cached drive state (disk changed, write protected et al.)

FDPOLLDRVSTAT

polls the drive and return its state.

FDGETFDCSTAT

gets the floppy controller state.

FDRESET

resets the floppy controller under certain conditions.

FDRAWCMD

sends a raw command to the floppy controller.

For more precise information, consult also the <linux/fd.h> and <linux/fdreg.h> include files, as well as the floppycontrol(1) manual page.

## FILES
/dev/fd*

## NOTES
The various formats permit reading and writing many types of disks. However, if a floppy is formatted with an inter-sector gap that is too small, performance may drop, to the point of needing a few seconds to access an entire track. To prevent this, use interleaved formats.

It is not possible to read floppies which are formatted using GCR (group code recording), which is used by Apple II and Macintosh computers (800k disks).

Reading floppies which are hard sectored (one hole per sector, with the index hole being a little skewed) is not supported. This used to be common with older 8-inch floppies.

## SEE ALSO
chown(1), floppycontrol(1), getfdprm(1), mknod(1), superformat(1), mount(8), setfdprm(8)


full

package: man-pages

title: full(4)

summary: always full device

text:
# full(4)

## NAME
full - always full device

## CONFIGURATION
If your system does not have /dev/full created already, it can be created with the following commands:

```
mknod -m 666 /dev/full c 1 7
chown root:root /dev/full
```

## DESCRIPTION
The file /dev/full has major device number 1 and minor device number 7.

Writes to the /dev/full device fail with an ENOSPC error. This can be used to test how a program handles disk-full errors.

Reads from the /dev/full device will return \0 characters.

Seeks on /dev/full will always succeed.

## FILES
/dev/full

## SEE ALSO
mknod(1), null(4), zero(4)


fuse

title: fuse(4)

summary: Filesystem in Userspace (FUSE) device

text:
# fuse(4)

## NAME
fuse - Filesystem in Userspace (FUSE) device

## SYNOPSIS

```
#include <linux/fuse.h>
```

## DESCRIPTION
This device is the primary interface between the FUSE filesystem driver and a user-space process wishing to provide the filesystem (referred to in the rest of this manual page as the filesystem daemon). This manual page is intended for those interested in understanding the kernel interface itself. Those implementing a FUSE filesystem may wish to make use of a user-space library such as libfuse that abstracts away the low-level interface.

At its core, FUSE is a simple client-server protocol, in which the Linux kernel is the client and the daemon is the server. After obtaining a file descriptor for this device, the daemon may read(2) requests from that file descriptor and is expected to write(2) back its replies. It is important to note that a file descriptor is associated with a unique FUSE filesystem. In particular, opening a second copy of this device, will not allow access to resources created through the first file descriptor (and vice versa).

### The basic protocol
Every message that is read by the daemon begins with a header described by the following structure:

```
struct fuse_in_header {

    uint32_t len;       /* Total length of the data,

                           including this header */

    uint32_t opcode;    /* The kind of operation (see below) */

    uint64_t unique;    /* A unique identifier for this request */

    uint64_t nodeid;    /* ID of the filesystem object

                           being operated on */

    uint32_t uid;       /* UID of the requesting process */

    uint32_t gid;       /* GID of the requesting process */

    uint32_t pid;       /* PID of the requesting process */

    uint32_t padding;
};
```

The header is followed by a variable-length data portion (which may be empty) specific to the requested operation (the requested operation is indicated by opcode).

The daemon should then process the request and if applicable send a reply (almost all operations require a reply; if they do not, this is documented below), by performing a write(2) to the file descriptor. All replies must start with the following header:

```
struct fuse_out_header {

    uint32_t len;       /* Total length of data written to

                           the file descriptor */

    int32_t  error;     /* Any error that occurred (0 if none) */

    uint64_t unique;    /* The value from the

                           corresponding request */
};
```

This header is also followed by (potentially empty) variable-sized data depending on the executed request. However, if the reply is an error reply (i.e., error is set), then no further payload data should be sent, independent of the request.

### Exchanged messages
This section should contain documentation for each of the messages in the protocol. This manual page is currently incomplete, so not all messages are documented. For each message, first the struct sent by the kernel is given, followed by a description of the semantics of the message.

FUSE_INIT

```
struct fuse_init_in {

    uint32_t major;

    uint32_t minor;

    uint32_t max_readahead; /* Since protocol v7.6 */

    uint32_t flags;         /* Since protocol v7.6 */
};

```

This is the first request sent by the kernel to the daemon. It is used to negotiate the protocol version and other filesystem parameters. Note that the protocol version may affect the layout of any structure in the protocol (including this structure). The daemon must thus remember the negotiated version and flags for each session. As of the writing of this man page, the highest supported kernel protocol version is 7.26.

Users should be aware that the descriptions in this manual page may be incomplete or incorrect for older or more recent protocol versions.

The reply for this request has the following format:

```
struct fuse_init_out {

    uint32_t major;

    uint32_t minor;

    uint32_t max_readahead;   /* Since v7.6 */

    uint32_t flags;           /* Since v7.6; some flags bits

                                 were introduced later */

    uint16_t max_background;  /* Since v7.13 */

    uint16_t congestion_threshold;  /* Since v7.13 */

    uint32_t max_write;       /* Since v7.5 */

    uint32_t time_gran;       /* Since v7.6 */

    uint32_t unused[9];
};

```

If the major version supported by the kernel is larger than that supported by the daemon, the reply shall consist of only uint32_t major (following the usual header), indicating the largest major version supported by the daemon. The kernel will then issue a new FUSE_INIT request conforming to the older version. In the reverse case, the daemon should quietly fall back to the kernel's major version.

The negotiated minor version is considered to be the minimum of the minor versions provided by the daemon and the kernel and both parties should use the protocol corresponding to said minor version.

FUSE_GETATTR

```
struct fuse_getattr_in {

    uint32_t getattr_flags;

    uint32_t dummy;

    uint64_t fh;      /* Set only if

                         (getattr_flags & FUSE_GETATTR_FH)
};

```

The requested operation is to compute the attributes to be returned by stat(2) and similar operations for the given filesystem object. The object for which the attributes should be computed is indicated either by header->nodeid or, if the FUSE_GETATTR_FH flag is set, by the file handle fh. The latter case of operation is analogous to fstat(2).

For performance reasons, these attributes may be cached in the kernel for a specified duration of time. While the cache timeout has not been exceeded, the attributes will be served from the cache and will not cause additional FUSE_GETATTR requests.

The computed attributes and the requested cache timeout should then be returned in the following structure:

```
struct fuse_attr_out {

    /* Attribute cache duration (seconds + nanoseconds) */

    uint64_t attr_valid;

    uint32_t attr_valid_nsec;

    uint32_t dummy;

    struct fuse_attr {

        uint64_t ino;

        uint64_t size;

        uint64_t blocks;

        uint64_t atime;

        uint64_t mtime;

        uint64_t ctime;

        uint32_t atimensec;

        uint32_t mtimensec;

        uint32_t ctimensec;

        uint32_t mode;

        uint32_t nlink;

        uint32_t uid;

        uint32_t gid;

        uint32_t rdev;

        uint32_t blksize;

        uint32_t padding;

    } attr;
};

```

FUSE_ACCESS

```
struct fuse_access_in {

    uint32_t mask;

    uint32_t padding;
};

```

If the default_permissions mount options is not used, this request may be used for permissions checking. No reply data is expected, but errors may be indicated as usual by setting the error field in the reply header (in particular, access denied errors may be indicated by returning -EACCES).

FUSE_OPEN and FUSE_OPENDIR

```
struct fuse_open_in {

    uint32_t flags;     /* The flags that were passed

                           to the open(2) */

    uint32_t unused;
};

```

The requested operation is to open the node indicated by header->nodeid. The exact semantics of what this means will depend on the filesystem being implemented. However, at the very least the filesystem should validate that the requested flags are valid for the indicated resource and then send a reply with the following format:

```
struct fuse_open_out {

    uint64_t fh;

    uint32_t open_flags;

    uint32_t padding;
};

```

The fh field is an opaque identifier that the kernel will use to refer to this resource The open_flags field is a bit mask of any number of the flags that indicate properties of this file handle to the kernel:

FOPEN_DIRECT_IO

Bypass page cache for this open file.

FOPEN_KEEP_CACHE

Don't invalidate the data cache on open.

FOPEN_NONSEEKABLE

The file is not seekable.

FUSE_READ and FUSE_READDIR

```
struct fuse_read_in {

    uint64_t fh;

    uint64_t offset;

    uint32_t size;

    uint32_t read_flags;

    uint64_t lock_owner;

    uint32_t flags;

    uint32_t padding;
};

```

The requested action is to read up to size bytes of the file or directory, starting at offset. The bytes should be returned directly following the usual reply header.

FUSE_INTERRUPT

```
struct fuse_interrupt_in {

    uint64_t unique;
};

```

The requested action is to cancel the pending operation indicated by unique. This request requires no response. However, receipt of this message does not by itself cancel the indicated operation. The kernel will still expect a reply to said operation (e.g., an EINTR error or a short read). At most one FUSE_INTERRUPT request will be issued for a given operation. After issuing said operation, the kernel will wait uninterruptibly for completion of the indicated request.

FUSE_LOOKUP

Directly following the header is a filename to be looked up in the directory indicated by header->nodeid. The expected reply is of the form:

```
struct fuse_entry_out {

    uint64_t nodeid;            /* Inode ID */

    uint64_t generation;        /* Inode generation */

    uint64_t entry_valid;

    uint64_t attr_valid;

    uint32_t entry_valid_nsec;

    uint32_t attr_valid_nsec;

    struct fuse_attr attr;
};

```

The combination of nodeid and generation must be unique for the filesystem's lifetime.

The interpretation of timeouts and attr is as for FUSE_GETATTR.

FUSE_FLUSH

```
struct fuse_flush_in {

    uint64_t fh;

    uint32_t unused;

    uint32_t padding;

    uint64_t lock_owner;
};

```

The requested action is to flush any pending changes to the indicated file handle. No reply data is expected. However, an empty reply message still needs to be issued once the flush operation is complete.

FUSE_RELEASE and FUSE_RELEASEDIR

```
struct fuse_release_in {

    uint64_t fh;

    uint32_t flags;

    uint32_t release_flags;

    uint64_t lock_owner;
};

```

These are the converse of FUSE_OPEN and FUSE_OPENDIR respectively. The daemon may now free any resources associated with the file handle fh as the kernel will no longer refer to it. There is no reply data associated with this request, but a reply still needs to be issued once the request has been completely processed.

FUSE_STATFS

This operation implements statfs(2) for this filesystem. There is no input data associated with this request. The expected reply data has the following structure:

```
struct fuse_kstatfs {

    uint64_t blocks;

    uint64_t bfree;

    uint64_t bavail;

    uint64_t files;

    uint64_t ffree;

    uint32_t bsize;

    uint32_t namelen;

    uint32_t frsize;

    uint32_t padding;

    uint32_t spare[6];
};
struct fuse_statfs_out {

    struct fuse_kstatfs st;
};

```

For the interpretation of these fields, see statfs(2).

## ERRORS
E2BIG

Returned from read(2) operations when the kernel's request is too large for the provided buffer and the request was FUSE_SETXATTR.

EINVAL

Returned from write(2) if validation of the reply failed. Not all mistakes in replies will be caught by this validation. However, basic mistakes, such as short replies or an incorrect unique value, are detected.

EIO

Returned from read(2) operations when the kernel's request is too large for the provided buffer.

Note: There are various ways in which incorrect use of these interfaces can cause operations on the provided filesystem's files and directories to fail with EIO. Among the possible incorrect uses are:

- changing mode & S_IFMT for an inode that has previously been reported to the kernel; or

- giving replies to the kernel that are shorter than what the kernel expected.

ENODEV

Returned from read(2) and write(2) if the FUSE filesystem was unmounted.

EPERM

Returned from operations on a /dev/fuse file descriptor that has not been mounted.

## CONFORMING TO
The FUSE filesystem is Linux-specific.

## NOTES
The following messages are not yet documented in this manual page:

```
FUSE_BATCH_FORGET
FUSE_BMAP
FUSE_CREATE
FUSE_DESTROY
FUSE_FALLOCATE
FUSE_FORGET
FUSE_FSYNC
FUSE_FSYNCDIR
FUSE_GETLK
FUSE_GETXATTR
FUSE_IOCTL
FUSE_LINK
FUSE_LISTXATTR
FUSE_LSEEK
FUSE_MKDIR
FUSE_MKNOD
FUSE_NOTIFY_REPLY
FUSE_POLL
FUSE_READDIRPLUS
FUSE_READLINK
FUSE_REMOVEXATTR
FUSE_RENAME
FUSE_RENAME2
FUSE_RMDIR
FUSE_SETATTR
FUSE_SETLK
FUSE_SETLKW
FUSE_SYMLINK
FUSE_UNLINK
FUSE_WRITE
```

## SEE ALSO
fusermount(1), mount.fuse(8)


hd

title: hd(4)

summary: MFM/IDE hard disk devices

text:
# hd(4)

## NAME
hd - MFM/IDE hard disk devices

## DESCRIPTION
The hd* devices are block devices to access MFM/IDE hard disk drives in raw mode. The master drive on the primary IDE controller (major device number 3) is hda; the slave drive is hdb. The master drive of the second controller (major device number 22) is hdc and the slave is hdd.

General IDE block device names have the form hdX, or hdXP, where X is a letter denoting the physical drive, and P is a number denoting the partition on that physical drive. The first form, hdX, is used to address the whole drive. Partition numbers are assigned in the order the partitions are discovered, and only nonempty, nonextended partitions get a number. However, partition numbers 1–4 are given to the four partitions described in the MBR (the "primary" partitions), regardless of whether they are unused or extended. Thus, the first logical partition will be hdX5. Both DOS-type partitioning and BSD-disklabel partitioning are supported. You can have at most 63 partitions on an IDE disk.

For example, /dev/hda refers to all of the first IDE drive in the system; and /dev/hdb3 refers to the third DOS "primary" partition on the second one.

They are typically created by:

```
mknod -m 660 /dev/hda b 3 0
mknod -m 660 /dev/hda1 b 3 1
mknod -m 660 /dev/hda2 b 3 2
...
mknod -m 660 /dev/hda8 b 3 8
mknod -m 660 /dev/hdb b 3 64
mknod -m 660 /dev/hdb1 b 3 65
mknod -m 660 /dev/hdb2 b 3 66
...
mknod -m 660 /dev/hdb8 b 3 72
chown root:disk /dev/hd*
```

## FILES
/dev/hd*

## SEE ALSO
chown(1), mknod(1), sd(4), mount(8)


hpsa

title: hpsa(4)

summary: HP Smart Array SCSI driver

text:
# hpsa(4)

## NAME
hpsa - HP Smart Array SCSI driver

## SYNOPSIS

```
modprobe hpsa [ hpsa_allow_any=1 ]
```

## DESCRIPTION
hpsa is a SCSI driver for HP Smart Array RAID controllers.

### Options
hpsa_allow_any=1: This option allows the driver to attempt to operate on any HP Smart Array hardware RAID controller, even if it is not explicitly known to the driver. This allows newer hardware to work with older drivers. Typically this is used to allow installation of operating systems from media that predates the RAID controller, though it may also be used to enable hpsa to drive older controllers that would normally be handled by the cciss(4) driver. These older boards have not been tested and are not supported with hpsa, and cciss(4) should still be used for these.

### Supported hardware
The hpsa driver supports the following Smart Array boards:

```
    Smart Array P700M

    Smart Array P212

    Smart Array P410

    Smart Array P410i

    Smart Array P411

    Smart Array P812

    Smart Array P712m

    Smart Array P711m

    StorageWorks P1210m
```

Since Linux 4.14, the following Smart Array boards are also supported:

```
    Smart Array 5300

    Smart Array 5312

    Smart Array 532

    Smart Array 5i

    Smart Array 6400

    Smart Array 6400 EM

    Smart Array 641

    Smart Array 642

    Smart Array 6i

    Smart Array E200

    Smart Array E200i

    Smart Array E200i

    Smart Array E200i

    Smart Array E200i

    Smart Array E500

    Smart Array P400

    Smart Array P400i

    Smart Array P600

    Smart Array P700m

    Smart Array P800
```

### Configuration details
To configure HP Smart Array controllers, use the HP Array Configuration Utility (either hpacuxe(8) or hpacucli(8)) or the Offline ROM-based Configuration Utility (ORCA) run from the Smart Array's option ROM at boot time.

## FILES

### Device nodes
Logical drives are accessed via the SCSI disk driver (sd(4)), tape drives via the SCSI tape driver (st(4)), and the RAID controller via the SCSI generic driver (sg(4)), with device nodes named /dev/sd*, /dev/st*, and /dev/sg*, respectively.

### HPSA-specific host attribute files in /sys
/sys/class/scsi_host/host*/rescan

This is a write-only attribute. Writing to this attribute will cause the driver to scan for new, changed, or removed devices (e.g., hot-plugged tape drives, or newly configured or deleted logical drives, etc.) and notify the SCSI midlayer of any changes detected. Normally a rescan is triggered automatically by HP's Array Configuration Utility (either the GUI or the command-line variety); thus, for logical drive changes, the user should not normally have to use this attribute. This attribute may be useful when hot plugging devices like tape drives, or entire storage boxes containing preconfigured logical drives.

/sys/class/scsi_host/host*/firmware_revision

This attribute contains the firmware version of the Smart Array.

For example:

```
# cd /sys/class/scsi_host/host4
# cat firmware_revision
7.14

```

### HPSA-specific disk attribute files in /sys
/sys/class/scsi_disk/c:b:t:l/device/unique_id

This attribute contains a 32 hex-digit unique ID for each logical drive.

For example:

```
# cd /sys/class/scsi_disk/4:0:0:0/device
# cat unique_id
600508B1001044395355323037570F77

```

/sys/class/scsi_disk/c:b:t:l/device/raid_level

This attribute contains the RAID level of each logical drive.

For example:

```
# cd /sys/class/scsi_disk/4:0:0:0/device
# cat raid_level
RAID 0

```

/sys/class/scsi_disk/c:b:t:l/device/lunid

This attribute contains the 16 hex-digit (8 byte) LUN ID by which a logical drive or physical device can be addressed. c:b:t:l are the controller, bus, target, and lun of the device.

For example:

```
# cd /sys/class/scsi_disk/4:0:0:0/device
# cat lunid
0x0000004000000000

```

### Supported ioctl() operations
For compatibility with applications written for the cciss(4) driver, many, but not all of the ioctls supported by the cciss(4) driver are also supported by the hpsa driver. The data structures used by these ioctls are described in the Linux kernel source file include/linux/cciss_ioctl.h.

CCISS_DEREGDISK, CCISS_REGNEWDISK, CCISS_REGNEWD

These three ioctls all do exactly the same thing, which is to cause the driver to rescan for new devices. This does exactly the same thing as writing to the hpsa-specific host "rescan" attribute.

CCISS_GETPCIINFO

Returns PCI domain, bus, device, and function and "board ID" (PCI subsystem ID).

CCISS_GETDRIVVER

Returns driver version in three bytes encoded as:

```
(major_version << 16) | (minor_version << 8) |

    (subminor_version)

```

CCISS_PASSTHRU, CCISS_BIG_PASSTHRU

Allows "BMIC" and "CISS" commands to be passed through to the Smart Array. These are used extensively by the HP Array Configuration Utility, SNMP storage agents, and so on. See cciss_vol_status at http://cciss.sf.net for some examples.

## SEE ALSO
cciss(4), sd(4), st(4), cciss_vol_status(8), hpacucli(8), hpacuxe(8),

http://cciss.sf.net, and Documentation/scsi/hpsa.txt and Documentation/ABI/testing/sysfs-bus-pci-devices-cciss in the Linux kernel source tree


initrd

title: initrd(4)

summary: boot loader initialized RAM disk

text:
# initrd(4)

## NAME
initrd - boot loader initialized RAM disk

## CONFIGURATION
/dev/initrd is a read-only block device assigned major number 1 and minor number 250. Typically /dev/initrd is owned by root:disk with mode 0400 (read access by root only). If the Linux system does not have /dev/initrd already created, it can be created with the following commands:

```
mknod -m 400 /dev/initrd b 1 250
chown root:disk /dev/initrd
```

Also, support for both "RAM disk" and "Initial RAM disk" (e.g., CONFIG_BLK_DEV_RAM=y and CONFIG_BLK_DEV_INITRD=y) must be compiled directly into the Linux kernel to use /dev/initrd. When using /dev/initrd, the RAM disk driver cannot be loaded as a module.

## DESCRIPTION
The special file /dev/initrd is a read-only block device. This device is a RAM disk that is initialized (e.g., loaded) by the boot loader before the kernel is started. The kernel then can use /dev/initrd's contents for a two-phase system boot-up.

In the first boot-up phase, the kernel starts up and mounts an initial root filesystem from the contents of /dev/initrd (e.g., RAM disk initialized by the boot loader). In the second phase, additional drivers or other modules are loaded from the initial root device's contents. After loading the additional modules, a new root filesystem (i.e., the normal root filesystem) is mounted from a different device.

### Boot-up operation
When booting up with initrd, the system boots as follows:

1.

The boot loader loads the kernel program and /dev/initrd's contents into memory.

2.

On kernel startup, the kernel uncompresses and copies the contents of the device /dev/initrd onto device /dev/ram0 and then frees the memory used by /dev/initrd.

3.

The kernel then read-write mounts the device /dev/ram0 as the initial root filesystem.

4.

If the indicated normal root filesystem is also the initial root filesystem (e.g., /dev/ram0) then the kernel skips to the last step for the usual boot sequence.

5.

If the executable file /linuxrc is present in the initial root filesystem, /linuxrc is executed with UID 0. (The file /linuxrc must have executable permission. The file /linuxrc can be any valid executable, including a shell script.)

6.

If /linuxrc is not executed or when /linuxrc terminates, the normal root filesystem is mounted. (If /linuxrc exits with any filesystems mounted on the initial root filesystem, then the behavior of the kernel is UNSPECIFIED. See the NOTES section for the current kernel behavior.)

7.

If the normal root filesystem has a directory /initrd, the device /dev/ram0 is moved from / to /initrd. Otherwise, if the directory /initrd does not exist, the device /dev/ram0 is unmounted. (When moved from / to /initrd, /dev/ram0 is not unmounted and therefore processes can remain running from /dev/ram0. If directory /initrd does not exist on the normal root filesystem and any processes remain running from /dev/ram0 when /linuxrc exits, the behavior of the kernel is UNSPECIFIED. See the NOTES section for the current kernel behavior.)

8.

The usual boot sequence (e.g., invocation of /sbin/init) is performed on the normal root filesystem.

### Options
The following boot loader options, when used with initrd, affect the kernel's boot-up operation:

initrd=filename

Specifies the file to load as the contents of /dev/initrd. For LOADLIN this is a command-line option. For LILO you have to use this command in the LILO configuration file /etc/lilo.config. The filename specified with this option will typically be a gzipped filesystem image.

noinitrd

This boot option disables the two-phase boot-up operation. The kernel performs the usual boot sequence as if /dev/initrd was not initialized. With this option, any contents of /dev/initrd loaded into memory by the boot loader contents are preserved. This option permits the contents of /dev/initrd to be any data and need not be limited to a filesystem image. However, device /dev/initrd is read-only and can be read only one time after system startup.

root=device-name

Specifies the device to be used as the normal root filesystem. For LOADLIN this is a command-line option. For LILO this is a boot time option or can be used as an option line in the LILO configuration file /etc/lilo.config. The device specified by this option must be a mountable device having a suitable root filesystem.

### Changing the normal root filesystem
By default, the kernel's settings (e.g., set in the kernel file with rdev(8) or compiled into the kernel file), or the boot loader option setting is used for the normal root filesystems. For an NFS-mounted normal root filesystem, one has to use the nfs_root_name and nfs_root_addrs boot options to give the NFS settings. For more information on NFS-mounted root see the kernel documentation file Documentation/filesystems/nfs/nfsroot.txt (or Documentation/filesystems/nfsroot.txt before Linux 2.6.33). For more information on setting the root filesystem see also the LILO and LOADLIN documentation.

It is also possible for the /linuxrc executable to change the normal root device. For /linuxrc to change the normal root device, /proc must be mounted. After mounting /proc, /linuxrc changes the normal root device by writing into the proc files /proc/sys/kernel/real-root-dev, /proc/sys/kernel/nfs-root-name, and /proc/sys/kernel/nfs-root-addrs. For a physical root device, the root device is changed by having /linuxrc write the new root filesystem device number into /proc/sys/kernel/real-root-dev. For an NFS root filesystem, the root device is changed by having /linuxrc write the NFS setting into files /proc/sys/kernel/nfs-root-name and /proc/sys/kernel/nfs-root-addrs and then writing 0xff (e.g., the pseudo-NFS-device number) into file /proc/sys/kernel/real-root-dev. For example, the following shell command line would change the normal root device to /dev/hdb1:

```
echo 0x365 >/proc/sys/kernel/real-root-dev
```

For an NFS example, the following shell command lines would change the normal root device to the NFS directory /var/nfsroot on a local networked NFS server with IP number 193.8.232.7 for a system with IP number 193.8.232.2 and named "idefix":

```
echo /var/nfsroot >/proc/sys/kernel/nfs-root-name
echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \

    >/proc/sys/kernel/nfs-root-addrs
echo 255 >/proc/sys/kernel/real-root-dev
```

Note: The use of /proc/sys/kernel/real-root-dev to change the root filesystem is obsolete. See the Linux kernel source file Documentation/admin-guide/initrd.rst (or Documentation/initrd.txt before Linux 4.10) as well as pivot_root(2) and pivot_root(8) for information on the modern method of changing the root filesystem.

### Usage
The main motivation for implementing initrd was to allow for modular kernel configuration at system installation.

A possible system installation scenario is as follows:

1.

The loader program boots from floppy or other media with a minimal kernel (e.g., support for /dev/ram, /dev/initrd, and the ext2 filesystem) and loads /dev/initrd with a gzipped version of the initial filesystem.

2.

The executable /linuxrc determines what is needed to (1) mount the normal root filesystem (i.e., device type, device drivers, filesystem) and (2) the distribution media (e.g., CD-ROM, network, tape, ...). This can be done by asking the user, by auto-probing, or by using a hybrid approach.

3.

The executable /linuxrc loads the necessary modules from the initial root filesystem.

4.

The executable /linuxrc creates and populates the root filesystem. (At this stage the normal root filesystem does not have to be a completed system yet.)

5.

The executable /linuxrc sets /proc/sys/kernel/real-root-dev, unmounts /proc, the normal root filesystem and any other filesystems it has mounted, and then terminates.

6.

The kernel then mounts the normal root filesystem.

7.

Now that the filesystem is accessible and intact, the boot loader can be installed.

8.

The boot loader is configured to load into /dev/initrd a filesystem with the set of modules that was used to bring up the system. (e.g., device /dev/ram0 can be modified, then unmounted, and finally, the image is written from /dev/ram0 to a file.)

9.

The system is now bootable and additional installation tasks can be performed.

The key role of /dev/initrd in the above is to reuse the configuration data during normal system operation without requiring initial kernel selection, a large generic kernel or, recompiling the kernel.

A second scenario is for installations where Linux runs on systems with different hardware configurations in a single administrative network. In such cases, it may be desirable to use only a small set of kernels (ideally only one) and to keep the system-specific part of configuration information as small as possible. In this case, create a common file with all needed modules. Then, only the /linuxrc file or a file executed by /linuxrc would be different.

A third scenario is more convenient recovery disks. Because information like the location of the root filesystem partition is not needed at boot time, the system loaded from /dev/initrd can use a dialog and/or auto-detection followed by a possible sanity check.

Last but not least, Linux distributions on CD-ROM may use initrd for easy installation from the CD-ROM. The distribution can use LOADLIN to directly load /dev/initrd from CD-ROM without the need of any floppies. The distribution could also use a LILO boot floppy and then bootstrap a bigger RAM disk via /dev/initrd from the CD-ROM.

## FILES
/dev/initrd

/dev/ram0

/linuxrc

/initrd

## NOTES
1.

With the current kernel, any filesystems that remain mounted when /dev/ram0 is moved from / to /initrd continue to be accessible. However, the /proc/mounts entries are not updated.

2.

With the current kernel, if directory /initrd does not exist, then /dev/ram0 will not be fully unmounted if /dev/ram0 is used by any process or has any filesystem mounted on it. If /dev/ram0 is not fully unmounted, then /dev/ram0 will remain in memory.

3.

Users of /dev/initrd should not depend on the behavior given in the above notes. The behavior may change in future versions of the Linux kernel.

## SEE ALSO
chown(1), mknod(1), ram(4), freeramdisk(8), rdev(8)

Documentation/admin-guide/initrd.rst (or Documentation/initrd.txt before Linux 4.10) in the Linux kernel source tree, the LILO documentation, the LOADLIN documentation, the SYSLINUX documentation


intro

title: intro(4)

summary: introduction to special files

text:
# intro(4)

## NAME
intro - introduction to special files

## DESCRIPTION
Section 4 of the manual describes special files (devices).

## FILES
/dev/* — device files

## NOTES

### Authors and copyright conditions
Look at the header of the manual page source for the author(s) and copyright conditions. Note that these can be different from page to page!

## SEE ALSO
mknod(1), mknod(2), standards(7)


lirc

title: lirc(4)

summary: lirc devices

text:
# lirc(4)

## NAME
lirc - lirc devices

## DESCRIPTION
The /dev/lirc* character devices provide a low-level bidirectional interface to infra-red (IR) remotes. Most of these devices can receive, and some can send. When receiving or sending data, the driver works in two different modes depending on the underlying hardware.

Some hardware (typically TV-cards) decodes the IR signal internally and provides decoded button presses as scancode values. Drivers for this kind of hardware work in LIRC_MODE_SCANCODE mode. Such hardware usually does not support sending IR signals. Furthermore, such hardware can only decode a limited set of IR protocols, usually only the protocol of the specific remote which is bundled with, for example, a TV-card.

Other hardware provides a stream of pulse/space durations. Such drivers work in LIRC_MODE_MODE2 mode. Sometimes, this kind of hardware also supports sending IR data. Such hardware can be used with (almost) any kind of remote. This type of hardware can also be used in LIRC_MODE_SCANCODE mode, in which case the kernel IR decoders will decode the IR. These decoders can be written in extended BPF (see bpf(2)) and attached to the lirc device.

The LIRC_GET_FEATURES ioctl (see below) allows probing for whether receiving and sending is supported, and in which modes, amongst other features.

### Reading input with the LIRC_MODE_MODE2 mode
In the LIRC_MODE_MODE2 mode, the data returned by read(2) provides 32-bit values representing a space or a pulse duration. The time of the duration (microseconds) is encoded in the lower 24 bits. The upper 8 bits indicate the type of package:

LIRC_MODE2_SPACE

Value reflects a space duration (microseconds).

LIRC_MODE2_PULSE

Value reflects a pulse duration (microseconds).

LIRC_MODE2_FREQUENCY

Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CARRIER_MODE ioctl.

LIRC_MODE2_TIMEOUT

Value reflects a space duration (microseconds). The package reflects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.

### Reading input with the LIRC_MODE_SCANCODE mode
In the LIRC_MODE_SCANCODE mode, the data returned by read(2) reflects decoded button presses, in the struct lirc_scancode. The scancode is stored in the scancode field, and the IR protocol is stored in rc_proto. This field has one the values of the enum rc_proto.

### Writing output with the LIRC_MODE_PULSE mode
The data written to the character device using write(2) is a pulse/space sequence of integer values. Pulses and spaces are only marked implicitly by their position. The data must start and end with a pulse, thus it must always include an odd number of samples. The write(2) function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the write(2) call fails with the error EINVAL.

### Writing output with the LIRC_MODE_SCANCODE mode
The data written to the character devices must be a single struct lirc_scancode. The scancode and rc_proto fields must filled in, all other fields must be 0. The kernel IR encoders will convert the scancode to pulses and spaces. The protocol or scancode is invalid, or the lirc device cannot transmit.

## IOCTL COMMANDS
The LIRC device's ioctl definition is bound by the ioctl function definition of struct file_operations, leaving us with an unsigned int for the ioctl command and an unsigned long for the argument. For the purposes of ioctl portability across 32-bit and 64-bit architectures, these values are capped to their 32-bit sizes.

```
#include <linux/lirc.h>    /* But see BUGS */
int ioctl(int fd, int cmd, ...);
```

The following ioctls can be used to probe or change specific lirc hardware settings. Many require a third argument, usually an int, referred to below as val.

### Always Supported Commands
/dev/lirc* devices always support the following commands:

LIRC_GET_FEATURES (void)

Returns a bit mask of combined features bits; see FEATURES.

If a device returns an error code for LIRC_GET_FEATURES, it is safe to assume it is not a lirc device.

### Optional Commands
Some lirc devices support the commands listed below. Unless otherwise stated, these fail with the error ENOTTY if the operation isn't supported, or with the error EINVAL if the operation failed, or invalid arguments were provided. If a driver does not announce support of certain features, invoking the corresponding ioctls will fail with the error ENOTTY.

LIRC_GET_REC_MODE (void)

If the lirc device has no receiver, this operation fails with the error ENOTTY. Otherwise, it returns the receive mode, which will be one of:

LIRC_MODE_MODE2

The driver returns a sequence of pulse/space durations.

LIRC_MODE_SCANCODE

The driver returns struct lirc_scancode values, each of which represents a decoded button press.

LIRC_SET_REC_MODE (int)

Set the receive mode. val is either LIRC_MODE_SCANCODE or LIRC_MODE_MODE2. If the lirc device has no receiver, this operation fails with the error ENOTTY.

LIRC_GET_SEND_MODE (void)

Return the send mode. LIRC_MODE_PULSE or LIRC_MODE_SCANCODE is supported. If the lirc device cannot send, this operation fails with the error ENOTTY.

LIRC_SET_SEND_MODE (int)

Set the send mode. val is either LIRC_MODE_SCANCODE or LIRC_MODE_PULSE. If the lirc device cannot send, this operation fails with the error ENOTTY.

LIRC_SET_SEND_CARRIER (int)

Set the modulation frequency. The argument is the frequency (Hz).

LIRC_SET_SEND_DUTY_CYCLE (int)

Set the carrier duty cycle. val is a number in the range [0,100] which describes the pulse width as a percentage of the total cycle. Currently, no special meaning is defined for 0 or 100, but the values are reserved for future use.

LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)

Some devices have internal timers that can be used to detect when there has been no IR activity for a long time. This can help lircd(8) in detecting that an IR signal is finished and can speed up the decoding process. These operations return integer values with the minimum/maximum timeout that can be set (microseconds). Some devices have a fixed timeout. For such drivers, LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will fail with the error ENOTTY.

LIRC_SET_REC_TIMEOUT (int)

Set the integer value for IR inactivity timeout (microseconds). To be accepted, the value must be within the limits defined by LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT. A value of 0 (if supported by the hardware) disables all hardware timeouts and data should be reported as soon as possible. If the exact value cannot be set, then the next possible value greater than the given value should be set.

LIRC_GET_REC_TIMEOUT (void)

Return the current inactivity timeout (microseconds). Available since Linux 4.18.

LIRC_SET_REC_TIMEOUT_REPORTS (int)

Enable (val is 1) or disable (val is 0) timeout packages in LIRC_MODE_MODE2. The behavior of this operation has varied across kernel versions:

- Since Linux 4.16: each time the lirc device is opened, timeout reports are by default enabled for the resulting file descriptor. The LIRC_SET_REC_TIMEOUT operation can be used to disable (and, if desired, to later re-enable) the timeout on the file descriptor.

- In Linux 4.15 and earlier: timeout reports are disabled by default, and enabling them (via LIRC_SET_REC_TIMEOUT) on any file descriptor associated with the lirc device has the effect of enabling timeouts for all file descriptors referring to that device (until timeouts are disabled again).

LIRC_SET_REC_CARRIER (int)

Set the upper bound of the receive carrier frequency (Hz). See LIRC_SET_REC_CARRIER_RANGE.

LIRC_SET_REC_CARRIER_RANGE (int)

Sets the lower bound of the receive carrier frequency (Hz). For this to take affect, first set the lower bound using the LIRC_SET_REC_CARRIER_RANGE ioctl, and then the upper bound using the LIRC_SET_REC_CARRIER ioctl.

LIRC_SET_MEASURE_CARRIER_MODE (int)

Enable (val is 1) or disable (val is 0) the measure mode. If enabled, from the next key press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default, this should be turned off.

LIRC_GET_REC_RESOLUTION (void)

Return the driver resolution (microseconds).

LIRC_SET_TRANSMITTER_MASK (int)

Enable the set of transmitters specified in val, which contains a bit mask where each enabled transmitter is a 1. The first transmitter is encoded by the least significant bit, and so on. When an invalid bit mask is given, for example a bit is set even though the device does not have so many transmitters, this operation returns the number of available transmitters and does nothing otherwise.

LIRC_SET_WIDEBAND_RECEIVER (int)

Some devices are equipped with a special wide band receiver which is intended to be used to learn the output of an existing remote. This ioctl can be used to enable (val equals 1) or disable (val equals 0) this functionality. This might be useful for devices that otherwise have narrow band receivers that prevent them to be used with certain remotes. Wide band receivers may also be more precise. On the other hand, their disadvantage usually is reduced range of reception.

Note: wide band receiver may be implicitly enabled if you enable carrier reports. In that case, it will be disabled as soon as you disable carrier reports. Trying to disable a wide band receiver while carrier reports are active will do nothing.

## FEATURES
the LIRC_GET_FEATURES ioctl returns a bit mask describing features of the driver. The following bits may be returned in the mask:

LIRC_CAN_REC_MODE2

The driver is capable of receiving using LIRC_MODE_MODE2.

LIRC_CAN_REC_SCANCODE

The driver is capable of receiving using LIRC_MODE_SCANCODE.

LIRC_CAN_SET_SEND_CARRIER

The driver supports changing the modulation frequency using LIRC_SET_SEND_CARRIER.

LIRC_CAN_SET_SEND_DUTY_CYCLE

The driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.

LIRC_CAN_SET_TRANSMITTER_MASK

The driver supports changing the active transmitter(s) using LIRC_SET_TRANSMITTER_MASK.

LIRC_CAN_SET_REC_CARRIER

The driver supports setting the receive carrier frequency using LIRC_SET_REC_CARRIER. Any lirc device since the drivers were merged in kernel release 2.6.36 must have LIRC_CAN_SET_REC_CARRIER_RANGE set if LIRC_CAN_SET_REC_CARRIER feature is set.

LIRC_CAN_SET_REC_CARRIER_RANGE

The driver supports LIRC_SET_REC_CARRIER_RANGE. The lower bound of the carrier must first be set using the LIRC_SET_REC_CARRIER_RANGE ioctl, before using the LIRC_SET_REC_CARRIER ioctl to set the upper bound.

LIRC_CAN_GET_REC_RESOLUTION

The driver supports LIRC_GET_REC_RESOLUTION.

LIRC_CAN_SET_REC_TIMEOUT

The driver supports LIRC_SET_REC_TIMEOUT.

LIRC_CAN_MEASURE_CARRIER

The driver supports measuring of the modulation frequency using LIRC_SET_MEASURE_CARRIER_MODE.

LIRC_CAN_USE_WIDEBAND_RECEIVER

The driver supports learning mode using LIRC_SET_WIDEBAND_RECEIVER.

LIRC_CAN_SEND_PULSE

The driver supports sending using LIRC_MODE_PULSE or LIRC_MODE_SCANCODE

## BUGS
Using these devices requires the kernel source header file lirc.h. This file is not available before kernel release 4.6. Users of older kernels could use the file bundled in http://www.lirc.org.

## SEE ALSO
ir-ctl(1), lircd(8), bpf(2)

https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html


loop

title: loop(4)

summary: loop devices

text:
# loop(4)

## NAME
loop, loop-control - loop devices

## SYNOPSIS

```
#include <linux/loop.h>
```

## DESCRIPTION
The loop device is a block device that maps its data blocks not to a physical device such as a hard disk or optical disk drive, but to the blocks of a regular file in a filesystem or to another block device. This can be useful for example to provide a block device for a filesystem image stored in a file, so that it can be mounted with the mount(8) command. You could do

```
$ dd if=/dev/zero of=file.img bs=1MiB count=10
$ sudo losetup /dev/loop4 file.img
$ sudo mkfs -t ext4 /dev/loop4
$ sudo mkdir /myloopdev
$ sudo mount /dev/loop4 /myloopdev
```

See losetup(8) for another example.

A transfer function can be specified for each loop device for encryption and decryption purposes.

The following ioctl(2) operations are provided by the loop block device:

LOOP_SET_FD

Associate the loop device with the open file whose file descriptor is passed as the (third) ioctl(2) argument.

LOOP_CLR_FD

Disassociate the loop device from any file descriptor.

LOOP_SET_STATUS

Set the status of the loop device using the (third) ioctl(2) argument. This argument is a pointer to a loop_info structure, defined in <linux/loop.h> as:

```
struct loop_info {

    int           lo_number;      /* ioctl r/o */

    dev_t         lo_device;      /* ioctl r/o */

    unsigned long lo_inode;       /* ioctl r/o */

    dev_t         lo_rdevice;     /* ioctl r/o */

    int           lo_offset;

    int           lo_encrypt_type;

    int           lo_encrypt_key_size;  /* ioctl w/o */

    int           lo_flags;       /* ioctl r/w (r/o before

                                     Linux 2.6.25) */

    char          lo_name[LO_NAME_SIZE];

    unsigned char lo_encrypt_key[LO_KEY_SIZE];

                                  /* ioctl w/o */

    unsigned long lo_init[2];

    char          reserved[4];
};

```

The encryption type (lo_encrypt_type) should be one of LO_CRYPT_NONE, LO_CRYPT_XOR, LO_CRYPT_DES, LO_CRYPT_FISH2, LO_CRYPT_BLOW, LO_CRYPT_CAST128, LO_CRYPT_IDEA, LO_CRYPT_DUMMY, LO_CRYPT_SKIPJACK, or (since Linux 2.6.0) LO_CRYPT_CRYPTOAPI.

The lo_flags field is a bit mask that can include zero or more of the following:

LO_FLAGS_READ_ONLY

The loopback device is read-only.

LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)

The loopback device will autodestruct on last close.

LO_FLAGS_PARTSCAN (since Linux 3.2)

Allow automatic partition scanning.

LO_FLAGS_DIRECT_IO (since Linux 4.10)

Use direct I/O mode to access the backing file.

The only lo_flags that can be modified by LOOP_SET_STATUS are LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN.

LOOP_GET_STATUS

Get the status of the loop device. The (third) ioctl(2) argument must be a pointer to a struct loop_info.

LOOP_CHANGE_FD (since Linux 2.6.5)

Switch the backing store of the loop device to the new file identified file descriptor specified in the (third) ioctl(2) argument, which is an integer. This operation is possible only if the loop device is read-only and the new backing store is the same size and type as the old backing store.

LOOP_SET_CAPACITY (since Linux 2.6.30)

Resize a live loop device. One can change the size of the underlying backing store and then use this operation so that the loop driver learns about the new size. This operation takes no argument.

LOOP_SET_DIRECT_IO (since Linux 4.10)

Set DIRECT I/O mode on the loop device, so that it can be used to open backing file. The (third) ioctl(2) argument is an unsigned long value. A nonzero represents direct I/O mode.

LOOP_SET_BLOCK_SIZE (since Linux 4.14)

Set the block size of the loop device. The (third) ioctl(2) argument is an unsigned long value. This value must be a power of two in the range [512,pagesize]; otherwise, an EINVAL error results.

LOOP_CONFIGURE (since Linux 5.8)

Setup and configure all loop device parameters in a single step using the (third) ioctl(2) argument. This argument is a pointer to a loop_config structure, defined in <linux/loop.h> as:

```
struct loop_config {

    __u32               fd;

    __u32               block_size;

    struct loop_info64  info;

    __u64               __reserved[8];
};

```

In addition to doing what LOOP_SET_STATUS can do, LOOP_CONFIGURE can also be used to do the following:

- set the correct block size immediately by setting loop_config.block_size;

- explicitly request direct I/O mode by setting LO_FLAGS_DIRECT_IO in loop_config.info.lo_flags; and

- explicitly request read-only mode by setting LO_FLAGS_READ_ONLY in loop_config.info.lo_flags.

Since Linux 2.6, there are two new ioctl(2) operations:

LOOP_SET_STATUS64, LOOP_GET_STATUS64

These are similar to LOOP_SET_STATUS and LOOP_GET_STATUS described above but use the loop_info64 structure, which has some additional fields and a larger range for some other fields:

```
struct loop_info64 {

    uint64_t lo_device;           /* ioctl r/o */

    uint64_t lo_inode;            /* ioctl r/o */

    uint64_t lo_rdevice;          /* ioctl r/o */

    uint64_t lo_offset;

    uint64_t lo_sizelimit;  /* bytes, 0 == max available */

    uint32_t lo_number;           /* ioctl r/o */

    uint32_t lo_encrypt_type;

    uint32_t lo_encrypt_key_size; /* ioctl w/o */

    uint32_t lo_flags; i          /* ioctl r/w (r/o before

                                     Linux 2.6.25) */

    uint8_t  lo_file_name[LO_NAME_SIZE];

    uint8_t  lo_crypt_name[LO_NAME_SIZE];

    uint8_t  lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */

    uint64_t lo_init[2];
};

```

### /dev/loop-control
Since Linux 3.1, the kernel provides the /dev/loop-control device, which permits an application to dynamically find a free device, and to add and remove loop devices from the system. To perform these operations, one first opens /dev/loop-control and then employs one of the following ioctl(2) operations:

LOOP_CTL_GET_FREE

Allocate or find a free loop device for use. On success, the device number is returned as the result of the call. This operation takes no argument.

LOOP_CTL_ADD

Add the new loop device whose device number is specified as a long integer in the third ioctl(2) argument. On success, the device index is returned as the result of the call. If the device is already allocated, the call fails with the error EEXIST.

LOOP_CTL_REMOVE

Remove the loop device whose device number is specified as a long integer in the third ioctl(2) argument. On success, the device number is returned as the result of the call. If the device is in use, the call fails with the error EBUSY.

## FILES
/dev/loop*

The loop block special device files.

## EXAMPLES
The program below uses the /dev/loop-control device to find a free loop device, opens the loop device, opens a file to be used as the underlying storage for the device, and then associates the loop device with the backing store. The following shell session demonstrates the use of the program:

```
$ dd if=/dev/zero of=file.img bs=1MiB count=10
10+0 records in
10+0 records out
10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
$ sudo ./mnt_loop file.img
loopname = /dev/loop5
```

### Program source

```
#include <fcntl.h>
#include <linux/loop.h>
#include <sys/ioctl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \

                        } while (0)
int
main(int argc, char *argv[])
{

    int loopctlfd, loopfd, backingfile;

    long devnr;

    char loopname[4096];

    if (argc != 2) {

        fprintf(stderr, "Usage: %s backing-file\n", argv[0]);

        exit(EXIT_FAILURE);

    }

    loopctlfd = open("/dev/loop-control", O_RDWR);

    if (loopctlfd == -1)

        errExit("open: /dev/loop-control");

    devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);

    if (devnr == -1)

        errExit("ioctl-LOOP_CTL_GET_FREE");

    sprintf(loopname, "/dev/loop%ld", devnr);

    printf("loopname = %s\n", loopname);

    loopfd = open(loopname, O_RDWR);

    if (loopfd == -1)

        errExit("open: loopname");

    backingfile = open(argv[1], O_RDWR);

    if (backingfile == -1)

        errExit("open: backing-file");

    if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)

        errExit("ioctl-LOOP_SET_FD");

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
losetup(8), mount(8)


lp

title: lp(4)

summary: line printer devices

text:
# lp(4)

## NAME
lp - line printer devices

## SYNOPSIS

```
#include <linux/lp.h>
```

## CONFIGURATION
lp[0–2] are character devices for the parallel line printers; they have major number 6 and minor number 0–2. The minor numbers correspond to the printer port base addresses 0x03bc, 0x0378, and 0x0278. Usually they have mode 220 and are owned by user root and group lp. You can use printer ports either with polling or with interrupts. Interrupts are recommended when high traffic is expected, for example, for laser printers. For typical dot matrix printers, polling will usually be enough. The default is polling.

## DESCRIPTION
The following ioctl(2) calls are supported:

int ioctl(int fd, LPTIME, int arg)

Sets the amount of time that the driver sleeps before rechecking the printer when the printer's buffer appears to be filled to arg. If you have a fast printer, decrease this number; if you have a slow printer, then increase it. This is in hundredths of a second, the default 2 being 0.02 seconds. It influences only the polling driver.

int ioctl(int fd, LPCHAR, int arg)

Sets the maximum number of busy-wait iterations which the polling driver does while waiting for the printer to get ready for receiving a character to arg. If printing is too slow, increase this number; if the system gets too slow, decrease this number. The default is 1000. It influences only the polling driver.

int ioctl(int fd, LPABORT, int arg)

If arg is 0, the printer driver will retry on errors, otherwise it will abort. The default is 0.

int ioctl(int fd, LPABORTOPEN, int arg)

If arg is 0, open(2) will be aborted on error, otherwise error will be ignored. The default is to ignore it.

int ioctl(int fd, LPCAREFUL, int arg)

If arg is 0, then the out-of-paper, offline, and error signals are required to be false on all writes, otherwise they are ignored. The default is to ignore them.

int ioctl(int fd, LPWAIT, int arg)

Sets the number of busy waiting iterations to wait before strobing the printer to accept a just-written character, and the number of iterations to wait before turning the strobe off again, to arg. The specification says this time should be 0.5 microseconds, but experience has shown the delay caused by the code is already enough. For that reason, the default value is 0. This is used for both the polling and the interrupt driver.

int ioctl(int fd, LPSETIRQ, int arg)

This ioctl(2) requires superuser privileges. It takes an int containing the new IRQ as argument. As a side effect, the printer will be reset. When arg is 0, the polling driver will be used, which is also default.

int ioctl(int fd, LPGETIRQ, int *arg)

Stores the currently used IRQ in arg.

int ioctl(int fd, LPGETSTATUS, int *arg)

Stores the value of the status port in arg. The bits have the following meaning: LP_PBUSY

inverted busy input, active high

LP_PACK

unchanged acknowledge input, active low

LP_POUTPA

unchanged out-of-paper input, active high

LP_PSELECD

unchanged selected input, active high

LP_PERRORP

unchanged error input, active low

Refer to your printer manual for the meaning of the signals. Note that undocumented bits may also be set, depending on your printer.

int ioctl(int fd, LPRESET)

Resets the printer. No argument is used.

## FILES
/dev/lp*

## SEE ALSO
chmod(1), chown(1), mknod(1), lpcntl(8), tunelp(8)


mem

title: mem(4)

text:
# mem(4)

## NAME
mem, kmem, port - system memory, kernel memory and system ports

## DESCRIPTION
/dev/mem is a character device file that is an image of the main memory of the computer. It may be used, for example, to examine (and even patch) the system.

Byte addresses in /dev/mem are interpreted as physical memory addresses. References to nonexistent locations cause errors to be returned.

Examining and patching is likely to lead to unexpected results when read-only or write-only bits are present.

Since Linux 2.6.26, and depending on the architecture, the CONFIG_STRICT_DEVMEM kernel configuration option limits the areas which can be accessed through this file. For example: on x86, RAM access is not allowed but accessing memory-mapped PCI regions is.

It is typically created by:

```
mknod -m 660 /dev/mem c 1 1
chown root:kmem /dev/mem
```

The file /dev/kmem is the same as /dev/mem, except that the kernel virtual memory rather than physical memory is accessed. Since Linux 2.6.26, this file is available only if the CONFIG_DEVKMEM kernel configuration option is enabled.

It is typically created by:

```
mknod -m 640 /dev/kmem c 1 2
chown root:kmem /dev/kmem
```

/dev/port is similar to /dev/mem, but the I/O ports are accessed.

It is typically created by:

```
mknod -m 660 /dev/port c 1 4
chown root:kmem /dev/port
```

## FILES
/dev/mem

/dev/kmem

/dev/port

## SEE ALSO
chown(1), mknod(1), ioperm(2)


mouse

title: mouse(4)

summary: serial mouse interface

text:
# mouse(4)

## NAME
mouse - serial mouse interface

## CONFIGURATION
Serial mice are connected to a serial RS232/V24 dialout line, see ttyS(4) for a description.

## DESCRIPTION

### Introduction
The pinout of the usual 9 pin plug as used for serial mice is:

pin

name

used for

2

RX

Data

3

TX

-12 V, Imax = 10 mA

4

DTR

+12 V, Imax = 10 mA

7

RTS

+12 V, Imax = 10 mA

5

GND

Ground

This is the specification, in fact 9 V suffices with most mice.

The mouse driver can recognize a mouse by dropping RTS to low and raising it again. About 14 ms later the mouse will send 0x4D ('M') on the data line. After a further 63 ms, a Microsoft-compatible 3-button mouse will send 0x33 ('3').

The relative mouse movement is sent as dx (positive means right) and dy (positive means down). Various mice can operate at different speeds. To select speeds, cycle through the speeds 9600, 4800, 2400, and 1200 bit/s, each time writing the two characters from the table below and waiting 0.1 seconds. The following table shows available speeds and the strings that select them:

bit/s

string

9600

*q

4800

*p

2400

*o

1200

*n

The first byte of a data packet can be used for synchronization purposes.

### Microsoft protocol
The Microsoft protocol uses 1 start bit, 7 data bits, no parity and one stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 3-byte packets. The dx and dy movements are sent as two's-complement, lb (rb) are set when the left (right) button is pressed:

byte

d6

d5

d4

d3

d2

d1

d0

1

1

lb

rb

dy7

dy6

dx7

dx6

2

0

dx5

dx4

dx3

dx2

dx1

dx0

3

0

dy5

dy4

dy3

dy2

dy1

dy0

### 3-button Microsoft protocol
Original Microsoft mice only have two buttons. However, there are some three button mice which also use the Microsoft protocol. Pressing or releasing the middle button is reported by sending a packet with zero movement and no buttons pressed. (Thus, unlike for the other two buttons, the status of the middle button is not reported in each packet.)

### Logitech protocol
Logitech serial 3-button mice use a different extension of the Microsoft protocol: when the middle button is up, the above 3-byte packet is sent. When the middle button is down a 4-byte packet is sent, where the 4th byte has value 0x20 (or at least has the 0x20 bit set). In particular, a press of the middle button is reported as 0,0,0,0x20 when no other buttons are down.

### Mousesystems protocol
The Mousesystems protocol uses 1 start bit, 8 data bits, no parity, and two stop bits at the speed of 1200 bits/sec. Data is sent to RxD in 5-byte packets. dx is sent as the sum of the two two's-complement values, dy is send as negated sum of the two two's-complement values. lb (mb, rb) are cleared when the left (middle, right) button is pressed:

byte

d7

d6

d5

d4

d3

d2

d1

d0

1

1

0

0

0

0

lb

mb

rb

2

0

dxa6

dxa5

dxa4

dxa3

dxa2

dxa1

dxa0

3

0

dya6

dya5

dya4

dya3

dya2

dya1

dya0

4

0

dxb6

dxb5

dxb4

dxb3

dxb2

dxb1

dxb0

5

0

dyb6

dyb5

dyb4

dyb3

dyb2

dyb1

dyb0

Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 were transmitted.

### Sun protocol
The Sun protocol is the 3-byte version of the above 5-byte Mousesystems protocol: the last two bytes are not sent.

### MM protocol
The MM protocol uses 1 start bit, 8 data bits, odd parity, and one stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 3-byte packets. dx and dy are sent as single signed values, the sign bit indicating a negative value. lb (mb, rb) are set when the left (middle, right) button is pressed:

byte

d7

d6

d5

d4

d3

d2

d1

d0

1

1

0

0

dxs

dys

lb

mb

rb

2

0

dx6

dx5

dx4

dx3

dx2

dx1

dx0

3

0

dy6

dy5

dy4

dy3

dy2

dy1

dy0

## FILES
/dev/mouse

A commonly used symbolic link pointing to a mouse device.

## SEE ALSO
ttyS(4), gpm(8)


msr

title: msr(4)

summary: x86 CPU MSR access device

text:
# msr(4)

## NAME
msr - x86 CPU MSR access device

## DESCRIPTION
/dev/cpu/CPUNUM/msr provides an interface to read and write the model-specific registers (MSRs) of an x86 CPU. CPUNUM is the number of the CPU to access as listed in /proc/cpuinfo.

The register access is done by opening the file and seeking to the MSR number as offset in the file, and then reading or writing in chunks of 8 bytes. An I/O transfer of more than 8 bytes means multiple reads or writes of the same register.

This file is protected so that it can be read and written only by the user root, or members of the group root.

## NOTES
The msr driver is not auto-loaded. On modular kernels you might need to use the following command to load it explicitly before use:

```
$ modprobe msr
```

## SEE ALSO
Intel Corporation Intel 64 and IA-32 Architectures Software Developer's Manual Volume 3B Appendix B, for an overview of the Intel CPU MSRs.


title: null(4)

summary: data sink

text:
# null(4)

## NAME
null, zero - data sink

## DESCRIPTION
Data written to the /dev/null and /dev/zero special files is discarded.

Reads from /dev/null always return end of file (i.e., read(2) returns 0), whereas reads from /dev/zero always return bytes containing zero ('\0' characters).

These devices are typically created by:

```
mknod -m 666 /dev/null c 1 3
mknod -m 666 /dev/zero c 1 5
chown root:root /dev/null /dev/zero
```

## FILES
/dev/null

/dev/zero

## NOTES
If these devices are not writable and readable for all users, many programs will act strangely.

Since Linux 2.6.31, reads from /dev/zero are interruptible by signals. (This change was made to help with bad latencies for large reads from /dev/zero.)

## SEE ALSO
chown(1), mknod(1), full(4)


pts

title: pts(4)

summary: pseudoterminal master and slave

text:
# pts(4)

## NAME
ptmx, pts - pseudoterminal master and slave

## DESCRIPTION
The file /dev/ptmx (the pseudoterminal multiplexor device) is a character file with major number 5 and minor number 2, usually with mode 0666 and ownership root:root. It is used to create a pseudoterminal master and slave pair.

When a process opens /dev/ptmx, it gets a file descriptor for a pseudoterminal master and a pseudoterminal slave device is created in the /dev/pts directory. Each file descriptor obtained by opening /dev/ptmx is an independent pseudoterminal master with its own associated slave, whose path can be found by passing the file descriptor to ptsname(3).

Before opening the pseudoterminal slave, you must pass the master's file descriptor to grantpt(3) and unlockpt(3).

Once both the pseudoterminal master and slave are open, the slave provides processes with an interface that is identical to that of a real terminal.

Data written to the slave is presented on the master file descriptor as input. Data written to the master is presented to the slave as input.

In practice, pseudoterminals are used for implementing terminal emulators such as xterm(1), in which data read from the pseudoterminal master is interpreted by the application in the same way a real terminal would interpret the data, and for implementing remote-login programs such as sshd(8), in which data read from the pseudoterminal master is sent across the network to a client program that is connected to a terminal or terminal emulator.

Pseudoterminals can also be used to send input to programs that normally refuse to read input from pipes (such as su(1), and passwd(1)).

## FILES
/dev/ptmx, /dev/pts/*

## NOTES
The Linux support for the above (known as UNIX 98 pseudoterminal naming) is done using the devpts filesystem, which should be mounted on /dev/pts.

## SEE ALSO
getpt(3), grantpt(3), ptsname(3), unlockpt(3), pty(7)


ram

title: ram(4)

summary: ram disk device

text:
# ram(4)

## NAME
ram - ram disk device

## DESCRIPTION
The ram device is a block device to access the ram disk in raw mode.

It is typically created by:

```
mknod -m 660 /dev/ram b 1 1
chown root:disk /dev/ram
```

## FILES
/dev/ram

## SEE ALSO
chown(1), mknod(1), mount(8)


random

title: random(4)

summary: kernel random number source devices

text:
# random(4)

## NAME
random, urandom - kernel random number source devices

## SYNOPSIS

```
#include <linux/random.h>
```

```
int ioctl(fd, RNDrequest, param);
```

## DESCRIPTION
The character special files /dev/random and /dev/urandom (present since Linux 1.3.30) provide an interface to the kernel's random number generator. The file /dev/random has major device number 1 and minor device number 8. The file /dev/urandom has major device number 1 and minor device number 9.

The random number generator gathers environmental noise from device drivers and other sources into an entropy pool. The generator also keeps an estimate of the number of bits of noise in the entropy pool. From this entropy pool, random numbers are created.

Linux 3.17 and later provides the simpler and safer getrandom(2) interface which requires no special files; see the getrandom(2) manual page for details.

When read, the /dev/urandom device returns random bytes using a pseudorandom number generator seeded from the entropy pool. Reads from this device do not block (i.e., the CPU is not yielded), but can incur an appreciable delay when requesting large amounts of data.

When read during early boot time, /dev/urandom may return data prior to the entropy pool being initialized. If this is of concern in your application, use getrandom(2) or /dev/random instead.

The /dev/random device is a legacy interface which dates back to a time where the cryptographic primitives used in the implementation of /dev/urandom were not widely trusted. It will return random bytes only within the estimated number of bits of fresh noise in the entropy pool, blocking if necessary. /dev/random is suitable for applications that need high quality randomness, and can afford indeterminate delays.

When the entropy pool is empty, reads from /dev/random will block until additional environmental noise is gathered. If open(2) is called for /dev/random with the O_NONBLOCK flag, a subsequent read(2) will not block if the requested number of bytes is not available. Instead, the available bytes are returned. If no byte is available, read(2) will return -1 and errno will be set to EAGAIN.

The O_NONBLOCK flag has no effect when opening /dev/urandom. When calling read(2) for the device /dev/urandom, reads of up to 256 bytes will return as many bytes as are requested and will not be interrupted by a signal handler. Reads with a buffer over this limit may return less than the requested number of bytes or fail with the error EINTR, if interrupted by a signal handler.

Since Linux 3.16, a read(2) from /dev/urandom will return at most 32 MB. A read(2) from /dev/random will return at most 512 bytes (340 bytes on Linux kernels before version 2.6.12).

Writing to /dev/random or /dev/urandom will update the entropy pool with the data written, but this will not result in a higher entropy count. This means that it will impact the contents read from both files, but it will not make reads from /dev/random faster.

### Usage
The /dev/random interface is considered a legacy interface, and /dev/urandom is preferred and sufficient in all use cases, with the exception of applications which require randomness during early boot time; for these applications, getrandom(2) must be used instead, because it will block until the entropy pool is initialized.

If a seed file is saved across reboots as recommended below, the output is cryptographically secure against attackers without local root access as soon as it is reloaded in the boot sequence, and perfectly adequate for network encryption session keys. (All major Linux distributions have saved the seed file across reboots since 2000 at least.) Since reads from /dev/random may block, users will usually want to open it in nonblocking mode (or perform a read with timeout), and provide some sort of user notification if the desired entropy is not immediately available.

### Configuration
If your system does not have /dev/random and /dev/urandom created already, they can be created with the following commands:

```
mknod -m 666 /dev/random c 1 8
mknod -m 666 /dev/urandom c 1 9
chown root:root /dev/random /dev/urandom
```

When a Linux system starts up without much operator interaction, the entropy pool may be in a fairly predictable state. This reduces the actual amount of noise in the entropy pool below the estimate. In order to counteract this effect, it helps to carry entropy pool information across shut-downs and start-ups. To do this, add the lines to an appropriate script which is run during the Linux system start-up sequence:

```
echo "Initializing random number generator..."
random_seed=/var/run/random-seed
# Carry a random seed from start-up to start-up
# Load and then save the whole entropy pool
if [ -f $random_seed ]; then

    cat $random_seed >/dev/urandom
else

    touch $random_seed
fi
chmod 600 $random_seed
poolfile=/proc/sys/kernel/random/poolsize
[ -r $poolfile ] && bits=$(cat $poolfile) || bits=4096
bytes=$(expr $bits / 8)
dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
```

Also, add the following lines in an appropriate script which is run during the Linux system shutdown:

```
# Carry a random seed from shut-down to start-up
# Save the whole entropy pool
echo "Saving random seed..."
random_seed=/var/run/random-seed
touch $random_seed
chmod 600 $random_seed
poolfile=/proc/sys/kernel/random/poolsize
[ -r $poolfile ] && bits=$(cat $poolfile) || bits=4096
bytes=$(expr $bits / 8)
dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
```

In the above examples, we assume Linux 2.6.0 or later, where /proc/sys/kernel/random/poolsize returns the size of the entropy pool in bits (see below).

### /proc interfaces
The files in the directory /proc/sys/kernel/random (present since 2.3.16) provide additional information about the /dev/random device:

entropy_avail

This read-only file gives the available entropy, in bits. This will be a number in the range 0 to 4096.

poolsize

This file gives the size of the entropy pool. The semantics of this file vary across kernel versions:

Linux 2.4:

This file gives the size of the entropy pool in bytes. Normally, this file will have the value 512, but it is writable, and can be changed to any value for which an algorithm is available. The choices are 32, 64, 128, 256, 512, 1024, or 2048.

Linux 2.6 and later:

This file is read-only, and gives the size of the entropy pool in bits. It contains the value 4096.

read_wakeup_threshold

This file contains the number of bits of entropy required for waking up processes that sleep waiting for entropy from /dev/random. The default is 64.

write_wakeup_threshold

This file contains the number of bits of entropy below which we wake up processes that do a select(2) or poll(2) for write access to /dev/random. These values can be changed by writing to the files.

uuid and boot_id

These read-only files contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. The former is generated afresh for each read, the latter was generated once.

### ioctl(2) interface
The following ioctl(2) requests are defined on file descriptors connected to either /dev/random or /dev/urandom. All requests performed will interact with the input entropy pool impacting both /dev/random and /dev/urandom. The CAP_SYS_ADMIN capability is required for all requests except RNDGETENTCNT.

RNDGETENTCNT

Retrieve the entropy count of the input pool, the contents will be the same as the entropy_avail file under proc. The result will be stored in the int pointed to by the argument.

RNDADDTOENTCNT

Increment or decrement the entropy count of the input pool by the value pointed to by the argument.

RNDGETPOOL

Removed in Linux 2.6.9.

RNDADDENTROPY

Add some additional entropy to the input pool, incrementing the entropy count. This differs from writing to /dev/random or /dev/urandom, which only adds some data but does not increment the entropy count. The following structure is used:

```
struct rand_pool_info {

    int    entropy_count;

    int    buf_size;

    __u32  buf[0];
};

```

Here entropy_count is the value added to (or subtracted from) the entropy count, and buf is the buffer of size buf_size which gets added to the entropy pool.

RNDZAPENTCNT, RNDCLEARPOOL

Zero the entropy count of all pools and add some system data (such as wall clock) to the pools.

## FILES
/dev/random

/dev/urandom

## NOTES
For an overview and comparison of the various interfaces that can be used to obtain randomness, see random(7).

## BUGS
During early boot time, reads from /dev/urandom may return data prior to the entropy pool being initialized.

## SEE ALSO
mknod(1), getrandom(2), random(7)

RFC 1750, "Randomness Recommendations for Security"


rtc

title: rtc(4)

summary: real-time clock

text:
# rtc(4)

## NAME
rtc - real-time clock

## SYNOPSIS

```
#include <linux/rtc.h>
```

```
int ioctl(fd, RTC_request, param);
```

## DESCRIPTION
This is the interface to drivers for real-time clocks (RTCs).

Most computers have one or more hardware clocks which record the current "wall clock" time. These are called "Real Time Clocks" (RTCs). One of these usually has battery backup power so that it tracks the time even while the computer is turned off. RTCs often provide alarms and other interrupts.

All i386 PCs, and ACPI-based systems, have an RTC that is compatible with the Motorola MC146818 chip on the original PC/AT. Today such an RTC is usually integrated into the mainboard's chipset (south bridge), and uses a replaceable coin-sized backup battery.

Non-PC systems, such as embedded systems built around system-on-chip processors, use other implementations. They usually won't offer the same functionality as the RTC from a PC/AT.

### RTC vs system clock
RTCs should not be confused with the system clock, which is a software clock maintained by the kernel and used to implement gettimeofday(2) and time(2), as well as setting timestamps on files, and so on. The system clock reports seconds and microseconds since a start point, defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). (One common implementation counts timer interrupts, once per "jiffy", at a frequency of 100, 250, or 1000 Hz.) That is, it is supposed to report wall clock time, which RTCs also do.

A key difference between an RTC and the system clock is that RTCs run even when the system is in a low power state (including "off"), and the system clock can't. Until it is initialized, the system clock can only report time since system boot ... not since the POSIX Epoch. So at boot time, and after resuming from a system low power state, the system clock will often be set to the current wall clock time using an RTC. Systems without an RTC need to set the system clock using another clock, maybe across the network or by entering that data manually.

### RTC functionality
RTCs can be read and written with hwclock(8), or directly with the ioctl(2) requests listed below.

Besides tracking the date and time, many RTCs can also generate interrupts

- on every clock update (i.e., once per second);

- at periodic intervals with a frequency that can be set to any power-of-2 multiple in the range 2 Hz to 8192 Hz;

- on reaching a previously specified alarm time.

Each of those interrupt sources can be enabled or disabled separately. On many systems, the alarm interrupt can be configured as a system wakeup event, which can resume the system from a low power state such as Suspend-to-RAM (STR, called S3 in ACPI systems), Hibernation (called S4 in ACPI systems), or even "off" (called S5 in ACPI systems). On some systems, the battery backed RTC can't issue interrupts, but another one can.

The /dev/rtc (or /dev/rtc0, /dev/rtc1, etc.) device can be opened only once (until it is closed) and it is read-only. On read(2) and select(2) the calling process is blocked until the next interrupt from that RTC is received. Following the interrupt, the process can read a long integer, of which the least significant byte contains a bit mask encoding the types of interrupt that occurred, while the remaining 3 bytes contain the number of interrupts since the last read(2).

### ioctl(2) interface
The following ioctl(2) requests are defined on file descriptors connected to RTC devices:

RTC_RD_TIME

Returns this RTC's time in the following structure:

```
struct rtc_time {

    int tm_sec;

    int tm_min;

    int tm_hour;

    int tm_mday;

    int tm_mon;

    int tm_year;

    int tm_wday;     /* unused */

    int tm_yday;     /* unused */

    int tm_isdst;    /* unused */
};

```

The fields in this structure have the same meaning and ranges as for the tm structure described in gmtime(3). A pointer to this structure should be passed as the third ioctl(2) argument.

RTC_SET_TIME

Sets this RTC's time to the time specified by the rtc_time structure pointed to by the third ioctl(2) argument. To set the RTC's time the process must be privileged (i.e., have the CAP_SYS_TIME capability).

RTC_ALM_READ, RTC_ALM_SET

Read and set the alarm time, for RTCs that support alarms. The alarm interrupt must be separately enabled or disabled using the RTC_AIE_ON, RTC_AIE_OFF requests. The third ioctl(2) argument is a pointer to an rtc_time structure. Only the tm_sec, tm_min, and tm_hour fields of this structure are used.

RTC_IRQP_READ, RTC_IRQP_SET

Read and set the frequency for periodic interrupts, for RTCs that support periodic interrupts. The periodic interrupt must be separately enabled or disabled using the RTC_PIE_ON, RTC_PIE_OFF requests. The third ioctl(2) argument is an unsigned long * or an unsigned long, respectively. The value is the frequency in interrupts per second. The set of allowable frequencies is the multiples of two in the range 2 to 8192. Only a privileged process (i.e., one having the CAP_SYS_RESOURCE capability) can set frequencies above the value specified in /proc/sys/dev/rtc/max-user-freq. (This file contains the value 64 by default.)

RTC_AIE_ON, RTC_AIE_OFF

Enable or disable the alarm interrupt, for RTCs that support alarms. The third ioctl(2) argument is ignored.

RTC_UIE_ON, RTC_UIE_OFF

Enable or disable the interrupt on every clock update, for RTCs that support this once-per-second interrupt. The third ioctl(2) argument is ignored.

RTC_PIE_ON, RTC_PIE_OFF

Enable or disable the periodic interrupt, for RTCs that support these periodic interrupts. The third ioctl(2) argument is ignored. Only a privileged process (i.e., one having the CAP_SYS_RESOURCE capability) can enable the periodic interrupt if the frequency is currently set above the value specified in /proc/sys/dev/rtc/max-user-freq.

RTC_EPOCH_READ, RTC_EPOCH_SET

Many RTCs encode the year in an 8-bit register which is either interpreted as an 8-bit binary number or as a BCD number. In both cases, the number is interpreted relative to this RTC's Epoch. The RTC's Epoch is initialized to 1900 on most systems but on Alpha and MIPS it might also be initialized to 1952, 1980, or 2000, depending on the value of an RTC register for the year. With some RTCs, these operations can be used to read or to set the RTC's Epoch, respectively. The third ioctl(2) argument is an unsigned long * or an unsigned long, respectively, and the value returned (or assigned) is the Epoch. To set the RTC's Epoch the process must be privileged (i.e., have the CAP_SYS_TIME capability).

RTC_WKALM_RD, RTC_WKALM_SET

Some RTCs support a more powerful alarm interface, using these ioctls to read or write the RTC's alarm time (respectively) with this structure:

```
struct rtc_wkalrm {

    unsigned char enabled;

    unsigned char pending;

    struct rtc_time time;
};
```

The enabled flag is used to enable or disable the alarm interrupt, or to read its current status; when using these calls, RTC_AIE_ON and RTC_AIE_OFF are not used. The pending flag is used by RTC_WKALM_RD to report a pending interrupt (so it's mostly useless on Linux, except when talking to the RTC managed by EFI firmware). The time field is as used with RTC_ALM_READ and RTC_ALM_SET except that the tm_mday, tm_mon, and tm_year fields are also valid. A pointer to this structure should be passed as the third ioctl(2) argument.

## FILES
/dev/rtc, /dev/rtc0, /dev/rtc1, etc.

RTC special character device files.

/proc/driver/rtc

status of the (first) RTC.

## NOTES
When the kernel's system time is synchronized with an external reference using adjtimex(2) it will update a designated RTC periodically every 11 minutes. To do so, the kernel has to briefly turn off periodic interrupts; this might affect programs using that RTC.

An RTC's Epoch has nothing to do with the POSIX Epoch which is used only for the system clock.

If the year according to the RTC's Epoch and the year register is less than 1970 it is assumed to be 100 years later, that is, between 2000 and 2069.

Some RTCs support "wildcard" values in alarm fields, to support scenarios like periodic alarms at fifteen minutes after every hour, or on the first day of each month. Such usage is nonportable; portable user-space code expects only a single alarm interrupt, and will either disable or reinitialize the alarm after receiving it.

Some RTCs support periodic interrupts with periods that are multiples of a second rather than fractions of a second; multiple alarms; programmable output clock signals; nonvolatile memory; and other hardware capabilities that are not currently exposed by this API.

## SEE ALSO
date(1), adjtimex(2), gettimeofday(2), settimeofday(2), stime(2), time(2), gmtime(3), time(7), hwclock(8)

Documentation/rtc.txt in the Linux kernel source tree


sd

title: sd(4)

summary: driver for SCSI disk drives

text:
# sd(4)

## NAME
sd - driver for SCSI disk drives

## SYNOPSIS

```
#include <linux/hdreg.h>        /* for HDIO_GETGEO */
#include <linux/fs.h>           /* for BLKGETSIZE and BLKRRPART */
```

## CONFIGURATION
The block device name has the following form: sdlp, where l is a letter denoting the physical drive, and p is a number denoting the partition on that physical drive. Often, the partition number, p, will be left off when the device corresponds to the whole drive.

SCSI disks have a major device number of 8, and a minor device number of the form (16 * drive_number) + partition_number, where drive_number is the number of the physical drive in order of detection, and partition_number is as follows:

+3

partition 0 is the whole drive

partitions 1–4 are the DOS "primary" partitions

partitions 5–8 are the DOS "extended" (or "logical") partitions

For example, /dev/sda will have major 8, minor 0, and will refer to all of the first SCSI drive in the system; and /dev/sdb3 will have major 8, minor 19, and will refer to the third DOS "primary" partition on the second SCSI drive in the system.

At this time, only block devices are provided. Raw devices have not yet been implemented.

## DESCRIPTION
The following ioctls are provided:

HDIO_GETGEO

Returns the BIOS disk parameters in the following structure:

```
struct hd_geometry {

    unsigned char  heads;

    unsigned char  sectors;

    unsigned short cylinders;

    unsigned long  start;
};
```

A pointer to this structure is passed as the ioctl(2) parameter.

The information returned in the parameter is the disk geometry of the drive as understood by DOS! This geometry is not the physical geometry of the drive. It is used when constructing the drive's partition table, however, and is needed for convenient operation of fdisk(1), efdisk(1), and lilo(1). If the geometry information is not available, zero will be returned for all of the parameters.

BLKGETSIZE

Returns the device size in sectors. The ioctl(2) parameter should be a pointer to a long.

BLKRRPART

Forces a reread of the SCSI disk partition tables. No parameter is needed.

The SCSI ioctl(2) operations are also supported. If the ioctl(2) parameter is required, and it is NULL, then ioctl(2) fails with the error EINVAL.

## FILES
/dev/sd[a-h]

the whole device

/dev/sd[a-h][0-8]

individual block partitions