Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 575 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man5/mtools.5 b/upstream/opensuse-tumbleweed/man5/mtools.5
new file mode 100644
index 00000000..166aa901
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man5/mtools.5
@@ -0,0 +1,575 @@
+'\" t
+.TH mtools 5 "21Mar23" MTOOLS MTOOLS
+.SH Name
+mtools.conf - mtools configuration files
+'\" t
+.de TQ
+.br
+.ns
+.TP \\$1
+..
+
+.tr \(is'
+.tr \(if`
+.tr \(pd"
+
+.ds St Mtools\ 4.0.43
+.PP
+.SH Description
+.PP
+This manual page describes the configuration files for mtools. They 
+are called \fR\&\f(CW\(if/etc/mtools.conf\(is\fR and \fR\&\f(CW\(if~/.mtoolsrc\(is\fR. If
+the environmental variable \fR\&\f(CWMTOOLSRC\fR is set, its contents is used
+as the filename for a third configuration file. These configuration
+files describe the following items:
+.TP
+* \ Global\ configuration\ flags\ and\ variables\ 
+.TP
+* \ Per\ drive\ flags\ and\ variables\ 
+.PP
+.SS Location\ of\ the\ configuration\ files
+.PP
+.PP
+\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR is the system-wide configuration file,
+and \fR\&\f(CW\(if~/.mtoolsrc\(is\fR is the user's private configuration file.
+.PP
+On some systems, the system-wide configuration file is called
+\&\fR\&\f(CW\(if/etc/default/mtools.conf\(is\fR instead.
+.PP
+.SS \ \ General\ configuration\ file\ syntax
+.PP
+The configuration files is made up of sections. Each section starts
+with a keyword identifying the section followed by a colon.
+Then follow variable assignments and flags. Variable assignments take
+the following form:
+.ft I
+.nf
+name=value
+.fi
+.ft R
+ 
+Flags are lone keywords without an equal sign and value following
+them.  A section either ends at the end of the file or where the next
+section begins.
+.PP
+Lines starting with a hash (\fR\&\f(CW#\fR) are comments. Newline characters
+are equivalent to whitespace (except where ending a comment). The
+configuration file is case insensitive, except for item enclosed in
+quotes (such as filenames).
+.PP
+.SS Default\ values
+For most platforms, mtools contains reasonable compiled-in defaults for
+physical floppy drives.  Thus, you usually don't need to bother with the
+configuration file, if all you want to do with mtools is to access your
+floppy drives. On the other hand, the configuration file is needed if
+you also want to use mtools to access your hard disk partitions and
+DOSEMU image files.
+.PP
+.SS Global\ variables
+.PP
+Global flags may be set to 1 or to 0.
+.PP
+The following global flags are recognized:
+.TP
+\&\fR\&\f(CWMTOOLS_SKIP_CHECK\fR\ 
+If this is set to 1, mtools skips most of its sanity checks. This is
+needed to read some Atari disks which have been made with the earlier
+ROMs, and which would not be recognized otherwise.
+.TP
+\&\fR\&\f(CWMTOOLS_FAT_COMPATIBILITY\fR\ 
+If this is set to 1, mtools skips the fat size checks. Some disks have
+a bigger FAT than they really need to. These are rejected if this
+option is not set.
+.TP
+\&\fR\&\f(CWMTOOLS_LOWER_CASE\fR\ 
+If this is set to 1, mtools displays all-upper-case short filenames as
+lowercase. This has been done to allow a behavior which is consistent
+with older versions of mtools which didn't know about the case bits.
+.TP
+\&\fR\&\f(CWMTOOLS_NO_VFAT\fR\ 
+If this is set to 1, mtools won't generate VFAT entries for filenames
+which are mixed-case, but otherwise legal dos filenames.  This is useful
+when working with DOS versions which can't grok VFAT long names, such as
+FreeDOS.
+.TP
+\&\fR\&\f(CWMTOOLS_DOTTED_DIR\fR\ 
+In a wide directory, prints the short name with a dot instead of spaces
+separating the basename and the extension.
+.TP
+\&\fR\&\f(CWMTOOLS_NAME_NUMERIC_TAIL\fR\ 
+If this is set to one (default), generate numeric tails for all long
+names (~1).  If set to zero, only generate numeric tails if otherwise a
+clash would have happened.
+.TP
+\&\fR\&\f(CWMTOOLS_TWENTY_FOUR_HOUR_CLOCK\fR\ 
+If 1, uses the European notation for times (twenty four hour clock),
+else uses the UK/US notation (am/pm)
+.TP
+\&\fR\&\f(CWMTOOLS_LOCK_TIMEOUT\fR\ 
+How long, in seconds, to wait for a locked device to become free.
+Defaults to 30.
+.PP
+Example:
+Inserting the following line into your configuration file instructs
+mtools to skip the sanity checks:
+ 
+.nf
+.ft 3
+.in +0.3i
+  MTOOLS_SKIP_CHECK=1
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+Global variables may also be set via the environment:
+ 
+.nf
+.ft 3
+.in +0.3i
+  export MTOOLS_SKIP_CHECK=1
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+Global string variables may be set to any value:
+.TP
+\&\fR\&\f(CWMTOOLS_DATE_STRING\fR\ 
+The format used for printing dates of files.  By default, is dd-mm-yyyy.
+.PP
+.SS Per\ drive\ flags\ and\ variables
+.PP
+.SS \ \ General\ information
+.PP
+Per drive flags and values may be described in a drive section. A
+drive section starts with
+\&\fR\&\f(CWdrive\fR "\fIdriveletter\fR" :
+.PP
+Then follow variable-value pairs and flags.
+.PP
+This is a sample drive description:
+ 
+.nf
+.ft 3
+.in +0.3i
+  drive a:
+    file="/dev/fd0" use_xdf=1
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+.SS \ \ Location\ information
+.PP
+For each drive, you need to describe where its data is physically
+stored (image file, physical device, partition, offset).
+.TP
+\&\fR\&\f(CWfile\fR\ 
+The name of the file or device holding the disk image. This is
+mandatory. The file name should be enclosed in quotes.
+.TP
+\&\fR\&\f(CWpartition\fR\ 
+Tells mtools to treat the drive as a partitioned device, and to use the
+given partition. Only primary partitions are accessible using this
+method, and they are numbered from 1 to 4. For logical partitions, use
+the more general \fR\&\f(CWoffset\fR variable. The \fR\&\f(CWpartition\fR variable
+is intended for removable media such as Syquest disks, ZIP drives, and
+magneto-optical disks. Although traditional DOS sees Syquest disks and
+magneto-optical disks as \fR\&\f(CW\(ifgiant floppy disks\(is\fR which are
+unpartitioned, OS/2 and Windows NT treat them like hard disks,
+i.e. partitioned devices. The \fR\&\f(CWpartition\fR flag is also useful DOSEMU
+hdimages. It is not recommended for hard disks for which direct access
+to partitions is available through mounting.
+.TP
+\&\fR\&\f(CWoffset\fR\ 
+Describes where in the file the MS-DOS file system starts. This is useful
+for logical partitions in DOSEMU hdimages, and for ATARI ram disks. By
+default, this is zero, meaning that the file system starts right at the
+beginning of the device or file.
+.PP
+.SS \ \ Disk\ Geometry\ Configuration
+.PP
+Geometry information describes the physical characteristics about the
+disk. Its has three purposes:
+.TP
+formatting\ 
+The geometry information is written into the boot sector of the newly
+made disk. However, you may also describe the geometry information on
+the command line. See section mformat, for details.
+.TP
+filtering\ 
+On some Unixes there are device nodes which only support one physical
+geometry. For instance, you might need a different node to access a disk
+as high density or as low density. The geometry is compared to the
+actual geometry stored on the boot sector to make sure that this device
+node is able to correctly read the disk. If the geometry doesn't match,
+this drive entry fails, and the next drive entry bearing the same drive
+letter is tried. See section multiple descriptions, for more details on
+supplying several descriptions for one drive letter.
+.IP
+If no geometry information is supplied in the configuration file, all
+disks are accepted. On Linux (and on SPARC) there exist device nodes
+with configurable geometry (\fR\&\f(CW\(if/dev/fd0\(is\fR, \fR\&\f(CW\(if/dev/fd1\(is\fR etc),
+and thus filtering is not needed (and ignored) for disk drives.  (Mtools
+still does do filtering on plain files (disk images) in Linux: this is
+mainly intended for test purposes, as I don't have access to a Unix
+which would actually need filtering).
+.IP
+If you do not need filtering, but want still a default geometry for
+mformatting, you may switch off filtering using the \fR\&\f(CWmformat_only\fR
+flag.
+.IP
+If you want filtering, you should supply the \fR\&\f(CWfilter\fR flag.  If you 
+supply a geometry, you must supply one of both flags.
+.TP
+initial\ geometry\ 
+On devices that support it (usually floppy devices), the geometry
+information is also used to set the initial geometry. This initial
+geometry is applied while reading the boot sector, which contains the
+real geometry.  If no geometry information is supplied in the
+configuration file, or if the \fR\&\f(CWmformat_only\fR flag is supplied, no
+initial configuration is done.
+.IP
+On Linux, initial geometry is not really needed, as the configurable
+devices are able to auto-detect the disk type accurately enough (for
+most common formats) to read the boot sector.
+.PP
+Wrong geometry information may lead to very bizarre errors. That's why I
+strongly recommend that you add the \fR\&\f(CWmformat_only\fR flag to your
+drive description, unless you really need filtering or initial geometry.
+.PP
+The following geometry related variables are available:
+.TP
+\&\fR\&\f(CWcylinders\fR\ 
+.TQ
+\&\fR\&\f(CWtracks\fR
+The number of cylinders. (\fR\&\f(CWcylinders\fR is the preferred form,
+\&\fR\&\f(CWtracks\fR is considered obsolete)
+.TP
+\&\fR\&\f(CWheads\fR\ 
+The number of heads (sides).
+.TP
+\&\fR\&\f(CWsectors\fR\ 
+The number of sectors per track.
+.PP
+Example: the following drive section describes a 1.44M drive:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+  drive a:
+      file="/dev/fd0H1440"
+      fat_bits=12
+      cylinders=80 heads=2 sectors=18
+      mformat_only
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+The following shorthand geometry descriptions are available:
+.TP
+\&\fR\&\f(CW1.44m\fR\ 
+high density 3 1/2 disk. Equivalent to:
+\&\fR\&\f(CWfat_bits=12 cylinders=80 heads=2 sectors=18\fR
+.TP
+\&\fR\&\f(CW1.2m\fR\ 
+high density 5 1/4 disk. Equivalent to:
+\&\fR\&\f(CWfat_bits=12 cylinders=80 heads=2 sectors=15\fR
+.TP
+\&\fR\&\f(CW720k\fR\ 
+double density 3 1/2 disk. Equivalent to:
+\&\fR\&\f(CWfat_bits=12 cylinders=80 heads=2 sectors=9\fR
+.TP
+\&\fR\&\f(CW360k\fR\ 
+double density 5 1/4 disk. Equivalent to:
+\&\fR\&\f(CWfat_bits=12 cylinders=40 heads=2 sectors=9\fR
+.PP
+The shorthand format descriptions may be amended. For example,
+\&\fR\&\f(CW360k sectors=8\fR
+describes a 320k disk and is equivalent to:
+\&\fR\&\f(CWfat_bits=12 cylinders=40 heads=2 sectors=8\fR
+.PP
+.SS \ \ Open\ Flags
+.PP
+Moreover, the following flags are available:
+.TP
+\&\fR\&\f(CWsync\fR\ 
+All i/o operations are done synchronously
+.TP
+\&\fR\&\f(CWnodelay\fR\ 
+The device or file is opened with the O_NDELAY flag. This is needed on
+some non-Linux architectures.
+.TP
+\&\fR\&\f(CWexclusive\fR\ 
+The device or file is opened with the O_EXCL flag. On Linux, this
+ensures exclusive access to the floppy drive. On most other
+architectures, and for plain files it has no effect at all.
+.PP
+.SS \ \ General\ Purpose\ Drive\ Variables
+.PP
+The following general purpose drive variables are available.
+Depending to their type, these variables can be set to a string
+(precmd, postcmd) or an integer (all others)
+.TP
+\&\fR\&\f(CWfat_bits\fR\ 
+The number of FAT bits. This may be 12 or 16. This is very rarely
+needed, as it can almost always be deduced from information in the
+boot sector. On the contrary, describing the number of fat bits may
+actually be harmful if you get it wrong. You should only use it if
+mtools gets the auto-detected number of fat bits wrong, or if you want
+to mformat a disk with a weird number of fat bits.
+.TP
+\&\fR\&\f(CWcodepage\fR\ 
+Describes the DOS code page used for short filenames. This is a number
+between 1 and 999. By default, code page 850 is used. The reason for
+this is because this code page contains most of the characters that are
+also available in ISO-Latin-1. You may also specify a global code page
+for all drives by using the global \fR\&\f(CWdefault_codepage\fR parameter
+(outside of any drive description). This parameters exists starting at
+version 4.0.0
+.TP
+\&\fR\&\f(CWdata_map\fR\ 
+Remaps data from image file. This is useful for image files which
+might need additional zero-filled sectors to be inserted. Such is the
+case for instance for IBM 3174 floppy images. These images represent
+floppy disks with fewer sectors on their first cylinder. These missing
+sectors are not stored in the image, but are still counted in the
+filesystem layout. The data_map allows to fake these missing sectors
+for the upper layers of mtools. A data_map is a comma-separated
+sequence of source type and size. Source type may be \fR\&\f(CWzero\fR for
+zero-filled sectors created by map, \fR\&\f(CWskip\fR for data in raw image
+to be ignored (skipped), and nothing for data to be used as is
+(copied) from the raw image. Datamap is automatically complemented by
+an implicit last element of data to be used as is from current offset
+to end of file. Each size is a number followed by a unit: \fR\&\f(CWs\fR for
+a 512 byte sector, \fR\&\f(CWK\fR for Kbytes, \fR\&\f(CWM\fR for megabytes,
+\&\fR\&\f(CWG\fR for gigabytes, and nothing for single bytes.
+.IP
+Example:
+.IP
+\&\fR\&\f(CWdata_map=1s,zero31s,28s,skip1s\fR would be a map for use with IBM
+3174 floppy images. First sector (\fR\&\f(CW1s\fR, boot sector) is used as
+is. Then follow 31 fake zero-filled sectors (\fR\&\f(CWzero31s\fR), then the
+next 28 sectors from image (\fR\&\f(CW28s\fR) are used as is (they contain
+FAT and root directory), then one sector from image is skipped
+(\fR\&\f(CWskip1s\fR), and finally the rest of image is used as is
+(implicit)
+.IP
+.TP
+\&\fR\&\f(CWprecmd\fR\ 
+Executes the given command before opening the device.
+On some variants of Solaris, it is necessary to call 'volcheck -v'
+before opening a floppy device, in order for the system to notice that
+there is indeed a disk in the drive. \fR\&\f(CWprecmd="volcheck -v"\fR in the
+drive clause establishes the desired behavior.
+.TP
+\&\fR\&\f(CWpostcmd\fR\ 
+Executes the given command after closing the device.
+May be useful if mtools shares the image file with some other application,
+in order to release the image file to that application.
+.TP
+\&\fR\&\f(CWblocksize\fR\ 
+This parameter represents a default block size to be always used on this
+device.  All I/O is done with multiples of this block size,
+independently of the sector size registered in the file system's boot
+sector.  This is useful for character devices whose sector size is not
+512, such as for example CD-ROM drives on Solaris.
+.PP
+Only the \fR\&\f(CWfile\fR variable is mandatory. The other parameters may
+be left out. In that case a default value or an auto-detected value is
+used.
+.PP
+.SS \ \ General\ Purpose\ Drive\ Flags
+.PP
+A flag can either be set to 1 (enabled) or 0 (disabled). If the value is
+omitted, it is enabled.  For example, \fR\&\f(CWscsi\fR is equivalent to
+\&\fR\&\f(CWscsi=1\fR
+.TP
+\&\fR\&\f(CWnolock\fR\ 
+Instruct mtools to not use locking on this drive.  This is needed on
+systems with buggy locking semantics.  However, enabling this makes
+operation less safe in cases where several users may access the same
+drive at the same time.
+.TP
+\&\fR\&\f(CWscsi\fR\ 
+When set to 1, this option tells mtools to use raw SCSI I/O instead of
+the standard read/write calls to access the device. Currently, this is
+supported on HP-UX, Solaris and SunOS.  This is needed because on some
+architectures, such as SunOS or Solaris, PC media can't be accessed
+using the \fR\&\f(CWread\fR and \fR\&\f(CWwrite\fR system calls, because the OS expects
+them to contain a Sun specific "disk label".
+.IP
+As raw SCSI access always uses the whole device, you need to specify the
+"partition" flag in addition
+.IP
+On some architectures, such as Solaris, mtools needs root privileges to
+be able to use the \fR\&\f(CWscsi\fR option.  Thus mtools should be installed
+setuid root on Solaris if you want to access Zip/Jaz drives.  Thus, if
+the \fR\&\f(CWscsi\fR flag is given, \fR\&\f(CWprivileged\fR is automatically
+implied, unless explicitly disabled by \fR\&\f(CWprivileged=0\fR
+.IP
+Mtools uses its root privileges to open the device, and to issue the
+actual SCSI I/O calls.  Moreover, root privileges are only used for
+drives described in a system-wide configuration file such as
+\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR, and not for those described in
+\&\fR\&\f(CW\(if~/.mtoolsrc\(is\fR or \fR\&\f(CW\(if$MTOOLSRC\(is\fR.  
+.TP
+\&\fR\&\f(CWprivileged\fR\ 
+When set to 1, this instructs mtools to use its setuid and setgid
+privileges for opening the given drive.  This option is only valid for
+drives described in the system-wide configuration files (such as
+\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR, not \fR\&\f(CW\(if~/.mtoolsrc\(is\fR or
+\&\fR\&\f(CW\(if$MTOOLSRC\(is\fR).  Obviously, this option is also a no op if mtools is
+not installed setuid or setgid.  This option is implied by 'scsi=1', but
+again only for drives defined in system-wide configuration files.
+Privileged may also be set explicitly to 0, in order to tell mtools not
+to use its privileges for a given drive even if \fR\&\f(CWscsi=1\fR is set.
+.IP
+Mtools only needs to be installed setuid if you use the
+\&\fR\&\f(CWprivileged\fR or \fR\&\f(CWscsi\fR drive variables.  If you do not use
+these options, mtools works perfectly well even when not installed
+setuid root.
+.TP
+\&\fR\&\f(CWvold\fR\ 
+.IP
+Instructs mtools to interpret the device name as a vold identifier
+rather than as a filename.  The vold identifier is translated into a
+real filename using the \fR\&\f(CWmedia_findname()\fR and
+\&\fR\&\f(CWmedia_oldaliases()\fR functions of the \fR\&\f(CWvolmgt\fR library.  This
+flag is only available if you configured mtools with the
+\&\fR\&\f(CW--enable-new-vold\fR option before compilation.
+.TP
+\&\fR\&\f(CWswap\fR\ 
+.IP
+Consider the media as a word-swapped Atari disk.
+.TP
+\&\fR\&\f(CWuse_xdf\fR\ 
+If this is set to a non-zero value, mtools also tries to access this
+disk as an XDF disk. XDF is a high capacity format used by OS/2. This
+is off by default. See section XDF, for more details.
+.TP
+\&\fR\&\f(CWmformat_only\fR\ 
+Tells mtools to use the geometry for this drive only for mformatting and 
+not for filtering.
+.TP
+\&\fR\&\f(CWfilter\fR\ 
+Tells mtools to use the geometry for this drive both for mformatting and 
+filtering.
+.TP
+\&\fR\&\f(CWremote\fR\ 
+Tells mtools to connect to floppyd (see section  floppyd).
+.PP
+.SS \ \ Supplying\ multiple\ descriptions\ for\ a\ drive
+.PP
+It is possible to supply multiple descriptions for a drive. In that
+case, the descriptions are tried in order until one is found that
+fits. Descriptions may fail for several reasons:
+.TP
+1.\ 
+because the geometry is not appropriate,
+.TP
+2.\ 
+because there is no disk in the drive,
+.TP
+3.\ 
+or because of other problems.
+.PP
+Multiple definitions are useful when using physical devices which are
+only able to support one single disk geometry.
+Example:
+ 
+.nf
+.ft 3
+.in +0.3i
+  drive a: file="/dev/fd0H1440" 1.44m
+  drive a: file="/dev/fd0H720" 720k
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+This instructs mtools to use /dev/fd0H1440 for 1.44m (high density)
+disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this
+feature is not really needed, as the /dev/fd0 device is able to handle
+any geometry.
+.PP
+You may also use multiple drive descriptions to access both of your
+physical drives through one drive letter:
+.PP
+ 
+.nf
+.ft 3
+.in +0.3i
+  drive z: file="/dev/fd0"
+  drive z: file="/dev/fd1"
+.fi
+.in -0.3i
+.ft R
+.PP
+ 
+\&\fR
+.PP
+With this description, \fR\&\f(CWmdir z:\fR accesses your first physical
+drive if it contains a disk. If the first drive doesn't contain a disk,
+mtools checks the second drive.
+.PP
+When using multiple configuration files, drive descriptions in the files
+parsed last override descriptions for the same drive in earlier
+files. In order to avoid this, use the \fR\&\f(CWdrive+\fR or \fR\&\f(CW+drive\fR
+keywords instead of \fR\&\f(CWdrive\fR. The first adds a description to the
+end of the list (i.e. it will be tried last), and the first adds it to
+the start of the list.
+.PP
+.SS Location\ of\ configuration\ files\ and\ parsing\ order
+.PP
+The configuration files are parsed in the following order:
+.TP
+1.\ 
+compiled-in defaults
+.TP
+2.\ 
+\&\fR\&\f(CW\(if/etc/mtools.conf\(is\fR
+.TP
+3.\ 
+\&\fR\&\f(CW\(if~/.mtoolsrc\(is\fR.
+.TP
+4.\ 
+\&\fR\&\f(CW\(if$MTOOLSRC\(is\fR (file pointed by the \fR\&\f(CWMTOOLSRC\fR environmental
+variable)
+.PP
+Options described in the later files override those described in the
+earlier files. Drives defined in earlier files persist if they are not
+overridden in the later files. For instance, drives A and B may be
+defined in \fR\&\f(CW\(if/etc/mtools.conf\(is\fR and drives C and D may be
+defined in \fR\&\f(CW\(if~/.mtoolsrc\(is\fR However, if \fR\&\f(CW\(if~/.mtoolsrc\(is\fR also
+defines drive A, this new description would override the description of
+drive A in \fR\&\f(CW\(if/etc/mtools.conf\(is\fR instead of adding to it. If
+you want to add a new description to a drive already described in an
+earlier file, you need to use either the \fR\&\f(CW+drive\fR or \fR\&\f(CWdrive+\fR
+keyword.
+.PP
+.SS Backwards\ compatibility\ with\ old\ configuration\ file\ syntax
+.PP
+The syntax described herein is new for version \fR\&\f(CWmtools-3.0\fR. The
+old line-oriented syntax is still supported. Each line beginning with a
+single letter is considered to be a drive description using the old
+syntax. Old style and new style drive sections may be mixed within the
+same configuration file, in order to make upgrading easier. Support for
+the old syntax will be phased out eventually, and in order to discourage
+its use, I purposefully omit its description here.
+.PP
+.SH See also
+mtools