From 6d5b69483a58885d58f741de68d4c20286311fa5 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mario=20Bl=C3=A4ttermann?= Date: Fri, 12 Mar 2021 21:10:37 +0100 Subject: [PATCH] Asciidoc: Import sys-utils man pages, part 1 --- sys-utils/adjtime_config.5.adoc | 64 +++++++++++ sys-utils/blkdiscard.8.adoc | 71 ++++++++++++ sys-utils/blkzone.8.adoc | 121 ++++++++++++++++++++ sys-utils/chcpu.8.adoc | 89 +++++++++++++++ sys-utils/chmem.8.adoc | 98 ++++++++++++++++ sys-utils/choom.1.adoc | 64 +++++++++++ sys-utils/ctrlaltdel.8.adoc | 61 ++++++++++ sys-utils/dmesg.1.adoc | 191 ++++++++++++++++++++++++++++++++ sys-utils/eject.1.adoc | 133 ++++++++++++++++++++++ sys-utils/fallocate.1.adoc | 93 ++++++++++++++++ sys-utils/flock.1.adoc | 136 +++++++++++++++++++++++ sys-utils/fsfreeze.8.adoc | 65 +++++++++++ sys-utils/fstab.5.adoc | 160 ++++++++++++++++++++++++++ sys-utils/fstrim.8.adoc | 95 ++++++++++++++++ sys-utils/ipcmk.1.adoc | 64 +++++++++++ sys-utils/ipcrm.1.adoc | 88 +++++++++++++++ sys-utils/ipcs.1.adoc | 109 ++++++++++++++++++ sys-utils/irqtop.1.adoc | 71 ++++++++++++ sys-utils/ldattach.8.adoc | 132 ++++++++++++++++++++++ sys-utils/losetup.8.adoc | 169 ++++++++++++++++++++++++++++ sys-utils/lscpu.1.adoc | 161 +++++++++++++++++++++++++++ sys-utils/lsipc.1.adoc | 125 +++++++++++++++++++++ sys-utils/lsirq.1.adoc | 60 ++++++++++ sys-utils/lsmem.1.adoc | 85 ++++++++++++++ sys-utils/lsns.8.adoc | 87 +++++++++++++++ 25 files changed, 2592 insertions(+) create mode 100644 sys-utils/adjtime_config.5.adoc create mode 100644 sys-utils/blkdiscard.8.adoc create mode 100644 sys-utils/blkzone.8.adoc create mode 100644 sys-utils/chcpu.8.adoc create mode 100644 sys-utils/chmem.8.adoc create mode 100644 sys-utils/choom.1.adoc create mode 100644 sys-utils/ctrlaltdel.8.adoc create mode 100644 sys-utils/dmesg.1.adoc create mode 100644 sys-utils/eject.1.adoc create mode 100644 sys-utils/fallocate.1.adoc create mode 100644 sys-utils/flock.1.adoc create mode 100644 sys-utils/fsfreeze.8.adoc create mode 100644 sys-utils/fstab.5.adoc create mode 100644 sys-utils/fstrim.8.adoc create mode 100644 sys-utils/ipcmk.1.adoc create mode 100644 sys-utils/ipcrm.1.adoc create mode 100644 sys-utils/ipcs.1.adoc create mode 100644 sys-utils/irqtop.1.adoc create mode 100644 sys-utils/ldattach.8.adoc create mode 100644 sys-utils/losetup.8.adoc create mode 100644 sys-utils/lscpu.1.adoc create mode 100644 sys-utils/lsipc.1.adoc create mode 100644 sys-utils/lsirq.1.adoc create mode 100644 sys-utils/lsmem.1.adoc create mode 100644 sys-utils/lsns.8.adoc diff --git a/sys-utils/adjtime_config.5.adoc b/sys-utils/adjtime_config.5.adoc new file mode 100644 index 0000000000..4a72e6b300 --- /dev/null +++ b/sys-utils/adjtime_config.5.adoc @@ -0,0 +1,64 @@ += adjtime_config(5) +:doctype: manpage +:man manual: File formats +:man source: util-linux {release-version} +:page-layout: base +:configfile: adjtime_config + +== NAME + +adjtime_config - information about hardware clock setting and drift factor + +== SYNOPSIS + +_/etc/adjtime_ + +== DESCRIPTION + +The file _/etc/adjtime_ contains descriptive information about the hardware mode clock setting and clock drift factor. The file is read and write by *hwclock*(8); and read by programs like rtcwake to get RTC time mode. + +The file is usually located in _/etc_, but tools like *hwclock*(8) or *rtcwake*(8) can use alternative location by command line options if write access to _/etc_ is unwanted. The default clock mode is "UTC" if the file is missing. + +The Hardware Clock is usually not very accurate. However, much of its inaccuracy is completely predictable - it gains or loses the same amount of time every day. This is called systematic drift. The util *hwclock*(8) keeps the file _/etc/adjtime_, that keeps some historical information. For more details see "*The Adjust Function*" and "*The Adjtime File*" sections from *hwclock*(8) man page. + +The format of the adjtime file is, in ASCII. + +=== First line + +Three numbers, separated by blanks: + +*drift factor*:: + the systematic drift rate in seconds per day (floating point decimal) + +*last adjust time*:: + the resulting number of seconds since 1969 UTC of most recent adjustment or calibration (decimal integer) + +*adjustment status*:: + zero (for compatibility with *clock*(8)) as a floating point decimal + +=== Second line + +*last calibration time*:: + The resulting number of seconds since 1969 UTC of most recent calibration. Zero if there has been no calibration yet or it is known that any previous calibration is moot (for example, because the Hardware Clock has been found, since that calibration, not to contain a valid time). This is a decimal integer. + +=== Third line + +*clock mode*:: + Supported values are *UTC* or *LOCAL*. Tells whether the Hardware Clock is set to Coordinated Universal Time or local time. You can always override this value with options on the *hwclock*(8) command line. + +== FILES + +_/etc/adjtime_ + +== SEE ALSO + +*hwclock*(8), +*rtcwake*(8) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer-config.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/blkdiscard.8.adoc b/sys-utils/blkdiscard.8.adoc new file mode 100644 index 0000000000..1d2fadae87 --- /dev/null +++ b/sys-utils/blkdiscard.8.adoc @@ -0,0 +1,71 @@ += blkdiscard(8) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: blkdiscard + +== NAME + +blkdiscard - discard sectors on a device + +== SYNOPSIS + +*blkdiscard* _options_ [*-o* _offset_] *-l* [_length_] _device_ + +== DESCRIPTION + +*blkdiscard* is used to discard device sectors. This is useful for solid-state drivers (SSDs) and thinly-provisioned storage. Unlike *fstrim*(8), this command is used directly on the block device. + +By default, *blkdiscard* will discard all blocks on the device. Options may be used to modify this behavior based on range or size, as explained below. + +The _device_ argument is the pathname of the block device. + +*WARNING: All data in the discarded region on the device will be lost!* + +== OPTIONS + +The _offset_ and _length_ arguments may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB") or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. + +*-f*, *--force*:: + Disable all checking. Since v2.36 the block device is open in exclusive mode (O_EXCL) by default to avoid collision with mounted filesystem or another kernel subsystem. The *--force* option disables the exclusive access mode. + +*-o*, *--offset* _offset_:: + Byte offset into the device from which to start discarding. The provided value must be aligned to the device sector size. The default value is zero. + +*-l*, *--length* _length_:: + The number of bytes to discard (counting from the starting point). The provided value must be aligned to the device sector size. If the specified value extends past the end of the device, *blkdiscard* will stop at the device size boundary. The default value extends to the end of the device. + +*-p*, *--step* _length_:: + The number of bytes to discard within one iteration. The default is to discard all by one ioctl call. + +*-s*, *--secure*:: + Perform a secure discard. A secure discard is the same as a regular discard except that all copies of the discarded blocks that were possibly created by garbage collection must also be erased. This requires support from the device. + +*-z*, *--zeroout*:: + Zero-fill rather than discard. + +*-v*, *--verbose*:: + Display the aligned values of _offset_ and _length_. If the *--step* option is specified, it prints the discard progress every second. + +*-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== AUTHORS + +mailto:lczerner@redhat.com[Lukas Czerner] + +== SEE ALSO + +*fstrim*(8) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/blkzone.8.adoc b/sys-utils/blkzone.8.adoc new file mode 100644 index 0000000000..27af082d97 --- /dev/null +++ b/sys-utils/blkzone.8.adoc @@ -0,0 +1,121 @@ += blkzone(8) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: blkzone + +== NAME + +blkzone - run zone command on a device + +== SYNOPSIS + +*blkzone* _command_ [_options_] _device_ + +== DESCRIPTION + +*blkzone* is used to run zone command on device that support the Zoned Block Commands (ZBC) or Zoned-device ATA Commands (ZAC). The zones to operate on can be specified using the offset, count and length options. + +The _device_ argument is the pathname of the block device. + +== COMMANDS + +=== report + +The command *blkzone report* is used to report device zone information. + +By default, the command will report all zones from the start of the block device. Options may be used to modify this behavior, changing the starting zone or the size of the report, as explained below. + +.Report output +[cols=",",] +|=== +|start |Zone start sector +|len |Zone length in number of sectors +|cap |Zone capacity in number of sectors +|wptr |Zone write pointer position +|reset |Reset write pointer recommended +|non-seq |Non-sequential write resources active +|cond |Zone condition +|type |Zone type +|=== + +.Zone conditions +[cols=",",] +|=== +|cl |Closed +|nw |Not write pointer +|em |Empty +|fu |Full +|oe |Explicitly opened +|oi |Implicitly opened +|ol |Offline +|ro |Read only +|x? |Reserved conditions (should not be reported) +|=== + +=== capacity + +The command *blkzone capacity* is used to report device capacity information. + +By default, the command will report the sum, in number of sectors, of all zone capacities on the device. Options may be used to modify this behavior, changing the starting zone or the size of the report, as explained below. + +=== reset + +The command *blkzone reset* is used to reset one or more zones. Unlike *sg_reset_wp*(8), this command operates from the block layer and can reset a range of zones. + +=== open + +The command *blkzone open* is used to explicitly open one or more zones. Unlike *sg_zone*(8), open action, this command operates from the block layer and can open a range of zones. + +=== close + +The command *blkzone close* is used to close one or more zones. Unlike *sg_zone*(8), close action, this command operates from the block layer and can close a range of zones. + +=== finish + +The command *blkzone finish* is used to finish (transition to full condition) one or more zones. Unlike *sg_zone*(8), finish action, this command operates from the block layer and can finish a range of zones. + +By default, the reset, open, close and finish commands will operate from the zone at device sector 0 and operate on all zones. Options may be used to modify this behavior as explained below. + +== OPTIONS + +The _offset_ and _length_ option arguments may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB") or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. Additionally, the 0x prefix can be used to specify _offset_ and _length_ in hex. + +*-o*, *--offset* _sector_:: + The starting zone specified as a sector offset. The provided offset in sector units (512 bytes) should match the start of a zone. The default value is zero. + +*-l*, *--length* _sectors_:: + The maximum number of sectors the command should operate on. The default value is the number of sectors remaining after _offset_. This option cannot be used together with the option *--count*. + +*-c*, *--count* _count_:: + The maximum number of zones the command should operate on. The default value is the number of zones starting from _offset_. This option cannot be used together with the option *--length*. + +*-f*, *--force*:: + Enforce commands to change zone status on block devices used by the system. + +*-v*, *--verbose*:: + Display the number of zones returned in the report or the range of sectors reset. + +*-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== AUTHORS + +mailto:shaun@tancheff.com[Shaun Tancheff] + +mailto:kzak@redhat.com[Karel Zak] + +== SEE ALSO + +*sg_rep_zones*(8) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/chcpu.8.adoc b/sys-utils/chcpu.8.adoc new file mode 100644 index 0000000000..721f739e5b --- /dev/null +++ b/sys-utils/chcpu.8.adoc @@ -0,0 +1,89 @@ += chcpu(8) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: chcpu + +== NAME + +chcpu - configure CPUs + +== SYNOPSIS + +*chcpu* *-c*|*-d*|*-e*|*-g* _cpu-list_ + +*chcpu* *-p* _mode_ + +*chcpu* *-r*|*-h*|*-V* + +== DESCRIPTION + +*chcpu* can modify the state of CPUs. It can enable or disable CPUs, scan for new CPUs, change the CPU dispatching _mode_ of the underlying hypervisor, and request CPUs from the hypervisor (configure) or return CPUs to the hypervisor (deconfigure). + +Some options have a _cpu-list_ argument. Use this argument to specify a comma-separated list of CPUs. The list can contain individual CPU addresses or ranges of addresses. For example, *0,5,7,9-11* makes the command applicable to the CPUs with the addresses 0, 5, 7, 9, 10, and 11. + +== OPTIONS + +*-c*, *--configure* _cpu-list_:: + Configure the specified CPUs. Configuring a CPU means that the hypervisor takes a CPU from the CPU pool and assigns it to the virtual hardware on which your kernel runs. + +*-d*, *--disable* _cpu-list_:: + Disable the specified CPUs. Disabling a CPU means that the kernel sets it offline. + +*-e*, *--enable* _cpu-list_:: + Enable the specified CPUs. Enabling a CPU means that the kernel sets it online. A CPU must be configured, see *-c*, before it can be enabled. + +*-g*, *--deconfigure* _cpu-list_:: + Deconfigure the specified CPUs. Deconfiguring a CPU means that the hypervisor removes the CPU from the virtual hardware on which the Linux instance runs and returns it to the CPU pool. A CPU must be offline, see *-d*, before it can be deconfigured. + +*-p*, *--dispatch* _mode_:: + Set the CPU dispatching _mode_ (polarization). This option has an effect only if your hardware architecture and hypervisor support CPU polarization. Available _modes_ are: + + *horizontal*;; + The workload is spread across all available CPUs. + + *vertical*;; + The workload is concentrated on few CPUs. + +*-r*, *--rescan*:: + Trigger a rescan of CPUs. After a rescan, the Linux kernel recognizes the new CPUs. Use this option on systems that do not automatically detect newly attached CPUs. + + *-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== EXIT STATUS + +*chcpu* has the following exit status values: + +*0*:: + success + +*1*:: + failure + +*64*:: + partial success + +== AUTHORS + +mailto:heiko.carstens@de.ibm.com[Heiko Carstens] + +== COPYRIGHT + +Copyright IBM Corp. 2011 + +== SEE ALSO + +*lscpu*(1) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/chmem.8.adoc b/sys-utils/chmem.8.adoc new file mode 100644 index 0000000000..49d3cde553 --- /dev/null +++ b/sys-utils/chmem.8.adoc @@ -0,0 +1,98 @@ += chmem(8) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: chmem + +== NAME + +chmem - configure memory + +== SYNOPSIS + +*chmem* [*-h] [*-V*] [*-v*] [*-e*|*-d*] [_SIZE_|_RANGE_ *-b* _BLOCKRANGE_] [*-z* _ZONE_] + +== DESCRIPTION + +The chmem command sets a particular size or range of memory online or offline. + +-:: + Specify _SIZE_ as [m|M|g|G]. With m or M, specifies the memory size in MiB (1024 x 1024 bytes). With g or G, specifies the memory size in GiB (1024 x 1024 x 1024 bytes). The default unit is MiB. + +-:: + Specify _RANGE_ in the form 0x-0x as shown in the output of the *lsmem*(1) command. is the hexadecimal address of the first byte and is the hexadecimal address of the last byte in the memory range. + +-:: + Specify _BLOCKRANGE_ in the form - or as shown in the output of the *lsmem*(1) command. is the number of the first memory block and is the number of the last memory block in the memory range. Alternatively a single block can be specified. _BLOCKRANGE_ requires the *--blocks* option. + +-:: + Specify _ZONE_ as the name of a memory zone, as shown in the output of the *lsmem -o +ZONES* command. The output shows one or more valid memory zones for each memory range. If multiple zones are shown, then the memory range currently belongs to the first zone. By default, *chmem* will set memory online to the zone Movable, if this is among the valid zones. This default can be changed by specifying the *--zone* option with another valid zone. For memory ballooning, it is recommended to select the zone Movable for memory online and offline, if possible. Memory in this zone is much more likely to be able to be offlined again, but it cannot be used for arbitrary kernel allocations, only for migratable pages (e.g., anonymous and page cache pages). Use the *--help* option to see all available zones. + +_SIZE_ and _RANGE_ must be aligned to the Linux memory block size, as shown in the output of the *lsmem*(1) command. + +Setting memory online can fail for various reasons. On virtualized systems it can fail if the hypervisor does not have enough memory left, for example because memory was overcommitted. Setting memory offline can fail if Linux cannot free the memory. If only part of the requested memory can be set online or offline, a message tells you how much memory was set online or offline instead of the requested amount. + +When setting memory online *chmem* starts with the lowest memory block numbers. When setting memory offline *chmem* starts with the highest memory block numbers. + +== OPTIONS + +*-b*, *--blocks*:: + Use a _BLOCKRANGE_ parameter instead of _RANGE_ or _SIZE_ for the *--enable* and *--disable* options. + +*-d*, *--disable*:: + Set the specified _RANGE_, _SIZE_, or _BLOCKRANGE_ of memory offline. + +*-e*, *--enable*:: + Set the specified _RANGE_, _SIZE_, or _BLOCKRANGE_ of memory online. + +*-z*, *--zone*:: + Select the memory _ZONE_ where to set the specified _RANGE_, _SIZE_, or _BLOCKRANGE_ of memory online or offline. By default, memory will be set online to the zone Movable, if possible. + +*-h*, *--help*:: + Print a short help text, then exit. + +*-v*, *--verbose*:: + Verbose mode. Causes *chmem* to print debugging messages about it's progress. + +*-V*, *--version*:: + Print the version number, then exit. + +== EXIT STATUS + +*chmem* has the following exit status values: + +*0*:: + success + +*1*:: + failure + +*64*:: + partial success + +== EXAMPLE + +*chmem --enable 1024*:: + This command requests 1024 MiB of memory to be set online. + +*chmem -e 2g*:: + This command requests 2 GiB of memory to be set online. + +*chmem --disable 0x00000000e4000000-0x00000000f3ffffff*:: + This command requests the memory range starting with 0x00000000e4000000 and ending with 0x00000000f3ffffff to be set offline. + +*chmem -b -d 10*:: + This command requests the memory block number 10 to be set offline. + +== SEE ALSO + +*lsmem*(1) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/choom.1.adoc b/sys-utils/choom.1.adoc new file mode 100644 index 0000000000..e317567dfd --- /dev/null +++ b/sys-utils/choom.1.adoc @@ -0,0 +1,64 @@ += choom(1) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: choom + +== NAME + +choom - display and adjust OOM-killer score. + +*choom* *-p* _PID_ + +*choom* *-p* _PID_ *-n* _number_ + +*choom* *-n* _number_ [--] _command_ [_argument_ ...] + +== DESCRIPTION + +The *choom* command displays and adjusts Out-Of-Memory killer score setting. + +== OPTIONS + +*-p*, *--pid* _pid_:: + Specifies process ID. + +*-n*, *--adjust* _value_:: + Specify the adjust score value. + +*-h*, *--help*:: + Display help text and exit. + +*-V*, *--version*:: + Display version information and exit. + +== NOTES + +Linux kernel uses the badness heuristic to select which process gets killed in out of memory conditions. + +The badness heuristic assigns a value to each candidate task ranging from 0 (never kill) to 1000 (always kill) to determine which process is targeted. The units are roughly a proportion along that range of allowed memory the process may allocate from based on an estimation of its current memory and swap use. For example, if a task is using all allowed memory, its badness score will be 1000. If it is using half of its allowed memory, its score will be 500. + +There is an additional factor included in the badness score: the current memory and swap usage is discounted by 3% for root processes. + +The amount of "allowed" memory depends on the context in which the oom killer was called. If it is due to the memory assigned to the allocating task's cpuset being exhausted, the allowed memory represents the set of mems assigned to that cpuset. If it is due to a mempolicy's node(s) being exhausted, the allowed memory represents the set of mempolicy nodes. If it is due to a memory limit (or swap limit) being reached, the allowed memory is that configured limit. Finally, if it is due to the entire system being out of memory, the allowed memory represents all allocatable resources. + +The adjust score value is added to the badness score before it is used to determine which task to kill. Acceptable values range from -1000 to +1000. This allows userspace to polarize the preference for oom killing either by always preferring a certain task or completely disabling it. The lowest possible value, -1000, is equivalent to disabling oom killing entirely for that task since it will always report a badness score of 0. + +Setting an adjust score value of +500, for example, is roughly equivalent to allowing the remainder of tasks sharing the same system, cpuset, mempolicy, or memory controller resources to use at least 50% more memory. A value of -500, on the other hand, would be roughly equivalent to discounting 50% of the task's allowed memory from being considered as scoring against the task. + +== AUTHORS + +mailto:kzak@redhat.com[Karel Zak] + +== SEE ALSO + +*proc*(5) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/ctrlaltdel.8.adoc b/sys-utils/ctrlaltdel.8.adoc new file mode 100644 index 0000000000..edc847aca6 --- /dev/null +++ b/sys-utils/ctrlaltdel.8.adoc @@ -0,0 +1,61 @@ +//// +Copyright 1992, 1993 Rickard E. Faith (faith@cs.unc.edu) +May be distributed under the GNU General Public License +//// += ctrlaltdel(8) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: ctrlaltdel + +== NAME + +ctrlaltdel - set the function of the Ctrl-Alt-Del combination + +== SYNOPSIS + +*ctrlaltdel* *hard*|*soft* + +== DESCRIPTION + +Based on examination of the _linux/kernel/reboot.c_ code, it is clear that there are two supported functions that the sequence can perform. + +*hard*:: + Immediately reboot the computer without calling *sync*(2) and without any other preparation. This is the default. + +*soft*:: + Make the kernel send the SIGINT (interrupt) signal to the *init* process (this is always the process with PID 1). If this option is used, the *init*(8) program must support this feature. Since there are now several *init*(8) programs in the Linux community, please consult the documentation for the version that you are currently using. + +When the command is run without any argument, it will display the current setting. + +The function of *ctrlaltdel* is usually set in the _/etc/rc.local_ file. + +== OPTIONS + +*-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== FILES + +_/etc/rc.local_ + +== AUTHORS + +mailto:poe@daimi.aau.dk[Peter Orbaek] + +== SEE ALSO + +*init*(8), +*systemd*(1) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/dmesg.1.adoc b/sys-utils/dmesg.1.adoc new file mode 100644 index 0000000000..9306600fe6 --- /dev/null +++ b/sys-utils/dmesg.1.adoc @@ -0,0 +1,191 @@ +//// +Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +May be distributed under the GNU General Public License +//// += dmesg(1) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: dmesg + +== NAME + +dmesg - print or control the kernel ring buffer + +== SYNOPSIS + +*dmesg* [_options_] + +*dmesg* *--clear* + +*dmesg* *--read-clear* [_options_] + +*dmesg* *--console-level* _level_ + +*dmesg* *--console-on* + +*dmesg* *--console-off* + +== DESCRIPTION + +*dmesg* is used to examine or control the kernel ring buffer. + +The default action is to display all messages from the kernel ring buffer. + +== OPTIONS + +The *--clear*, *--read-clear*, *--console-on*, *--console-off*, and *--console-level* options are mutually exclusive. + +*-C*, *--clear*:: + Clear the ring buffer. + +*-c*, *--read-clear*:: + Clear the ring buffer after first printing its contents. + +*-D*, *--console-off*:: + Disable the printing of messages to the console. + +*-d*, *--show-delta*:: + Display the timestamp and the time delta spent between messages. If used together with *--notime* then only the time delta without the timestamp is printed. + +*-E*, *--console-on*:: + Enable printing messages to the console. + +*-e*, *--reltime*:: + Display the local time and the delta in human-readable format. Be aware that conversion to the local time could be inaccurate (see *-T* for more details). + +*-F*, *--file* _file_:: + Read the syslog messages from the given _file_. Note that *-F* does not support messages in kmsg format. The old syslog format is supported only. + +*-f*, *--facility* _list_:: + Restrict output to the given (comma-separated) _list_ of facilities. For example: + + *dmesg --facility=daemon* + + will print messages from system daemons only. For all supported facilities see the *--help* output. + +*-H*, *--human*:: + Enable human-readable output. See also *--color*, *--reltime* and *--nopager*. + +*-k*, *--kernel*:: + Print kernel messages. + +*-L*, *--color*[=_when_]:: + Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled; for the current built-in default see the *--help* output. See also the *COLORS* section below. + +*-l*, *--level* _list_:: + Restrict output to the given (comma-separated) _list_ of levels. For example: + + *dmesg --level=err,warn* + + will print error and warning messages only. For all supported levels see the *--help* output. + +*-n*, *--console-level* _level_:: + Set the _level_ at which printing of messages is done to the console. The _level_ is a level number or abbreviation of the level name. For all supported levels see the *--help* output. + + For example, *-n 1* or *-n emerg* prevents all messages, except emergency (panic) messages, from appearing on the console. All levels of messages are still written to _/proc/kmsg_, so *syslogd*(8) can still be used to control exactly where kernel messages appear. When the *-n* option is used, *dmesg* will _not_ print or clear the kernel ring buffer. + +*--noescape*:: + The unprintable and potentially unsafe characters (e.g., broken multi-byte sequences, terminal controlling chars, etc.) are escaped in format x for security reason by default. This option disables this feature at all. It's usable for example for debugging purpose together with *--raw*. Be careful and don't use it by default. + +*-P*, *--nopager*:: + Do not pipe output into a pager. A pager is enabled by default for *--human* output. + +*-p*, *--force-prefix*:: + Add facility, level or timestamp information to each line of a multi-line message. + +*-r*, *--raw*:: + Print the raw message buffer, i.e., do not strip the log-level prefixes, but all unprintable characters are still escaped (see also *--noescape*). + + + Note that the real raw format depends on the method how *dmesg* reads kernel messages. The _/dev/kmsg_ device uses a different format than *syslog*(2). For backward compatibility, *dmesg* returns data always in the *syslog*(2) format. It is possible to read the real raw data from _/dev/kmsg_ by, for example, the command 'dd if=/dev/kmsg iflag=nonblock'. + +*-S*, *--syslog*:: + Force *dmesg* to use the *syslog*(2) kernel interface to read kernel messages. The default is to use _/dev/kmsg_ rather than *syslog*(2) since kernel 3.5.0. + +*-s*, *--buffer-size* _size_:: + Use a buffer of _size_ to query the kernel ring buffer. This is 16392 by default. (The default kernel syslog buffer size was 4096 at first, 8192 since 1.3.54, 16384 since 2.1.113.) If you have set the kernel buffer to be larger than the default, then this option can be used to view the entire buffer. + +*-T*, *--ctime*:: + Print human-readable timestamps. + + + *Be aware that the timestamp could be inaccurate!* The *time* source used for the logs is *not updated after* system *SUSPEND*/*RESUME*. Timestamps are adjusted according to current delta between boottime and monotonic clocks, this works only for messages printed after last resume. + +*--since* _time_:: + Display record since the specified time. The time is possible to specify in absolute way as well as by relative notation (e.g. '1 hour ago'). Be aware that the timestamp could be inaccurate and see *--ctime* for more details. + +*--until* _time_:: + Display record until the specified time. The time is possible to specify in absolute way as well as by relative notation (e.g. '1 hour ago'). Be aware that the timestamp could be inaccurate and see *--ctime* for more details. + +*-t*, *--notime*:: + Do not print kernel's timestamps. + +*--time-format* _format_:: + Print timestamps using the given _format_, which can be *ctime*, *reltime*, *delta* or *iso*. The first three formats are aliases of the time-format-specific options. The *iso* format is a *dmesg* implementation of the ISO-8601 timestamp format. The purpose of this format is to make the comparing of timestamps between two systems, and any other parsing, easy. The definition of the *iso* timestamp is: YYYY-MM-DDHH:MM:SS,<-+>. + + The *iso* format has the same issue as *ctime*: the time may be inaccurate when a system is suspended and resumed. + +*-u*, *--userspace*;; + Print userspace messages. + +*-w*, *--follow*;; + Wait for new messages. This feature is supported only on systems with a readable _/dev/kmsg_ (since kernel 3.5.0). + +*-W*, *--follow-new*;; + Wait and print only new messages. + +*-x*, *--decode*;; + Decode facility and level (priority) numbers to human-readable prefixes. + +*-V*, *--version*;; + Display version information and exit. + +*-h*, *--help*;; + Display help text and exit. + +== COLORS + +Implicit coloring can be disabled by an empty file _/etc/terminal-colors.d/dmesg.disable_. See *terminal-colors.d*(5) for more details about colorization configuration. + +The logical color names supported by *dmesg* are: + +*subsys*:: + The message sub-system prefix (e.g., "ACPI:"). + +*time*:: + The message timestamp. + +*timebreak*:: + The message timestamp in short ctime format in *--reltime* or *--human* output. + +*alert*:: + The text of the message with the alert log priority. + +*crit*:: + The text of the message with the critical log priority. + +*err*:: + The text of the message with the error log priority. + +*warn*:: + The text of the message with the warning log priority. + +*segfault*:: + The text of the message that inform about segmentation fault. + +== EXIT STATUS + +*dmesg* can fail reporting permission denied error. This is usually caused by *dmesg_restrict* kernel setting, please see *syslog*(2) for more details. + +== AUTHORS + +mailto:kzak@redhat.com[Karel Zak] + +*dmesg* was originally written by mailto:tytso@athena.mit.edu[Theodore Ts'o]. + +== SEE ALSO + +*terminal-colors.d*(5), +*syslogd*(8) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/eject.1.adoc b/sys-utils/eject.1.adoc new file mode 100644 index 0000000000..f8811f4ec0 --- /dev/null +++ b/sys-utils/eject.1.adoc @@ -0,0 +1,133 @@ +//// +Copyright (C) 1994-2005 Jeff Tranter (tranter@pobox.com) +Copyright (C) 2012 Karel Zak . + +It may be distributed under the GNU Public License, version 2, or +any higher version. See section COPYING of the GNU Public license +for conditions under which this file may be redistributed. +//// += eject(1) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: eject + +== NAME + +eject - eject removable media + +*eject* [_options_] _device_|_mountpoint_ + +== DESCRIPTION + +*eject* allows removable media (typically a CD-ROM, floppy disk, tape, JAZ, ZIP or USB disk) to be ejected under software control. The command can also control some multi-disc CD-ROM changers, the auto-eject feature supported by some devices, and close the disc tray of some CD-ROM drives. + +The device corresponding to _device_ or _mountpoint_ is ejected. If no name is specified, the default name */dev/cdrom* is used. The device may be addressed by device name (e.g., 'sda'), device path (e.g., '/dev/sda'), UUID=__uuid__ or LABEL=__label__ tags. + +There are four different methods of ejecting, depending on whether the device is a CD-ROM, SCSI device, removable floppy, or tape. By default *eject* tries all four methods in order until it succeeds. + +If a device partition is specified, the whole-disk device is used. + +If the device or a device partition is currently mounted, it is unmounted before ejecting. The eject is processed on exclusive open block device file descriptor if *--no-unmount* or *--force* are not specified. + +== OPTIONS + +*-a*, **--auto on**|*off*:: + This option controls the auto-eject mode, supported by some devices. When enabled, the drive automatically ejects when the device is closed. + +*-c*, *--changerslot* _slot_:: + With this option a CD slot can be selected from an ATAPI/IDE CD-ROM changer. The CD-ROM drive cannot be in use (mounted data CD or playing a music CD) for a change request to work. Please also note that the first slot of the changer is referred to as 0, not 1. + +*-d*, *--default*:: + List the default device name. + +*-F*, *--force*:: + Force eject, don't check device type, don't open device with exclusive lock. The successful result may be false positive on non hot-pluggable devices. + +*-f*, *--floppy*:: + This option specifies that the drive should be ejected using a removable floppy disk eject command. + + *-h*, *--help*:: + Display help text and exit. + +*-i*, **--manualeject on**|*off*:: + This option controls locking of the hardware eject button. When enabled, the drive will not be ejected when the button is pressed. This is useful when you are carrying a laptop in a bag or case and don't want it to eject if the button is inadvertently pressed. + +*-M*, *--no-partitions-unmount*:: + The option tells eject to not try to unmount other partitions on partitioned devices. If another partition is still mounted, the program will not attempt to eject the media. It will attempt to unmount only the device or mountpoint given on the command line. + +*-m*, *--no-unmount*:: + The option tells eject to not try to unmount at all. If this option is not specified than *eject* opens the device with *O_EXCL* flag to be sure that the device is not used (since v2.35). + +*-n*, *--noop*:: + With this option the selected device is displayed but no action is performed. + +*-p*, *--proc*:: + This option allows you to use _/proc/mounts_ instead _/etc/mtab_. It also passes the *-n* option to *umount*(8). + +*-q*, *--tape*:: + This option specifies that the drive should be ejected using a tape drive offline command. + +*-r*, *--cdrom*:: + This option specifies that the drive should be ejected using a CDROM eject command. + +*-s*, *--scsi*:: + This option specifies that the drive should be ejected using SCSI commands. + +*-T*, *--traytoggle*:: + With this option the drive is given a CD-ROM tray close command if it's opened, and a CD-ROM tray eject command if it's closed. Not all devices support this command, because it uses the above CD-ROM tray close command. + +*-t*, *--trayclose*:: + With this option the drive is given a CD-ROM tray close command. Not all devices support this command. + +*-V*, *--version*:: + Display version information and exit. + +*-v*, *--verbose*:: + Run in verbose mode; more information is displayed about what the command is doing. + +*-X*, *--listspeed*:: + With this option the CD-ROM drive will be probed to detect the available speeds. The output is a list of speeds which can be used as an argument of the *-x* option. This only works with Linux 2.6.13 or higher, on previous versions solely the maximum speed will be reported. Also note that some drives may not correctly report the speed and therefore this option does not work with them. + +*-x*, *--cdspeed* _speed_:: + With this option the drive is given a CD-ROM select speed command. The _speed_ argument is a number indicating the desired speed (e.g., 8 for 8X speed), or 0 for maximum data rate. Not all devices support this command and you can only specify speeds that the drive is capable of. Every time the media is changed this option is cleared. This option can be used alone, or with the *-t* and *-c* options. + +== EXIT STATUS + +Returns 0 if operation was successful, 1 if operation failed or command syntax was not valid. + +== NOTES + +*eject* only works with devices that support one or more of the four methods of ejecting. This includes most CD-ROM drives (IDE, SCSI, and proprietary), some SCSI tape drives, JAZ drives, ZIP drives (parallel port, SCSI, and IDE versions), and LS120 removable floppies. Users have also reported success with floppy drives on Sun SPARC and Apple Macintosh systems. If *eject* does not work, it is most likely a limitation of the kernel driver for the device and not the *eject* program itself. + +The *-r*, *-s*, *-f*, and *-q* options allow controlling which methods are used to eject. More than one method can be specified. If none of these options are specified, it tries all four (this works fine in most cases). + +*eject* may not always be able to determine if the device is mounted (e.g., if it has several names). If the device name is a symbolic link, *eject* will follow the link and use the device that it points to. + +If *eject* determines that the device can have multiple partitions, it will attempt to unmount all mounted partitions of the device before ejecting (see also *--no-partitions-unmount*). If an unmount fails, the program will not attempt to eject the media. + +You can eject an audio CD. Some CD-ROM drives will refuse to open the tray if the drive is empty. Some devices do not support the tray close command. + +If the auto-eject feature is enabled, then the drive will always be ejected after running this command. Not all Linux kernel CD-ROM drivers support the auto-eject mode. There is no way to find out the state of the auto-eject mode. + +You need appropriate privileges to access the device files. Running as root is required to eject some devices (e.g., SCSI devices). + +== AUTHORS + +mailto:tranter@pobox.com[Jeff Tranter] - original author. mailto:kzak@redhat.com[Karel Zak] and mailto:mluscon@redhat.com[Michal Luscon] - util-linux version. + +== SEE ALSO + +*findmnt*(8), +*lsblk*(8), +*mount*(8), +*umount*(8) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/fallocate.1.adoc b/sys-utils/fallocate.1.adoc new file mode 100644 index 0000000000..670eba61cc --- /dev/null +++ b/sys-utils/fallocate.1.adoc @@ -0,0 +1,93 @@ += fallocate(1) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: fallocate + +== NAME + +fallocate - preallocate or deallocate space to a file + +== SYNOPSIS + +*fallocate* [*-c*|*-p*|*-z*] [*-o* _offset_] *-l* _length_ [*-n*] _filename_ + +*fallocate* *-d* [*-o* _offset_] [*-l* _length_] _filename_ + +*fallocate* *-x* [*-o* _offset_] *-l* _length filename_ + +== DESCRIPTION + +*fallocate* is used to manipulate the allocated disk space for a file, either to deallocate or preallocate it. For filesystems which support the fallocate system call, preallocation is done quickly by allocating blocks and marking them as uninitialized, requiring no IO to the data blocks. This is much faster than creating a file by filling it with zeroes. + +The exit status returned by *fallocate* is 0 on success and 1 on failure. + +== OPTIONS + +The _length_ and _offset_ arguments may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB, and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB") or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB, and YB. + +The options *--collapse-range*, *--dig-holes*, *--punch-hole*, and *--zero-range* are mutually exclusive. + +*-c*, *--collapse-range*:: + Removes a byte range from a file, without leaving a hole. The byte range to be collapsed starts at _offset_ and continues for _length_ bytes. At the completion of the operation, the contents of the file starting at the location __offset__+_length_ will be appended at the location _offset_, and the file will be _length_ bytes smaller. The option *--keep-size* may not be specified for the collapse-range operation. + + Available since Linux 3.15 for ext4 (only for extent-based files) and XFS. + + A filesystem may place limitations on the granularity of the operation, in order to ensure efficient implementation. Typically, offset and len must be a multiple of the filesystem logical block size, which varies according to the filesystem type and configuration. If a filesystem has such a requirement, the operation will fail with the error EINVAL if this requirement is violated. + +*-d*, *--dig-holes*:: + Detect and dig holes. This makes the file sparse in-place, without using extra disk space. The minimum size of the hole depends on filesystem I/O block size (usually 4096 bytes). Also, when using this option, *--keep-size* is implied. If no range is specified by *--offset* and *--length*, then the entire file is analyzed for holes. + + You can think of this option as doing a "*cp --sparse*" and then renaming the destination file to the original, without the need for extra disk space. + + See *--punch-hole* for a list of supported filesystems. + +*-i*, *--insert-range*:: + Insert a hole of _length_ bytes from _offset_, shifting existing data. + +*-l*, *--length* _length_:: + Specifies the length of the range, in bytes. + +*-n*, *--keep-size*:: + Do not modify the apparent length of the file. This may effectively allocate blocks past EOF, which can be removed with a truncate. + +*-o*, *--offset* _offset_:: + Specifies the beginning offset of the range, in bytes. + +*-p*, *--punch-hole*:: + Deallocates space (i.e., creates a hole) in the byte range starting at _offset_ and continuing for _length_ bytes. Within the specified range, partial filesystem blocks are zeroed, and whole filesystem blocks are removed from the file. After a successful call, subsequent reads from this range will return zeroes. This option may not be specified at the same time as the *--zero-range* option. Also, when using this option, *--keep-size* is implied. + + Supported for XFS (since Linux 2.6.38), ext4 (since Linux 3.0), Btrfs (since Linux 3.7), tmpfs (since Linux 3.5) and gfs2 (since Linux 4.16). + +*-v*, *--verbose*:: + Enable verbose mode. + +*-x*, *--posix*:: + Enable POSIX operation mode. In that mode allocation operation always completes, but it may take longer time when fast allocation is not supported by the underlying filesystem. + +*-z*, *--zero-range*:: + Zeroes space in the byte range starting at _offset_ and continuing for _length_ bytes. Within the specified range, blocks are preallocated for the regions that span the holes in the file. After a successful call, subsequent reads from this range will return zeroes. + + Zeroing is done within the filesystem preferably by converting the range into unwritten extents. This approach means that the specified range will not be physically zeroed out on the device (except for partial blocks at the either end of the range), and I/O is (otherwise) required only to update metadata. + + Option *--keep-size* can be specified to prevent file length modification. + + Available since Linux 3.14 for ext4 (only for extent-based files) and XFS. + +*-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== AUTHORS + +mailto:sandeen@redhat.com[Eric Sandeen] + +mailto:kzak@redhat.com[Karel Zak] + +== SEE ALSO + +*truncate*(1), +*fallocate*(2), +*posix_fallocate*(3) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/flock.1.adoc b/sys-utils/flock.1.adoc new file mode 100644 index 0000000000..36690c825a --- /dev/null +++ b/sys-utils/flock.1.adoc @@ -0,0 +1,136 @@ +//// +Copyright 2003-2006 H. Peter Anvin - All Rights Reserved + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom +the Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall +be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. +//// += flock(1) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: flock + +== NAME + +flock - manage locks from shell scripts + +== SYNOPSIS + +*flock* [_options_] _file_|_directory_ _command_ [_arguments_] + +*flock* [_options_] _file_|_directory_ *-c* _command_ + +*flock* [_options_] _number_ + +== DESCRIPTION + +This utility manages *flock*(2) locks from within shell scripts or from the command line. + +The first and second of the above forms wrap the lock around the execution of a _command_, in a manner similar to *su*(1) or *newgrp*(1). They lock a specified _file_ or _directory_, which is created (assuming appropriate permissions) if it does not already exist. By default, if the lock cannot be immediately acquired, *flock* waits until the lock is available. + +The third form uses an open file by its file descriptor _number_. See the examples below for how that can be used. + +== OPTIONS + +*-c*, *--command* _command_:: + Pass a single _command_, without arguments, to the shell with *-c*. + +*-E*, *--conflict-exit-code* _number_:: + The exit status used when the *-n* option is in use, and the conflicting lock exists, or the *-w* option is in use, and the timeout is reached. The default value is *1*. The _number_ has to be in the range of 0 to 255. + +*-F*, *--no-fork*:: + Do not fork before executing _command_. Upon execution the flock process is replaced by _command_ which continues to hold the lock. This option is incompatible with *--close* as there would otherwise be nothing left to hold the lock. + +*-e*, *-x*, *--exclusive*:: + Obtain an exclusive lock, sometimes called a write lock. This is the default. + +*-n*, *--nb*, *--nonblock*:: + Fail rather than wait if the lock cannot be immediately acquired. See the *-E* option for the exit status used. + +*-o*, *--close*:: + Close the file descriptor on which the lock is held before executing _command_. This is useful if _command_ spawns a child process which should not be holding the lock. + +*-s*, *--shared*:: + Obtain a shared lock, sometimes called a read lock. + +*-u*, *--unlock*:: + Drop a lock. This is usually not required, since a lock is automatically dropped when the file is closed. However, it may be required in special cases, for example if the enclosed command group may have forked a background process which should not be holding the lock. + +*-w*, *--wait*, *--timeout* _seconds_:: + Fail if the lock cannot be acquired within _seconds_. Decimal fractional values are allowed. See the *-E* option for the exit status used. The zero number of _seconds_ is interpreted as *--nonblock*. + +*--verbose*:: + Report how long it took to acquire the lock, or why the lock could not be obtained. + +*-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== EXIT STATUS + +The command uses exit status values for everything, except when using either of the options *-n* or *-w* which report a failure to acquire the lock with an exit status given by the *-E* option, or 1 by default. The exit status given by *-E* has to be in the range of 0 to 255. + +When using the _command_ variant, and executing the child worked, then the exit status is that of the child command. + +== EXAMPLES + +Note that "shell> " in examples is a command line prompt. + +shell1> flock /tmp -c cat; shell2> flock -w .007 /tmp -c echo; /bin/echo $?:: + Set exclusive lock to directory /tmp and the second command will fail. + +shell1> flock -s /tmp -c cat; shell2> flock -s -w .007 /tmp -c echo; /bin/echo $?:: + Set shared lock to directory /tmp and the second command will not fail. Notice that attempting to get exclusive lock with second command would fail. + +shell> flock -x local-lock-file echo 'a b c':: + Grab the exclusive lock "local-lock-file" before running echo with 'a b c'. + +(; flock -n 9 || exit 1; # ... commands executed under lock ...; ) 9>/var/lock/mylockfile:: + The form is convenient inside shell scripts. The mode used to open the file doesn't matter to *flock*; using _>_ or _>>_ allows the lockfile to be created if it does not already exist, however, write permission is required. Using _<_ requires that the file already exists but only read permission is required. + +[ $\{FLOCKER} != $0 ] && exec env FLOCKER="$0 flock -en $0 $0 $@ || ::: + This is useful boilerplate code for shell scripts. Put it at the top of the shell script you want to lock and it'll automatically lock itself on the first run. If the env var *$FLOCKER* is not set to the shell script that is being run, then execute *flock* and grab an exclusive non-blocking lock (using the script itself as the lock file) before re-execing itself with the right arguments. It also sets the FLOCKER env var to the right value so it doesn't run again. + +shell> exec 4<>/var/lock/mylockfile; shell> flock -n 4:: + This form is convenient for locking a file without spawning a subprocess. The shell opens the lock file for reading and writing as file descriptor 4, then flock is used to lock the descriptor. + +== AUTHORS + +mailto:hpa@zytor.com[H. Peter Anvin] + +== COPYRIGHT + +Copyright © 2003-2006 H. Peter Anvin. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +== SEE ALSO + +*flock*(2) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/fsfreeze.8.adoc b/sys-utils/fsfreeze.8.adoc new file mode 100644 index 0000000000..3482967d0e --- /dev/null +++ b/sys-utils/fsfreeze.8.adoc @@ -0,0 +1,65 @@ += fsfreeze(8) +:doctype: manpage +:man manual: User commands +:man source: util-linux {release-version} +:page-layout: base +:command: fsfreeze + +== NAME + +fsfreeze - suspend access to a filesystem (Ext3/4, ReiserFS, JFS, XFS) + +== SYNOPSIS + +*fsfreeze* *--freeze*|*--unfreeze* _mountpoint_ + +== DESCRIPTION + +*fsfreeze* suspends or resumes access to a filesystem. + +*fsfreeze* halts any new access to the filesystem and creates a stable image on disk. *fsfreeze* is intended to be used with hardware RAID devices that support the creation of snapshots. + +*fsfreeze* is unnecessary for *device-mapper* devices. The device-mapper (and LVM) automatically freezes a filesystem on the device when a snapshot creation is requested. For more details see the *dmsetup*(8) man page. + +The _mountpoint_ argument is the pathname of the directory where the filesystem is mounted. The filesystem must be mounted to be frozen (see *mount*(8)). + +Note that access-time updates are also suspended if the filesystem is mounted with the traditional atime behavior (mount option *strictatime*, for more details see *mount*(8)). + +== OPTIONS + +*-f*, *--freeze*:: + This option requests the specified a filesystem to be frozen from new modifications. When this is selected, all ongoing transactions in the filesystem are allowed to complete, new write system calls are halted, other calls which modify the filesystem are halted, and all dirty data, metadata, and log information are written to disk. Any process attempting to write to the frozen filesystem will block waiting for the filesystem to be unfrozen. + + Note that even after freezing, the on-disk filesystem can contain information on files that are still in the process of unlinking. These files will not be unlinked until the filesystem is unfrozen or a clean mount of the snapshot is complete. + +*-u*, *--unfreeze*:: + This option is used to un-freeze the filesystem and allow operations to continue. Any filesystem modifications that were blocked by the freeze are unblocked and allowed to complete. + +*-V*, *--version*:: + Display version information and exit. + +*-h*, *--help*:: + Display help text and exit. + +== FILESYSTEM SUPPORT + +This command will work only if filesystem supports has support for freezing. List of these filesystems include (2016-12-18) *btrfs*, *ext2/3/4*, *f2fs*, *jfs*, *nilfs2*, *reiserfs*, and *xfs*. Previous list may be incomplete, as more filesystems get support. If in doubt easiest way to know if a filesystem has support is create a small loopback mount and test freezing it. + +== NOTES + +This man page is based on *xfs_freeze*(8). + +== AUTHORS + +Written by Hajime Taira. + +== SEE ALSO + +*mount*(8) + +include::../man-common/bugreports.adoc[] + +include::../man-common/footer.adoc[] + +ifdef::translation[] +include::../man-common/translation.adoc[] +endif::[] diff --git a/sys-utils/fstab.5.adoc b/sys-utils/fstab.5.adoc new file mode 100644 index 0000000000..5c0141c33a --- /dev/null +++ b/sys-utils/fstab.5.adoc @@ -0,0 +1,160 @@ +//// +Copyright (c) 1980, 1989, 1991 The Regents of the University of California. +All rights reserved. + +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. +3. All advertising materials mentioning features or use of this software + must display the following acknowledgement: +This product includes software developed by the University of +California, Berkeley and its contributors. +4. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. + + @(#)fstab.5 6.5 (Berkeley) 5/10/91 +//// += fstab(5) +:doctype: manpage +:man manual: File formats +:man source: util-linux {release-version} +:page-layout: base +:configfile: fstab + +== NAME + +fstab - static information about the filesystems + +== SYNOPSIS + +_/etc/fstab_ + +== DESCRIPTION + +The file *fstab* contains descriptive information about the filesystems the system can mount. *fstab* is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. The order of records in *fstab* is important because fsck8, mount8, and umount8 sequentially iterate through *fstab* doing their thing. + +Each filesystem is described on a separate line. Fields on each line are separated by tabs or spaces. Lines starting with '#' are comments. Blank lines are ignored. + +The following is a typical example of an *fstab* entry: + +.... +LABEL=t-home2 /home ext4 defaults,auto_da_alloc 0 2 +.... + +=== The first field (_fs_spec_). + +____ +This field describes the block special device, remote filesystem or filesystem image for loop device to be mounted or swap file or swap partition to be enabled. + +For ordinary mounts, it will hold (a link to) a block special device node (as created by *mknod*(2)) for the device to be mounted, like _/dev/cdrom_ or _/dev/sdb7_. For NFS mounts, this field is _:_, e.g., _knuth.aeb.nl:/_. For filesystems with no storage, any string can be used, and will show up in *df*(1) output, for example. Typical usage is _proc_ for *procfs*; _mem_, _none_, or _tmpfs_ for *tmpfs*. Other special filesystems, like *udev* and *sysfs*, are typically not listed in *fstab*. + +LABEL=