From b7dfe65b3f39bcfd2736b31bbdd02e374690e4c1 Mon Sep 17 00:00:00 2001 From: "A. Wilcox" Date: Fri, 15 May 2020 23:33:47 -0500 Subject: DiskMan: Add manual pages --- diskman/CMakeLists.txt | 1 + diskman/man/Horizon::DiskMan.3 | 33 +++++++ diskman/man/Horizon::DiskMan::Disk.3 | 106 +++++++++++++++++++++ .../man/Horizon::DiskMan::Disk::contiguous_block.3 | 1 + diskman/man/Horizon::DiskMan::Disk::dev_path.3 | 1 + diskman/man/Horizon::DiskMan::Disk::free_space.3 | 1 + diskman/man/Horizon::DiskMan::Disk::fs_label.3 | 1 + diskman/man/Horizon::DiskMan::Disk::fs_type.3 | 77 +++++++++++++++ diskman/man/Horizon::DiskMan::Disk::has_fs.3 | 1 + diskman/man/Horizon::DiskMan::Disk::has_label.3 | 1 + diskman/man/Horizon::DiskMan::Disk::label.3 | 94 ++++++++++++++++++ diskman/man/Horizon::DiskMan::Disk::model.3 | 1 + diskman/man/Horizon::DiskMan::Disk::name.3 | 91 ++++++++++++++++++ diskman/man/Horizon::DiskMan::Disk::node.3 | 1 + diskman/man/Horizon::DiskMan::Disk::partitions.3 | 55 +++++++++++ .../Horizon::DiskMan::Disk::reload_partitions.3 | 1 + diskman/man/Horizon::DiskMan::Disk::sector_size.3 | 1 + diskman/man/Horizon::DiskMan::Disk::serial.3 | 1 + diskman/man/Horizon::DiskMan::Disk::total_size.3 | 78 +++++++++++++++ diskman/man/Horizon::DiskMan::DiskMan.3 | 74 ++++++++++++++ diskman/man/Horizon::DiskMan::Partition.3 | 51 ++++++++++ 21 files changed, 671 insertions(+) create mode 100644 diskman/man/Horizon::DiskMan.3 create mode 100644 diskman/man/Horizon::DiskMan::Disk.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::contiguous_block.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::dev_path.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::free_space.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::fs_label.3 create mode 100644 diskman/man/Horizon::DiskMan::Disk::fs_type.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::has_fs.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::has_label.3 create mode 100644 diskman/man/Horizon::DiskMan::Disk::label.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::model.3 create mode 100644 diskman/man/Horizon::DiskMan::Disk::name.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::node.3 create mode 100644 diskman/man/Horizon::DiskMan::Disk::partitions.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::reload_partitions.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::sector_size.3 create mode 120000 diskman/man/Horizon::DiskMan::Disk::serial.3 create mode 100644 diskman/man/Horizon::DiskMan::Disk::total_size.3 create mode 100644 diskman/man/Horizon::DiskMan::DiskMan.3 create mode 100644 diskman/man/Horizon::DiskMan::Partition.3 (limited to 'diskman') diff --git a/diskman/CMakeLists.txt b/diskman/CMakeLists.txt index ea0c5fe..1a48ade 100644 --- a/diskman/CMakeLists.txt +++ b/diskman/CMakeLists.txt @@ -20,3 +20,4 @@ target_link_libraries(diskman ${FDISK_LIBRARIES} ${LIBUDEV_LIBRARIES}) install(TARGETS diskman DESTINATION lib) install(FILES ${DISKMAN_INCLUDE} DESTINATION include/diskman) +install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/man/ DESTINATION share/man/man3) diff --git a/diskman/man/Horizon::DiskMan.3 b/diskman/man/Horizon::DiskMan.3 new file mode 100644 index 0000000..5106480 --- /dev/null +++ b/diskman/man/Horizon::DiskMan.3 @@ -0,0 +1,33 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan +.Nd namespace for the Horizon Disk Manager +.Sh SYNOPSIS +.In diskman/diskman.hh +.Sh DESCRIPTION +The +.Nm +namespace contains three classes for inspecting the fixed disks present on a +computer: +.Cm Horizon::DiskMan::DiskMan , +.Cm Horizon::DiskMan::Disk , +and +.Cm Horizon::DiskMan::Partition . +.Pp +You should only create instances of +.Cm Horizon::DiskMan::DiskMan ; +the DiskMan class will provide you with the relevant instances of Disk and +Parition. +.Sh EXAMPLES +See the class manual pages for in-depth examples. +.Sh SEE ALSO +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Disk.3 b/diskman/man/Horizon::DiskMan::Disk.3 new file mode 100644 index 0000000..edd7b42 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk.3 @@ -0,0 +1,106 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Disk 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Disk +.Nd disk class of the Horizon Disk Manager +.Sh SYNOPSIS +.In diskman/disk.hh +.Cm class Horizon::DiskMan::Disk; +.Sh DESCRIPTION +The +.Nm +class provides information about a fixed disk attached to the system. +.Ss Class methods - Identity +The +.Nm +class provides the following accessors for information about the identity of +the disk: +.Bl -tag -width Ds +.It Cm const std::string name() const +Retrieve the disk's name. For instance, +.Qq sda +or +.Qq nvme0n1 . +.It Cm const std::string model() const +Retrieve the disk's model. This is specified by the vendor. Typically, this +is the model number of the disk. Some vendors include the vendor name in the +model field. +.It Cm const std::string serial() const +Retrieve the disk's serial number. This may be equivalent to the model name, +if the vendor did not specify a serial number. +.It Cm const std::string node() const +Retrieve the absolute path of the device node for this disk. For instance, +.Qq /dev/sda . +.El +.Ss Class methods - Label +The +.Nm +class provides the following accessors for information about the label +present on the disk, if any: +.Bl -tag -width Ds +.It Cm bool has_label() const +Returns true if this disk has a disk label attached. +.It Cm enum Label label() const +Retrieve the type of disk label in use on this disk. Calling this function +is only valid if has_label() is true. +.El +.Ss Class methods - File system +The +.Nm +class provides the following accessors for information about the file system +present on the disk, if any: +.Bl -tag -width Ds +.It Cm bool has_fs() const +Returns true if this disk has a file system written to it. Note that this +means that the file system is directly written to the disk; it is not +contained within a partition. +.It Cm const std::string fs_type() const +Retrieve the type of file system written on this disk. Calling this function +is only valid if has_fs() is true. +.It Cm const std::string fs_label() const +Retrieve the label of the file system written on this disk. Calling this +function is only valid if has_fs() is true. +.El +.Ss Class methods - Sizing +The +.Nm +class provides the following accessors for information about the size of the +disk: +.Bl -tag -width Ds +.It Cm uint32_t total_size() const +Retrieve the total size of the disk in mebibytes (MiB). +.It Cm uint32_t free_space() const +Retrieve the amount of free space available on the disk in mebibytes (MiB). +.It Cm uint32_t contiguous_block() const +Retrieve the size of the largest contiguous block of free space on the disk +in mebibytes (MiB). +.It Cm uint32_t sector_size() const +Retrieve the sector size of the disk in bytes. +.El +.Ss Class methods - Partitions +The +.Nm +class provides the following accessors for retrieving partitions associated +with the disk's label, if present: +.Bl -tag -width Ds +.It Cm const std::vector partitions() const +Retrieve the partitions contained in the label, if any. Calling this +function is only valid is has_label() is true. +.It Cm bool reload_partitions() +Attempt to (re)load the partition table from the disk. Returns true if the +partition table was loaded successfully; otherwise, returns false. +.El +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk::name 3 , +.Xr Horizon::DiskMan::Disk::label 3 , +.Xr Horizon::DiskMan::Disk::fs_type 3 , +.Xr Horizon::DiskMan::Disk::total_size 3 , +.Xr Horizon::DiskMan::Disk::partitions 3 , +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Disk::contiguous_block.3 b/diskman/man/Horizon::DiskMan::Disk::contiguous_block.3 new file mode 120000 index 0000000..b22550c --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::contiguous_block.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::total_size.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::dev_path.3 b/diskman/man/Horizon::DiskMan::Disk::dev_path.3 new file mode 120000 index 0000000..6a0d00a --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::dev_path.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::name.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::free_space.3 b/diskman/man/Horizon::DiskMan::Disk::free_space.3 new file mode 120000 index 0000000..b22550c --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::free_space.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::total_size.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::fs_label.3 b/diskman/man/Horizon::DiskMan::Disk::fs_label.3 new file mode 120000 index 0000000..d08c496 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::fs_label.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::fs_type.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::fs_type.3 b/diskman/man/Horizon::DiskMan::Disk::fs_type.3 new file mode 100644 index 0000000..35ee55e --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::fs_type.3 @@ -0,0 +1,77 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Disk::fs_type 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Disk::has_fs , +.Nm Horizon::DiskMan::Disk::fs_type , +.Nm Horizon::DiskMan::Disk::fs_label +.Nd retrieve file system information for a disk +.Sh SYNOPSIS +.In diskman/disk.hh +.Cm using Horizon::DiskMan::Disk; +.Ft bool +.Fo Disk::has_fs +.Fc +.Ft const std::string +.Fo Disk::fs_type +.Fc +.Ft const std::string +.Fo Disk::fs_label +.Fc +.Sh DESCRIPTION +The +.Fn Disk::has_fs +function returns whether the disk has a file system written directly to it +(without a disk label or partition). +.Pp +The +.Fn Disk::fs_type +function provides the type of file system present and the +.Fn Disk::fs_label +function provides the file system's label (if set). Both of these functions +are only valid to be called if +.Fn Disk::has_fs +returns true. +.Sh RETURN VALUES +The +.Fn Disk::has_fs +function returns true if the disk has a file system written to it without a +disk label. +.Pp +The +.Fn Disk::fs_type +and +.Fn Disk::fs_label +functions return std::string containing the requested information, if +.Fn Disk::has_fs +returns true. +.Sh EXAMPLES +The following is a simple utility that will print the label and file system +type for each disk attached to the system that has one: +.Bd -literal -offset indent +#include "diskman/diskman.hh" +#include + +int main(void) { + Horizon::DiskMan::DiskMan diskMan; + auto disks = diskMan.find_disks(false, false, true); + for(auto &disk : disks) { + std::cout << "Disk: " << disk.name() << std::endl; + std::cout << "FS: "; + if(disk.has_fs()) { + std::cout << "\\"" << disk.fs_label() << "\\" (" << disk.fs_type() << ")"; + } else std::cout << "No"; + std::cout << std::endl; + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Disk::has_fs.3 b/diskman/man/Horizon::DiskMan::Disk::has_fs.3 new file mode 120000 index 0000000..d08c496 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::has_fs.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::fs_type.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::has_label.3 b/diskman/man/Horizon::DiskMan::Disk::has_label.3 new file mode 120000 index 0000000..cc993b2 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::has_label.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::label.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::label.3 b/diskman/man/Horizon::DiskMan::Disk::label.3 new file mode 100644 index 0000000..f15452e --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::label.3 @@ -0,0 +1,94 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Disk::label 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Disk::has_label , +.Nm Horizon::DiskMan::Disk::label +.Nd retrieve labeling information for a disk +.Sh SYNOPSIS +.In diskman/disk.hh +.Cm using Horizon::DiskMan::Disk; +.Ft bool +.Fo Disk::has_label +.Fc +.Ft enum Label +.Fo Disk::label +.Fc +.Sh DESCRIPTION +The +.Fn Disk::has_label +function returns whether a given disk has a label written to it. Note that +even if +.Fn Disk::has_label +returns false, the disk may still have a label. The DiskMan library is not +able to detect and read every type of disk label in the wild. For maximal +safety, you may wish to read the first few sectors of the disk (and use the +.Xr Horizon::DiskMan::Disk::has_fs 3 +function to determine if a file system is present without a label) before +considering the disk empty. +.Pp +The +.Fn Disk::label +function returns the type of label present on the disk. Calling this +function is only valid if +.Fn Disk::has_label +returns true. +.Sh RETURN VALUES +The +.Fn Disk::has_label +function returns a boolean which determines whether a given disk has a +recognised disk label written to it. +.Pp +The +.Fn Disk::label +functions returns a value of type enum Disk::Label, which contains at least +the following values: +.Bl -tag -width Ds +.It GPT +GUID Partition Table. +.It MBR +Master Boot Record. +.It APM +Apple Partition Map. +.It Unknown +Unknown disk label type. +.El +.Sh EXAMPLES +The following is a simple utility that prints the label type of every +labelled disk present on the system: +.Bd -literal -offset ident +#include +#include + +using Horizon::DiskMan::Disk; +using Horizon::DiskMan::DiskMan; + +const std::string label_name(Disk::Label label) { + switch(label) { + case Disk::APM: return "APM"; + case Disk::MBR: return "MBR"; + case Disk::GPT: return "GPT"; + } + return "Unknown"; +} + +int main(void) { + DiskMan dm; + auto disks = dm.find_disks(false, false, false); + for(auto &disk : disks) { + std::cout << "Disk: " << disk.name() << std::endl; + std::cout << "Label: " << (disk.has_label() ? label_name(disk.label()) : "No") << std::endl; + std::cout << std::endl; + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Disk::model.3 b/diskman/man/Horizon::DiskMan::Disk::model.3 new file mode 120000 index 0000000..6a0d00a --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::model.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::name.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::name.3 b/diskman/man/Horizon::DiskMan::Disk::name.3 new file mode 100644 index 0000000..aa26ab6 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::name.3 @@ -0,0 +1,91 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Disk::name 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Disk::name , +.Nm Horizon::DiskMan::Disk::model , +.Nm Horizon::DiskMan::Disk::serial , +.Nm Horizon::DiskMan::Disk::node , +.Nm Horizon::DiskMan::Disk::dev_path +.Nd retrieve properties of a disk +.Sh SYNOPSIS +.In diskman/disk.hh +.Cm using Horizon::DiskMan::Disk; +.Ft const std::string +.Fo Disk::name +.Fc +.Ft const std::string +.Fo Disk::model +.Fc +.Ft const std::string +.Fo Disk::serial +.Fc +.Ft const std::string +.Fo Disk::node +.Fc +.Ft const std::string +.Fo Disk::dev_path +.Fc +.Sh DESCRIPTION +The +.Fn Disk::name +function provides the name of the fixed disk. This is equivalent to calling +.Xr basename 3 +on +.Fn Disk::node . +.Pp +The +.Fn Disk::model +function provides the vendor's given model number for the fixed disk. This +is a free-form identification string provided by the disk's vendor and could +be blank or meaningless depending on the vendor. Some external disk +enclosures do not support retrieval of disk model numbers. +.Pp +The +.Fn Disk::serial +function provides the vendor's given serial number for the fixed disk. Like +.Fn Disk::model , +this is a free-form string provided by the disk's vendor. You should not +rely on this string being unique in a given system; some vendors simply copy +the model number as the serial number. When the given serial number is non- +blank and unequal to the model number, it may be unique. +.Pp +The +.Fn Disk::node +function provides the absolute path of the device node for this disk. +.Pp +The +.Fn Disk::dev_path +function provides the absolute path to the sysfs node for this disk. +.Sh RETURN VALUES +These routines return the requested information as a C++ std::string. Values +are not converted from their native representation. Virtually all disks the +authors have seen use US-ASCII or UTF-8, but there may be a disk in the wild +that uses a legacy codepage. +.Sh EXAMPLES +The following is a simple utility that returns the model and device node of +all disks present in a system: +.Bd -literal -offset indent +#include +#include + +using Horizon::DiskMan::DiskMan; + +int main(void) { + DiskMan dm; + auto disks = dm.find_disks(false, false, false); + for(auto &disk : disks) { + std::cout << "Disk " << disk.model() << " found at: " << disk.node() << std::endl; + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Disk::node.3 b/diskman/man/Horizon::DiskMan::Disk::node.3 new file mode 120000 index 0000000..6a0d00a --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::node.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::name.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::partitions.3 b/diskman/man/Horizon::DiskMan::Disk::partitions.3 new file mode 100644 index 0000000..2cb787e --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::partitions.3 @@ -0,0 +1,55 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Disk::partitions 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Disk::partitions , +.Nm Horizon::DiskMan::Disk::reload_partitions +.Nd retrieve partitioning information for a disk +.Sh SYNOPSIS +.In diskman/disk.hh +.Cm using Horizon::DiskMan::Disk; +.Cm using Horizon::DiskMan::Partition; +.Ft const std::vector +.Fo Disk::partitions +.Fc +.Ft bool +.Fo Disk::reload_partitions +.Fc +.Sh DESCRIPTION +The +.Fn Disk::partitions +function returns a vector containing the partitions present in the disk's +label. Calling this function is only valid if +.Xr Horizon::DiskMan::Disk::has_label 3 +returns true. +.Pp +The +.Fn Disk::reload_partitions +function will re-read the disk's label, returning true if the label was read +successfully. +.Sh RETURN VALUES +The +.Fn Disk::partitions +function returns a +.Xr std::vector 3 +containing +.Xr Horizon::DiskMan::Partition 3 +objects corresponding to the partitions in the disk's label. If the disk's +label is empty, the vector will be empty. +.Pp +The +.Fn Disk::reload_partitions +function returns true if the disk label was successfully read and parsed. If +the disk label could not be read or parsed, +.Fn Disk::reload_partitions +will return false and the current partition list (if any) is retained. +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk::has_label 3 , +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Disk::reload_partitions.3 b/diskman/man/Horizon::DiskMan::Disk::reload_partitions.3 new file mode 120000 index 0000000..e03dc04 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::reload_partitions.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::partitions.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::sector_size.3 b/diskman/man/Horizon::DiskMan::Disk::sector_size.3 new file mode 120000 index 0000000..b22550c --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::sector_size.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::total_size.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::serial.3 b/diskman/man/Horizon::DiskMan::Disk::serial.3 new file mode 120000 index 0000000..6a0d00a --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::serial.3 @@ -0,0 +1 @@ +Horizon::DiskMan::Disk::name.3 \ No newline at end of file diff --git a/diskman/man/Horizon::DiskMan::Disk::total_size.3 b/diskman/man/Horizon::DiskMan::Disk::total_size.3 new file mode 100644 index 0000000..cc2573b --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Disk::total_size.3 @@ -0,0 +1,78 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Disk::total_size 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Disk::total_size , +.Nm Horizon::DiskMan::Disk::free_space , +.Nm Horizon::DiskMan::Disk::contiguous_block , +.Nm Horizon::DiskMan::Disk::sector_size +.Nd retrieve sizing information for a disk +.Sh SYNOPSIS +.In diskman/disk.hh +.Cm using Horizon::DiskMan::Disk; +.Ft uint32_t +.Fo Disk::total_size +.Fc +.Ft uint32_t +.Fo Disk::free_space +.Fc +.Ft uint32_t +.Fo Disk::contiguous_block +.Fc +.Ft uint32_t +.Fo Disk::sector_size +.Fc +.Sh DESCRIPTION +The +.Fn Disk::total_size +function provides the size of the specified disk. +.Pp +The +.Fn Disk::free_space +and +.Fn Disk::contiguous_block +functions provide the amount of total free space, and the largest contiguous +block of free space, respectively. +.Pp +The +.Fn Disk::sector_size +function provides the disk's sector size. +.Sh RETURN VALUES +The +.Fn Disk::total_size , +.Fn Disk::free_space , +and +.Fn Disk::contiguous_block +functions return the requested information in mebibytes (MiB). +.Pp +The +.Fn Disk::sector_size +function returns the sector size in bytes. +.Sh EXAMPLES +The following is a simple utility that prints the name, total size, and free +space for each disk attached to the system: +.Bd -literal -offset indent +#include +#include + +int main(void) { + Horizon::DiskMan::DiskMan dm; + auto disks = dm.find_disks(false, false, false); + for(auto &disk : disks) { + std::cout << "Disk: " << disk.name() << ":" << std::endl; + std::cout << std::to_string(disk.total_size()) << " MiB total"; + std::cout << " (" << std::to_string(disk.free_space()) << " MiB free; "; + std::cout << std::to_string(disk.contiguous_block()) << " MiB largest contiguous block)" << std::endl; + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::DiskMan 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::DiskMan.3 b/diskman/man/Horizon::DiskMan::DiskMan.3 new file mode 100644 index 0000000..64710c7 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::DiskMan.3 @@ -0,0 +1,74 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::DiskMan 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::DiskMan +.Nd main class of the Horizon Disk Manager +.Sh SYNOPSIS +.In diskman/diskman.hh +.Cm using Horizon::DiskMan::DiskMan; +.Ft vector +.Fo DiskMan::find_disks +.Fa "bool include_part = true" "bool include_vg = true" "bool include_lvm = false" +.Fc +.Sh DESCRIPTION +The +.Nm +class provides a facility for inspecting the fixed disk(s) present on a +computer. +.Pp +Calling the +.Fn DiskMan::find_disks +function will return a vector of +.Cm Horizon::DiskMan::Disk +containing all fixed disks presently attached to the system. The +.Fn DiskMan::find_disks +function allows you to control the data returned with three arguments: +.Fa include_part , +which if true will include partition information when a fixed disk contains +a readable disk label; +.Fa include_vg , +which if true will include each LVM volume group as a Disk; and +.Fa include_lvm , +which if true will include each LVM logical volume as a Disk. +.Pp +You should only create instances of +.Cm Horizon::DiskMan::DiskMan ; +the DiskMan class will provide you with the relevant instances of Disk and +Parition. +.Sh RETURN VALUES +The +.Fn DiskMan::find_disks +function returns a +.Cm std::vector +of +.Cm Horizon::DiskMan::Disk +objects describing all fixed disks attached to the system. +.Sh EXAMPLES +.Bd -literal -offset indent +#include +#include + +using Horizon::DiskMan::DiskMan; + +int main(void) { + DiskMan diskMan; + auto disks = diskMan.find_disks(false, false, false); + std::cout << "Found " << std::to_string(disks.size()) << " disk(s):" << std::endl; + for(auto &disk : disks) { + std::cout << "==========================================" << std::endl; + std::cout << "Disk: " << disk.name() << " (" << disk.model() << ")"; + std::cout << " at " << disk.dev_path() << std::endl; + std::cout << "==========================================" << std::endl; + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::Partition 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org diff --git a/diskman/man/Horizon::DiskMan::Partition.3 b/diskman/man/Horizon::DiskMan::Partition.3 new file mode 100644 index 0000000..78d3748 --- /dev/null +++ b/diskman/man/Horizon::DiskMan::Partition.3 @@ -0,0 +1,51 @@ +.Dd May 15, 2020 +.Dt Horizon::DiskMan::Partition 3 +.Os "Adélie Linux" +.Sh NAME +.Nm Horizon::DiskMan::Partition +.Nd partition class of the Horizon Disk Manager +.Sh SYNOPSIS +.In diskman/partition.hh +.Cm class Horizon::DiskMan::Partition; +.Ft uint64_t +.Fo Partition::size +.Fc +.Ft const std::string +.Fo Partition::fs_type +.Fc +.Ft const std::string +.Fo Partition::fs_label +.Fc +.Sh DESCRIPTION +The +.Nm Horizon::DiskMan::Partition +class provides information about a partition of a disk attached to the system. +.Pp +The +.Fn Partition::size +function provides the size of the partition. +.Pp +The +.Fn Partition::fs_type +and +.Fn Partition::fs_label +functions provide information about the file system present on the partition +if it is present and readable by DiskMan. +.Sh RETURN VALUES +The +.Fn Partition::size +function returns the size of the partition in bytes. +.Pp +The +.Fn Partition::fs_type +and +.Fn Partition::fs_label +functions return the requested information as std::string. +.Sh SEE ALSO +.Xr Horizon::DiskMan::Disk 3 , +.Xr Horizon::DiskMan::DiskMan 3 . +.Sh HISTORY +The DiskMan library first appeared in Horizon 0.9. +.Sh AUTHORS +.An A. Wilcox +.Aq awilfox@adelielinux.org -- cgit v1.2.3-60-g2f50