diff options
Diffstat (limited to 'mtools.texi')
| -rw-r--r-- | mtools.texi | 2638 |
1 files changed, 2638 insertions, 0 deletions
diff --git a/mtools.texi b/mtools.texi new file mode 100644 index 0000000..1085789 --- /dev/null +++ b/mtools.texi @@ -0,0 +1,2638 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename mtools.info +@include version.texi +@settitle Mtools @value{VERSION} +@syncodeindex pg cp +@comment %**end of header + +@comment MANskip 5 + +@copying +This manual is for Mtools (version @value{VERSION}, @value{UPDATED}), +which is a collection of tools to allow Unix systems to manipulate +MS-DOS files. + +Copyright @copyright{} 2007, 2009 Free Software Foundation, Inc. +Copyright @copyright{} 1996-2005,2007-2011,2013 Alain Knaff. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled +``GNU Free Documentation License''. +@end quotation +@end copying + +@ignore +@unnumbered Name +mtools - utilities to access DOS disks in Unix. +@end ignore + +@include sysconfdir.texi + +@iftex +@finalout +@end iftex + +@dircategory DOS +@direntry +* Mtools: (mtools). Mtools: utilities to access DOS disks in Unix. +@end direntry + + +@titlepage +@title Mtools + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c Output the table contents at the beginning +@contents + +@ifnottex +@node Top, Location, (dir), (dir) +@top Mtools doc + +This is mtools' documentation. +@end ifnottex + +@comment MANstart 1 + +@unnumbered Introduction +Mtools is a collection of tools to allow Unix systems to manipulate +MS-DOS files: read, write, and move around files on an MS-DOS +file system (typically a floppy disk). Where reasonable, each program +attempts to emulate the MS-DOS equivalent command. However, +unnecessary restrictions and oddities of DOS are not emulated. For +instance, it is possible to move subdirectories from one subdirectory +to another. + +Mtools is sufficient to give access to MS-DOS file systems. For +instance, commands such as @code{mdir a:} work on the @code{a:} floppy +without any preliminary mounting or initialization (assuming the default +@file{@value{SYSCONFDIR}mtools.conf} works on your machine). With mtools, one can +change floppies too without unmounting and mounting. + +@insertcopying + +@menu +* Location:: Where to find mtools and early bug fixes +* Common features:: Common features of all mtools commands +* Configuration:: How to configure mtools for your environment +* Commands:: The available mtools commands +* Compiling mtools:: Architecture specific compilation flags +* Porting mtools:: Porting mtools to architectures which are not + yet supported + +* Command Index:: Command Index +* Variable Index:: Variable Index +* Concept Index:: Concept Index +@end menu + +@node Location, Common features, Top, Top +@chapter Where to get mtools +@cindex bugs +@cindex ALPHA patches +@cindex patches +@cindex diffs +@cindex mailing list + +Mtools can be found at the following places (and their mirrors): +@example +http://ftp.gnu.org/gnu/mtools/mtools-@value{VERSION}.tar.gz +http://mtools.linux.lu/mtools-@value{VERSION}.tar.gz +ftp://www.tux.org/pub/knaff/mtools/mtools-@value{VERSION}.tar.gz +ftp://ibiblio.unc.edu/pub/Linux/utils/disk-management/mtools-@value{VERSION}.tar.gz +@end example + +Before reporting a bug, make sure that it has not yet been fixed in the +Alpha patches which can be found at: +@example +http://ftp.gnu.org/gnu/mtools/ +http://mtools.linux.lu/ +ftp://www.tux.org/pub/knaff/mtools +@end example + +These patches are named +@code{mtools-}@var{version}@code{-}@var{ddmm}@code{.taz}, where version +stands for the base version, @var{dd} for the day and @var{mm} for the +month. Due to a lack of space, I usually leave only the most recent +patch. + +There is an mtools mailing list at mtools @@ tux.org . Please +send all bug reports to this list. You may subscribe to the list by +sending a message with 'subscribe mtools @@ tux.org' in its +body to majordomo @@ tux.org . (N.B. Please remove the spaces +around the "@@" both times. I left them there in order to fool +spambots.) Announcements of new mtools versions will also be sent to +the list, in addition to the Linux announce newsgroups. The mailing +list is archived at http://lists.gnu.org/pipermail/info-mtools/ + + +@node Common features, Configuration, Location, Top +@chapter Common features of all mtools commands + +@menu +* arguments:: What the command line parameters of mtools + mean +* drive letters:: Which drives are defined by default +* directory:: Current working directory +* long names:: VFAT-style long filenames +* name clashes:: Name clash handling, and associated command + line options +* case sensitivity:: Case sensitivity +* high capacity formats:: How to fit more data on your floppies +* exit codes:: Exit codes +* bugs:: Happens to everybody +@end menu + +@node arguments, drive letters, Common features, Common features +@section Options and filenames +@cindex Filenames +@cindex Options +MS-DOS filenames are composed of a drive letter followed by a colon, a +subdirectory, and a filename. Only the filename part is mandatory, the +drive letter and the subdirectory are optional. Filenames without a +drive letter refer to Unix files. Subdirectory names can use either the +'@code{/}' or '@code{\}' separator. The use of the '@code{\}' separator +or wildcards requires the names to be enclosed in quotes to protect them +from the shell. However, wildcards in Unix filenames should not be +enclosed in quotes, because here we @strong{want} the shell to expand +them. + +The regular expression "pattern matching" routines follow the Unix-style +rules. For example, `@code{*}' matches all MS-DOS files in lieu of +`@code{*.*}'. The archive, hidden, read-only and system attribute bits +are ignored during pattern matching. + +All options use the @code{-} (minus) as their first character, not +@code{/} as you'd expect in MS-DOS. + +Most mtools commands allow multiple filename parameters, which +doesn't follow MS-DOS conventions, but which is more user-friendly. + +Most mtools commands allow options that instruct them how to handle file +name clashes. @xref{name clashes}, for more details on these. All +commands accept the @code{-V} flags which prints the version, and most +accept the @code{-v} flag, which switches on verbose mode. In verbose +mode, these commands print out the name of the MS-DOS files upon which +they act, unless stated otherwise. @xref{Commands}, for a description of +the options which are specific to each command. + + +@node drive letters, directory, arguments, Common features +@section Drive letters + +The meaning of the drive letters depends on the target architectures. +However, on most target architectures, drive A is the first floppy +drive, drive B is the second floppy drive (if available), drive J is a +Jaz drive (if available), and drive Z is a Zip drive (if available). On +those systems where the device name is derived from the SCSI id, the Jaz +drive is assumed to be at SCSI target 4, and the Zip at SCSI target 5 +(factory default settings). On Linux, both drives are assumed to be the +second drive on the SCSI bus (/dev/sdb). The default settings can be +changes using a configuration file (@pxref{Configuration}). + +The drive letter : (colon) has a special meaning. It is used to access +image files which are directly specified on the command line using the +@code{-i} options. + +Example: +@example + mcopy -i my-image-file.bin ::file1 ::file2 . +@end example + +This copies @code{file1} and @code{file2} from the image file +(@code{my-image-file.bin}) to the @code{/tmp} directory. + +You can also supply an offset within the image file by including +@code{@@@@}@var{offset} into the file name. + +Example: +@example + mcopy -i my-image-file.bin@@@@1M ::file1 ::file2 . +@end example + +This looks for the image at the offset of 1M in the file, rather than +at its beginning. + +@node directory, long names, drive letters, Common features +@section Current working directory +@pindex mcd (introduction) +@cindex Directory +@cindex Working directory +@cindex Current working directory +@cindex Default directory + +The @code{mcd} command (@ref{mcd}) is used to establish the device and +the current working directory (relative to the MS-DOS file system), +otherwise the default is assumed to be @code{A:/}. However, unlike +MS-DOS, there is only one working directory for all drives, and not one +per drive. + +@node long names, name clashes, directory, Common features +@section VFAT-style long file names +@cindex Long file name +@cindex Windows 95-style file names +@cindex VFAT-style file names +@cindex Primary file name (long names) +@cindex Secondary file name (long names) + +This version of mtools supports VFAT style long filenames. If a Unix +filename is too long to fit in a short DOS name, it is stored as a +VFAT long name, and a companion short name is generated. This short +name is what you see when you examine the disk with a pre-7.0 version +of DOS. + The following table shows some examples of short names: + +@example +Long name MS-DOS name Reason for the change +--------- ---------- --------------------- +thisisatest THISIS~1 filename too long +alain.knaff ALAIN~1.KNA extension too long +prn.txt PRN~1.TXT PRN is a device name +.abc ABC~1 null filename +hot+cold HOT_CO~1 illegal character +@end example + + As you see, the following transformations happen to derive a short +name: +@itemize @bullet +@item +Illegal characters are replaced by underscores. The illegal characters +are @code{;+=[]',\"*\\<>/?:|}. +@item +Extra dots, which cannot be interpreted as a main name/extension +separator are removed +@item +A @code{~}@var{n} number is generated, +@item +The name is shortened so as to fit in the 8+3 limitation +@end itemize + + The initial Unix-style file name (whether long or short) is also called +the @dfn{primary} name, and the derived short name is also called the +@dfn{secondary} name. + + Example: +@example + mcopy /etc/motd a:Reallylongname +@end example + Mtools creates a VFAT entry for Reallylongname, and uses REALLYLO as +a short name. Reallylongname is the primary name, and REALLYLO is the +secondary name. +@example + mcopy /etc/motd a:motd +@end example + Motd fits into the DOS filename limits. Mtools doesn't need to +derivate another name. Motd is the primary name, and there is no +secondary name. + + In a nutshell: The primary name is the long name, if one exists, or +the short name if there is no long name. + + Although VFAT is much more flexible than FAT, there are still names +that are not acceptable, even in VFAT. There are still some illegal +characters left (@code{\"*\\<>/?:|}), and device names are still +reserved. + +@example +Unix name Long name Reason for the change +--------- ---------- --------------------- +prn prn-1 PRN is a device name +ab:c ab_c-1 illegal character +@end example + + As you see, the following transformations happen if a long name is +illegal: +@itemize @bullet +@item +Illegal characters are replaces by underscores, +@item +A @code{-}@var{n} number is generated, +@end itemize + +@node name clashes, case sensitivity, long names, Common features +@section Name clashes +@cindex Name clashes +@cindex Duplicate file names +@cindex Overwriting files +@cindex Primary file name (name clashes) +@cindex Secondary file name (name clashes) + +When writing a file to disk, its long name or short name may collide +with an already existing file or directory. This may happen for all +commands which create new directory entries, such as @code{mcopy}, +@code{mmd}, @code{mren}, @code{mmove}. When a name clash happens, mtools +asks you what it should do. It offers several choices: + +@table @code +@item overwrite +Overwrites the existing file. It is not possible to overwrite a +directory with a file. +@item rename +Renames the newly created file. Mtools prompts for the new filename +@item autorename +Renames the newly created file. Mtools chooses a name by itself, without +prompting +@item skip +Gives up on this file, and moves on to the next (if any) +@end table + +To chose one of these actions, type its first letter at the prompt. If +you use a lower case letter, the action only applies for this file only, +if you use an upper case letter, the action applies to all files, and +you won't be prompted again. + +You may also chose actions (for all files) on the command line, when +invoking mtools: + +@table @code +@item -D o +Overwrites primary names by default. +@item -D O +Overwrites secondary names by default. +@item -D r +Renames primary name by default. +@item -D R +Renames secondary name by default. +@item -D a +Autorenames primary name by default. +@item -D A +Autorenames secondary name by default. +@item -D s +Skip primary name by default. +@item -D S +Skip secondary name by default. +@item -D m +Ask user what to do with primary name. +@item -D M +Ask user what to do with secondary name. +@end table + +Note that for command line switches lower/upper differentiates between +primary/secondary name whereas for interactive choices, lower/upper +differentiates between just-this-time/always. + +The primary name is the name as displayed in Windows 95 or Windows NT: +i.e. the long name if it exists, and the short name otherwise. The +secondary name is the "hidden" name, i.e. the short name if a long name +exists. + +By default, the user is prompted if the primary name clashes, and the +secondary name is autorenamed. + +If a name clash occurs in a Unix directory, mtools only asks whether +to overwrite the file, or to skip it. + +@node case sensitivity, high capacity formats, name clashes, Common features +@section Case sensitivity of the VFAT file system +@cindex Case sensitivity + +The VFAT file system is able to remember the case of the +filenames. However, filenames which differ only in case are not allowed +to coexist in the same directory. For example if you store a file called +LongFileName on a VFAT file system, mdir shows this file as LongFileName, +and not as Longfilename. However, if you then try to add LongFilename to +the same directory, it is refused, because case is ignored for clash +checks. + +The VFAT file system allows to store the case of a filename in the +attribute byte, if all letters of the filename are the same case, and if +all letters of the extension are the same case too. Mtools uses this +information when displaying the files, and also to generate the Unix +filename when mcopying to a Unix directory. This may have unexpected +results when applied to files written using an pre-7.0 version of DOS: +Indeed, the old style filenames map to all upper case. This is different +from the behavior of the old version of mtools which used to generate +lower case Unix filenames. + +@node high capacity formats, exit codes, case sensitivity, Common features +@section high capacity formats +@cindex Special formats +@cindex High capacity formats +@cindex Odd formats +@cindex Weird formats +@cindex Formats, high capacity +@cindex Linux enhancements (High Capacity Formats) + +Mtools supports a number of formats which allow to store more data on +disk as usual. Due to different operating system abilities, these +formats are not supported on all operating systems. Mtools recognizes +these formats transparently where supported. + +In order to format these disks, you need to use an operating system +specific tool. For Linux, suitable floppy tools can be found in the +@code{fdutils} package at the following locations~: +@example +@code{ftp://www.tux.org/pub/knaff/fdutils/}. +@code{ftp://ibiblio.unc.edu/pub/Linux/utils/disk-management/fdutils-*} +@end example + +See the manual pages included in that package for further detail: Use +@code{superformat} to format all formats except XDF, and use +@code{xdfcopy} to format XDF. + +@menu +* more sectors:: Putting more sectors per track on the disk +* bigger sectors:: Use bigger sectors to save header space +* 2m:: Use a standard first track +* XDF:: OS/2's eXtended density format +@end menu + +@node more sectors, bigger sectors, high capacity formats, high capacity formats +@subsection More sectors +@cindex fdformat +@cindex vgacopy +@cindex DMF disks +@cindex Windows 95 (DMF disks) + +The oldest method of fitting more data on a disk is to use more sectors +and more cylinders. Although the standard format uses 80 cylinders and +18 sectors (on a 3 1/2 high density disk), it is possible to use up to +83 cylinders (on most drives) and up to 21 sectors. This method allows +to store up to 1743K on a 3 1/2 HD disk. However, 21 sector disks are +twice as slow as the standard 18 sector disks because the sectors are +packed so close together that we need to interleave them. This problem +doesn't exist for 20 sector formats. + +These formats are supported by numerous DOS shareware utilities such as +@code{fdformat} and @code{vgacopy}. In his infinite hubris, Bill Gate$ +believed that he invented this, and called it @samp{DMF disks}, or +@samp{Windows formatted disks}. But in reality, it has already existed +years before! Mtools supports these formats on Linux, on SunOS and on +the DELL Unix PC. + +@node bigger sectors, 2m, more sectors, high capacity formats +@subsection Bigger sectors +@cindex bigger sectors +By using bigger sectors it is possible to go beyond the capacity which +can be obtained by the standard 512-byte sectors. This is because of the +sector header. The sector header has the same size, regardless of how +many data bytes are in the sector. Thus, we save some space by using +@emph{fewer}, but bigger sectors. For example, 1 sector of 4K only takes +up header space once, whereas 8 sectors of 512 bytes have also 8 +headers, for the same amount of useful data. + +This method allows to store up to 1992K on a 3 1/2 HD disk. + +Mtools supports these formats only on Linux. + +@node 2m, XDF, bigger sectors, high capacity formats +@subsection 2m +@cindex 2m + +The 2m format was originally invented by Ciriaco Garcia de Celis. It +also uses bigger sectors than usual in order to fit more data on the +disk. However, it uses the standard format (18 sectors of 512 bytes +each) on the first cylinder, in order to make these disks easier to +handle by DOS. Indeed this method allows to have a standard sized +boot sector, which contains a description of how the rest of the disk +should be read. + +However, the drawback of this is that the first cylinder can hold less +data than the others. Unfortunately, DOS can only handle disks where +each track contains the same amount of data. Thus 2m hides the fact that +the first track contains less data by using a @dfn{shadow +FAT}. (Usually, DOS stores the FAT in two identical copies, for +additional safety. XDF stores only one copy, but tells DOS that it +stores two. Thus the space that would be taken up by the second FAT copy +is saved.) This also means that you should @strong{never use a 2m disk +to store anything else than a DOS file system}. + +Mtools supports these formats only on Linux. + +@node XDF, , 2m, high capacity formats +@subsection XDF +@cindex XDF disks +@cindex OS/2 (XDF disks) + +XDF is a high capacity format used by OS/2. It can hold 1840 K per +disk. That's lower than the best 2m formats, but its main advantage is +that it is fast: 600 milliseconds per track. That's faster than the 21 +sector format, and almost as fast as the standard 18 sector format. In +order to access these disks, make sure mtools has been compiled with XDF +support, and set the @code{use_xdf} variable for the drive in the +configuration file. @xref{Compiling mtools}, and @ref{miscellaneous variables}, +for details on how to do this. Fast XDF access is only available for +Linux kernels which are more recent than 1.1.34. + +Mtools supports this format only on Linux. + +@strong{Caution / Attention distributors}: If mtools is compiled on a +Linux kernel more recent than 1.3.34, it won't run on an older +kernel. However, if it has been compiled on an older kernel, it still +runs on a newer kernel, except that XDF access is slower. It is +recommended that distribution authors only include mtools binaries +compiled on kernels older than 1.3.34 until 2.0 comes out. When 2.0 will +be out, mtools binaries compiled on newer kernels may (and should) be +distributed. Mtools binaries compiled on kernels older than 1.3.34 won't +run on any 2.1 kernel or later. + +@node exit codes, bugs, high capacity formats, Common features +@section Exit codes +All the Mtools commands return 0 on success, 1 on utter failure, or 2 +on partial failure. All the Mtools commands perform a few sanity +checks before going ahead, to make sure that the disk is indeed an +MS-DOS disk (as opposed to, say an ext2 or MINIX disk). These checks +may reject partially corrupted disks, which might otherwise still be +readable. To avoid these checks, set the MTOOLS_SKIP_CHECK +environmental variable or the corresponding configuration file variable +(@pxref{global variables}) +@node bugs, , exit codes, Common features +@section Bugs +An unfortunate side effect of not guessing the proper device (when +multiple disk capacities are supported) is an occasional error message +from the device driver. These can be safely ignored. + +The fat checking code chokes on 1.72 Mb disks mformatted with pre-2.0.7 +mtools. Set the environmental variable MTOOLS_FAT_COMPATIBILITY (or the +corresponding configuration file variable, @ref{global variables}) to +bypass the fat checking. + +@comment MANskip 1 + +@ignore +@unnumbered Name +mtools.conf - mtools configuration files + +@comment MANend-skip 5 +@section Description + +This manual page describes the configuration files for mtools. They +@comment MANskip 5 +@end ignore + + +@node Configuration, Commands, Common features, Top + + +@chapter How to configure mtools for your environment +@section Description +@cindex Configuration files +@vindex MTOOLSRC + + This sections explains the syntax of the configurations files for +mtools. The configuration files +@comment MANend-skip 5 +are called @file{@value{SYSCONFDIR}mtools.conf} and @file{~/.mtoolsrc}. If +the environmental variable @code{MTOOLSRC} is set, its contents is used +as the filename for a third configuration file. These configuration +files describe the following items: + +@itemize @bullet +@item Global configuration flags and variables +@item Per drive flags and variables +@end itemize + + +@menu +* configuration file location:: Where mtools looks for its configuration files +* general syntax:: The layout of the configuration files +* default values:: Why you don't need a configuration file in most cases +* global variables:: Variables that are independent of the drive +* per drive variables:: Variables that are specific to a given drive +* parsing order:: Location of configuration files and parsing order +* old style configuration:: Backwards compatibility +@end menu + +@node configuration file location, general syntax, Configuration, Configuration +@section Location of the configuration files + +@cindex Configuration file name +@cindex Name of configuration files +@cindex Location of configuration files + +@file{@value{SYSCONFDIR}mtools.conf} is the system-wide configuration file, +and @file{~/.mtoolsrc} is the user's private configuration file. + +On some systems, the system-wide configuration file is called +@file{/etc/default/mtools.conf} instead. + + +@node general syntax, default values, configuration file location, Configuration +@subsection General configuration file syntax +@cindex Syntax of the configuration file +@cindex Configuration file syntax + +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: +@display +name=value +@end display +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. + +Lines starting with a hash (@code{#}) 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). + +@node default values, global variables, general syntax, Configuration +@section Default values +@cindex Default values +@cindex Default configuration +@cindex Configuration file +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. + +@node global variables, per drive variables, default values, Configuration +@section Global variables +@cindex Global configuration variables +@cindex Drive independent configuration variables +@cindex Environmental variables +@vindex MTOOLS_SKIP_CHECK +@vindex MTOOLS_FAT_COMPATIBILITY +@vindex MTOOLS_LOWER_CASE +@vindex MTOOLS_NO_VFAT +@cindex FreeDOS + +Global flags may be set to 1 or to 0. + +The following global flags are recognized: + +@table @code +@item MTOOLS_SKIP_CHECK +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. +@item MTOOLS_FAT_COMPATIBILITY +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. +@item MTOOLS_LOWER_CASE +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. +@item MTOOLS_NO_VFAT +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. +@item MTOOLS_DOTTED_DIR +In a wide directory, prints the short name with a dot instead of spaces +separating the basename and the extension. +@item MTOOLS_NAME_NUMERIC_TAIL +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. +@item MTOOLS_TWENTY_FOUR_HOUR_CLOCK +If 1, uses the European notation for times (twenty four hour clock), +else uses the UK/US notation (am/pm) +@end table + +Example: +Inserting the following line into your configuration file instructs +mtools to skip the sanity checks: +@example + MTOOLS_SKIP_CHECK=1 +@end example + +Global variables may also be set via the environment: +@example + export MTOOLS_SKIP_CHECK=1 +@end example + +Global string variables may be set to any value: +@table @code +@item MTOOLS_DATE_STRING +The format used for printing dates of files. By default, is dd-mm-yyyy. +@end table + +@node per drive variables, parsing order, global variables, Configuration +@section Per drive flags and variables +@cindex Drive description +@cindex Drive configuration + +@menu +* general information:: What a drive description looks like +* location information:: Where is the drive data physically stored +* geometry description:: Describes the physical characteristics of + the media +* open flags:: Flags passed to the open system call when the + device is opened +* miscellaneous variables:: Variables which don't fit in either category +* miscellaneous flags:: Switch variables, which can be enabled or disabled +* multiple descriptions:: How to supply several descriptions for a + drive, to be tried one after the other. +@end menu + +@node general information, location information, per drive variables, per drive variables +@subsection General information +@cindex Drive description, example +@cindex Drive configuration, example +@vindex drive + +Per drive flags and values may be described in a drive section. A +drive section starts with +@code{drive} "@var{driveletter}" : + +Then follow variable-value pairs and flags. + +This is a sample drive description: +@example + drive a: + file="/dev/fd0" use_xdf=1 +@end example + +@node location information, geometry description, general information, per drive variables +@subsection Location information +@cindex Hdimage + +For each drive, you need to describe where its data is physically +stored (image file, physical device, partition, offset). + +@table @code +@item file +@cindex Image file +@cindex Name of device node +@cindex File name of device node +@vindex file +The name of the file or device holding the disk image. This is +mandatory. The file name should be enclosed in quotes. + +@item partition +@cindex DOSEMU hard disk image +@cindex Zip disks (partitions) +@cindex Jaz disks (partitions) +@cindex Syquest disks +@cindex Magneto-optical disks +@cindex OS/2 (layout of removable media) +@cindex Windows NT (layout of removable media) +@cindex Removable media +@cindex Partitioned image file +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 @code{offset} variable. The @code{partition} 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 @samp{giant floppy disks} which are +unpartitioned, OS/2 and Windows NT treat them like hard disks, +i.e. partitioned devices. The @code{partition} flag is also useful DOSEMU +hdimages. It is not recommended for hard disks for which direct access +to partitions is available through mounting. + +@item offset +@cindex Ram disk +@cindex Atari Ram disk +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. +@end table + +@node geometry description, open flags, location information, per drive variables +@subsection Disk Geometry Configuration +@cindex Disk Geometry +@cindex Configuration of disk geometry +@cindex Description of disk geometry +@cindex Format of disk +@cindex High density disk +@cindex Low density disk +@pindex mformat (geometry used for) + +Geometry information describes the physical characteristics about the +disk. Its has three purposes: + +@table @asis +@item 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. @xref{mformat}, for details. +@item 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. @xref{multiple descriptions}, for more details on +supplying several descriptions for one drive letter. + +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 (@file{/dev/fd0}, @file{/dev/fd1} 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). + +If you do not need filtering, but want still a default geometry for +mformatting, you may switch off filtering using the @code{mformat_only} +flag. + +If you want filtering, you should supply the @code{filter} flag. If you +supply a geometry, you must supply one of both flags. + +@item 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 @code{mformat_only} flag is supplied, no +initial configuration is done. + +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. +@end table + +Wrong geometry information may lead to very bizarre errors. That's why I +strongly recommend that you add the @code{mformat_only} flag to your +drive description, unless you really need filtering or initial geometry. + +The following geometry related variables are available: + +@table @code +@item cylinders +@itemx tracks +@vindex cylinders +@vindex tracks +The number of cylinders. (@code{cylinders} is the preferred form, +@code{tracks} is considered obsolete) +@item heads +@vindex heads +The number of heads (sides). +@item sectors +@vindex sectors +The number of sectors per track. +@end table + +Example: the following drive section describes a 1.44M drive: + +@example + drive a: + file="/dev/fd0H1440" + fat_bits=12 + cylinders=80 heads=2 sectors=18 + mformat_only +@end example + +The following shorthand geometry descriptions are available: + +@table @code +@item 1.44m +high density 3 1/2 disk. Equivalent to: +@code{fat_bits=12 cylinders=80 heads=2 sectors=18} +@item 1.2m +high density 5 1/4 disk. Equivalent to: +@code{fat_bits=12 cylinders=80 heads=2 sectors=15} +@item 720k +double density 3 1/2 disk. Equivalent to: +@code{fat_bits=12 cylinders=80 heads=2 sectors=9} +@item 360k +double density 5 1/4 disk. Equivalent to: +@code{fat_bits=12 cylinders=40 heads=2 sectors=9} +@end table + +The shorthand format descriptions may be amended. For example, +@code{360k sectors=8} +describes a 320k disk and is equivalent to: +@code{fat_bits=12 cylinders=40 heads=2 sectors=8} + +@node open flags, miscellaneous variables, geometry description, per drive variables +@subsection Open Flags +@vindex sync +@vindex nodelay +@vindex exclusive +@cindex open flags +@cindex synchronous writing +@cindex exclusive access to a drive + +Moreover, the following flags are available: + +@table @code +@item sync +All i/o operations are done synchronously +@item nodelay +The device or file is opened with the O_NDELAY flag. This is needed on +some non-Linux architectures. +@item exclusive +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. +@end table + + +@node miscellaneous variables, miscellaneous flags, open flags, per drive variables +@subsection General Purpose Drive Variables + +The following general purpose drive variables are available. Depending +to their type, these variables can be set to a string (precmd) or +an integer (all others) + +@table @code +@item fat_bits +@vindex fat_bits +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. +@item codepage +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 @code{default_codepage} parameter +(outside of any drive description). This parameters exists starting at +version 4.0.0 +@item precmd +@cindex Solaris (volcheck) +@cindex Executing commands 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. @code{precmd="volcheck -v"} in the +drive clause establishes the desired behavior. + +@item blocksize +@cindex raw device +@cindex character devices +@cindex blocksize +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. + +@end table + +Only the @code{file} variable is mandatory. The other parameters may +be left out. In that case a default value or an auto-detected value is +used. + + + +@node miscellaneous flags, multiple descriptions, miscellaneous variables, per drive variables +@subsection General Purpose Drive Flags + +A flag can either be set to 1 (enabled) or 0 (disabled). If the value is +omitted, it is enabled. For example, @code{scsi} is equivalent to +@code{scsi=1} + +@table @code +@item nolock +@cindex disable locking +@cindex locking (disabling it) +@cindex plain floppy: device xxx busy +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. + +@item scsi +@cindex setuid installation (needed for raw SCSI I/O) +@cindex Solaris (Raw access to SCSI devices such as Zip & Jaz) +@cindex SunOS (Raw access to SCSI devices such as Zip & Jaz) +@cindex Zip disks (raw SCSI access) +@cindex Jaz disks (raw SCSI access) +@cindex Syquest disks (raw SCSI access) +@cindex SCSI devices +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 @code{read} and @code{write} system calls, because the OS expects +them to contain a Sun specific "disk label". + +As raw SCSI access always uses the whole device, you need to specify the +"partition" flag in addition + +On some architectures, such as Solaris, mtools needs root privileges to +be able to use the @code{scsi} option. Thus mtools should be installed +setuid root on Solaris if you want to access Zip/Jaz drives. Thus, if +the @code{scsi} flag is given, @code{privileged} is automatically +implied, unless explicitly disabled by @code{privileged=0} + +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 +@file{@value{SYSCONFDIR}mtools.conf}, and not for those described in +@file{~/.mtoolsrc} or @file{$MTOOLSRC}. + +@item privileged +@cindex setuid installation +@cindex setgid installation +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 +@file{@value{SYSCONFDIR}mtools.conf}, not @file{~/.mtoolsrc} or +@file{$MTOOLSRC}). 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 @code{scsi=1} is set. + +Mtools only needs to be installed setuid if you use the +@code{privileged} or @code{scsi} drive variables. If you do not use +these options, mtools works perfectly well even when not installed +setuid root. + +@item vold +@cindex Solaris (vold) +@cindex Vold (mediamgr) + +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 @code{media_findname()} and +@code{media_oldaliases()} functions of the @code{volmgt} library. This +flag is only available if you configured mtools with the +@code{--enable-new-vold} option before compilation. + +@item swap +@cindex Atari +@cindex Wordswapped + +Consider the media as a word-swapped Atari disk. + +@item use_xdf +@cindex XDF disks (how to configure) +@vindex use_xdf +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. @xref{XDF}, for more details. +@item mformat_only +@vindex mformat_only +Tells mtools to use the geometry for this drive only for mformatting and +not for filtering. + +@item filter +@vindex filter +Tells mtools to use the geometry for this drive both for mformatting and +filtering. + +@item remote +Tells mtools to connect to floppyd (@pxref{floppyd}). +@end table + + +@node multiple descriptions, , miscellaneous flags, per drive variables +@subsection Supplying multiple descriptions for a drive + +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: + +@enumerate +@item +because the geometry is not appropriate, +@item +because there is no disk in the drive, +@item +or because of other problems. +@end enumerate + +Multiple definitions are useful when using physical devices which are +only able to support one single disk geometry. +Example: +@example + drive a: file="/dev/fd0H1440" 1.44m + drive a: file="/dev/fd0H720" 720k +@end example + +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. + +You may also use multiple drive descriptions to access both of your +physical drives through one drive letter: + +@example + drive z: file="/dev/fd0" + drive z: file="/dev/fd1" +@end example + +With this description, @code{mdir z:} accesses your first physical +drive if it contains a disk. If the first drive doesn't contain a disk, +mtools checks the second drive. + +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 @code{drive+} or @code{+drive} +keywords instead of @code{drive}. 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. + +@node parsing order, old style configuration, per drive variables, Configuration +@section Location of configuration files and parsing order +@cindex Parsing order +@cindex Configuration file parsing order +@cindex Configuration file name (parsing order) +@cindex Name of configuration files (parsing order) +@cindex Location of configuration files (parsing order) + +The configuration files are parsed in the following order: +@enumerate +@item +compiled-in defaults +@item +@file{@value{SYSCONFDIR}mtools.conf} +@item +@file{~/.mtoolsrc}. +@item +@file{$MTOOLSRC} (file pointed by the @code{MTOOLSRC} environmental +variable) +@end enumerate + +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 @file{@value{SYSCONFDIR}mtools.conf} and drives C and D may be +defined in @file{~/.mtoolsrc} However, if @file{~/.mtoolsrc} also +defines drive A, this new description would override the description of +drive A in @file{@value{SYSCONFDIR}mtools.conf} 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 @code{+drive} or @code{drive+} +keyword. + +@node old style configuration, , parsing order, Configuration +@section Backwards compatibility with old configuration file syntax +@cindex Backwards compatibility +@cindex Old configuration file syntax +@cindex Configuration file, old syntax + +The syntax described herein is new for version @code{mtools-3.0}. 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. + +@comment MANskip 5 + +@node Commands, Compiling mtools, Configuration, Top +@chapter Command list +@cindex Command list +@cindex List of available commands + + This section describes the available mtools commands, and the command +line parameters that each of them accepts. Options which are common to +all mtools commands are not described here, @ref{arguments} for a +description of those. + +@menu +* floppyd:: floppy daemon to run on your X server box +* floppyd_installtest:: small utility to check for the presence of floppyd +* mattrib:: change MS-DOS file attribute flags +* mbadblocks:: tests a floppy disk, and marks the bad blocks in the FAT +* mcat:: same as cat. Only useful with floppyd. +* mcd:: change MS-DOS directory +* mclasserase:: erase memory card +* mcopy:: copy MS-DOS files to/from Unix +* mdel:: delete an MS-DOS file +* mdeltree:: recursively delete an MS-DOS directory +* mdir:: display an MS-DOS directory +* mdu:: list space occupied by directory and its contents +* mformat:: add an MS-DOS file system to a low-level formatted floppy disk +* minfo:: get information about an MS-DOS file system. +* mlabel:: make an MS-DOS volume label +* mkmanifest:: makes a list of short name equivalents +* mmd:: make an MS-DOS subdirectory +* mmount:: mount an MS-DOS disk +* mpartition:: create an MS-DOS as a partition +* mrd:: remove an MS-DOS subdirectory +* mmove:: move or rename an MS-DOS file or subdirectory +* mren:: rename an existing MS-DOS file +* mshortname:: shows the short name of a file +* mshowfat:: shows the FAT map of a file +* mtoolstest:: tests and displays the configuration +* mtype:: display contents of an MS-DOS file +* mzip:: zip disk specific commands +@end menu + +@node floppyd, floppyd_installtest, Commands, Commands +@section Floppyd +@pindex floppyd +@cindex X terminal +@cindex remote floppy access + +@code{Floppyd} is used as a server to grant access to the floppy drive +to clients running on a remote machine, just as an X server grants +access to the display to remote clients. It has the following syntax: + +@code{floppyd} [@code{-d}] [@code{-l}] [@code{-s} @var{port}] [@code{-r} +@var{user}] [@code{-b} @var{ipaddr}] [@code{-x} @var{display}] @var{devicenames} + + +@code{floppyd} is always associated with an X server. It runs on the +same machine as its X server, and listens on port 5703 and above. + +@subsection Authentication + +@code{floppyd} authenticates remote clients using the @code{Xauthority} +protocol. Xhost authentication is not supported. Each floppyd is +associated with an X server. When a remote client attempts to connect +to floppyd, it sends floppyd the X authority record corresponding to +floppyd's X server. Floppyd in turn then tries to open up a connection +to the X server in order to verify the authenticity of the xauth record. +If the connection to the X server succeeds, the client is granted +access. +@code{DISPLAY}. + +@strong{Caution}: In order to make authentication work correctly, the +local host should @strong{not} be listed in the @code{xhost} list of +allowed hosts. + Indeed, hosts listed in @code{xhost} do not need a correct +@code{Xauthority} cookie to connect to the X server. As @code{floppyd} +runs on the same host as the X server, all its probe connection would +succeed even for clients who supplied a bad cookie. This means that +your floppy drive would be open to the world, i.e. a huge security hole. + If your X server does not allow you to remove @code{localhost:0} and +@code{:0} from the @code{xhost} list, you can prevent floppyd from +probing those display names with the @code{-l} option. + +@subsection Command line options + +@table @code +@item d +Daemon mode. Floppyd runs its own server loop. Do not supply this if +you start floppyd from @code{inetd.conf} +@item s @var{port} +Port number for daemon mode. Default is 5703 + @var{displaynumber}. +This flag implies daemon mode. For example, for display +@code{hitchhiker:5}, the port would be 5708. +@item b @var{ipaddr} +Bind address (for multi homed hosts). This flag implies daemon mode +@item r @var{user} +Run the server under as the given user +@item x @var{display} +X display to use for authentication. By default, this is taken from the +@code{DISPLAY} variable. If neither the @code{x} attribute is present +nor @code{DISPLAY} is set, floppyd uses @code{:0.0}. +@end table + +@var{devicenames} is a list of device nodes to be opened. Default +is @code{/dev/fd0}. Multiple devices are only supported on mtools +versions newer than 3.9.11. + + +@subsection Connecting to floppyd + + In order to use floppyd, add the flag @code{remote} to the device +description in your @file{~/.mtoolsrc} file. If the flag @code{remote} +is given, the @code{file} parameter of the device description is taken +to be a remote address. It's format is the following: +@var{hostname}@code{:}@var{displaynumber}[@code{/}[@var{baseport}][@code{/}@var{drive}]]. When +using this entry, mtools connects to port +@var{baseport}+@var{displaynumber} at @var{hostname}. By default +@var{baseport} is 5703. The drive parameter is to distinguish among +multiple drives associated with a single display (only mtools versions +more recent than 3.9.11) + +@subsection Examples: + + The following starts a floppy daemon giving access to @file{/dev/fd0}, +listening on the default port 5703, tied to the default X servers: + +@example +floppyd -d /dev/fd0 +@end example + + Each of the following starts a floppy daemon giving access to +@file{/dev/fd1}, tied to the :1 local X servers, and listening on port +5704. We assume that the local host is named @code{hitchhiker}. + +@example +floppyd -d /dev/fd0 +floppyd -d -x :1 -p 5704 /dev/fd0 +@end example + + If you want to start floppyd by @code{inetd} instead of running it as a +daemon, insert the following lines into @file{/etc/services}: +@example +# floppy daemon +floppyd-0 5703/tcp # floppy daemon for X server :0 +floppyd-1 5704/tcp # floppy daemon for X server :1 +@end example + + And insert the following into @file{/etc/inetd.conf} (assuming that you +have defined a user named floppy in your @file{/etc/passwd}): + +@example +# floppy daemon +floppyd-0 stream tcp wait floppy /usr/sbin/floppyd floppyd /dev/fd0 +floppyd-1 stream tcp wait floppy /usr/sbin/floppyd floppyd -x :1 /dev/fd0 +@end example + + Note that you need to supply the X display names for the second +floppyd. This is because the port is opened by inetd.conf, and hence +floppyd cannot know its number to interfere the display number. + + +On the client side, insert the following into your @file{~/.mtoolsrc} +to define a drive letter accessing floppy drive in your X terminal: +@example +drive x: file="$DISPLAY" remote +@end example + +If your X terminal has more than one drive, you may access the +additional drives as follows: +@example +drive y: file="$DISPLAY//1" remote +drive z: file="$DISPLAY//2" remote +@end example + +@node floppyd_installtest, mattrib, floppyd, Commands +@section Floppyd_installtest +@pindex floppyd_installtest +@cindex X terminal +@cindex remote floppy access + +@code{Floppyd_installtest} is used to check for the presence of a running +floppyd daemon. This is useful, if you have a small front-end script to +mtools, which decides whether to use floppyd or not. + +@code{floppyd_installtest} [@code{-f}] Connect-String + +If the @code{-f} option is specified, @code{floppyd_installtest} does a +full X-Cookie authentication and complains if this does not work. + +The connect-String has the format described in the floppyd-section: +@var{hostname}@code{:}@var{displaynumber}[@code{/}@var{baseport}] + +@node mattrib, mbadblocks, floppyd_installtest, Commands +@section Mattrib +@pindex mattrib +@cindex Changing file attributes +@cindex Hidden files +@cindex Read-only files (changing the attribute) +@cindex System files +@cindex Archive bit + +@code{Mattrib} is used to change MS-DOS file attribute flags. It has the +following syntax: + +@code{mattrib} [@code{-a|+a}] [@code{-h|+h}] [@code{-r|+r}] +[@code{-s|+s}] [@code{-/}] [@code{-p}] [@code{-X}] @var{msdosfile} [ @var{msdosfiles} @dots{} ] + +@code{Mattrib} adds attribute flags to an MS-DOS file (with the +`@code{+}' operator) or remove attribute flags (with the `@code{-}' +operator). + +@code{Mattrib} supports the following attribute bits: + +@table @code +@item a +Archive bit. Used by some backup programs to indicate a new file. +@item r +Read-only bit. Used to indicate a read-only file. Files with this bit +set cannot be erased by @code{DEL} nor modified. +@item s +System bit. Used by MS-DOS to indicate a operating system file. +@item h +Hidden bit. Used to make files hidden from @code{DIR}. +@end table + +@code{Mattrib} supports the following command line flags: +@table @code +@item / +Recursive. Recursively list the attributes of the files in the subdirectories. +@item X +Concise. Prints the attributes without any whitespace padding. If +neither the "/" option is given, nor the @var{msdosfile} contains a +wildcard, and there is only one MS-DOS file parameter on the command +line, only the attribute is printed, and not the filename. This option +is convenient for scripts +@item p +Replay mode. Outputs a series of mformat commands that will reproduce +the current situation, starting from a situation as left by untarring +the MS-DOS file system. Commands are only output for attribute settings +that differ from the default (archive bit set for files, unset for +directories). This option is intended to be used in addition to +tar. The @code{readonly} attribute is not taken into account, as tar can +set that one itself. +@end table + +@node mbadblocks, mcat, mattrib, Commands +@section Mbadblocks +@pindex mbadblocks +@cindex Marking blocks as bad +@cindex Bad blocks +@cindex Read errors + +The @code{mbadblocks} command is used to mark some clusters on an +MS-DOS filesystem bad. It has the following syntax: + +@code{mbadblocks} [@code{-s} @var{sectorlist}|@code{-c} @var{clusterlist}|-w] @var{drive}@code{:} + +If no command line flags are supplied, @code{Mbadblocks} scans an +MS-DOS filesystem for bad blocks by simply trying to read them and +flag them if read fails. All blocks that are unused are scanned, and +if detected bad are marked as such in the FAT. + +This command is intended to be used right after @code{mformat}. It is +not intended to salvage data from bad disks. + + +@subsection Command line options + +@table @code +@item c @var{file} +Use a list of bad clusters, rather than scanning for bad clusters +itself. +@item s @var{file} +Use a list of bad sectors (counted from beginning of filesystem), +rather than trying for bad clusters itself. +@item w +Write a random pattern to each cluster, then read it back and flag +cluster as bad if mismatch. Only free clusters are tested in such a +way, so any file data is preserved. +@end table + +@subsection Bugs +@code{Mbadblocks} should (but doesn't yet :-( ) also try to salvage bad +blocks which are in use by reading them repeatedly, and then mark them +bad. + +@node mcat, mcd, mbadblocks, Commands +@section Mcat + +The @code{mcat} command is used to copy an entire disk image from or +to the floppy device. It uses the following syntax: + +@code{mcat} [@code{-w}] @var{drive}@code{:} +@pindex mcat +@cindex Copying an entire disk image +@cindex Disk image +@cindex Floppyd cat + +@code{Mcat} performs the same task as the Unix @code{cat} command. It +is included into the mtools package, since @code{cat} cannot access +remote floppy devices offered by the mtools floppy daemon. +Now it is possible to create boot floppies remotely. + +The default operation is reading. The output is written to stdout. + +If the @code{-w} option is specified, mcat reads a disk-image from +stdin and writes it to the given device. +@strong{Use this carefully!} Because of the low-level nature of this +command, it will happily destroy any data written before on the +disk without warning! + +@node mcd, mclasserase, mcat, Commands +@section Mcd +@pindex mcd +@cindex Directory (changing) +@cindex Working directory +@cindex Current working directory (changing the) +@cindex Default directory (changing the) +@cindex Mcwd file + +The @code{mcd} command is used to change the mtools working directory +on the MS-DOS disk. It uses the following syntax: + +@example +@code{mcd} [@var{msdosdirectory}] +@end example + +Without arguments, @code{mcd} reports the current device and working +directory. Otherwise, @code{mcd} changes the current device and current +working directory relative to an MS-DOS file system. + +The environmental variable @code{MCWD} may be used to locate the file +where the device and current working directory information is stored. +The default is @file{$HOME/.mcwd}. Information in this file is ignored +if the file is more than 6 hours old. + +@code{Mcd} returns 0 on success or 1 on failure. + +Unlike MS-DOS versions of @code{CD}, @code{mcd} can be used to change to +another device. It may be wise to remove old @file{.mcwd} files at logout. + +@node mclasserase, mcopy, mcd, Commands +@section Mclasserase +@pindex mclasserase +@cindex Memory Card +@cindex Physically erase + +The @code{mclasserase} command is used to wipe memory cards by +overwriting it three times: first with @code{0xff}, then with +@code{0x00}, then with @code{0xff} again. The command uses the following +syntax: + +@example +@code{mclasserase} [@code{-d}] @var{msdosdrive} +@end example + +MS-DOS drive is optional, if none is specified, use @code{A:}. If more than +one drive are specified, all but the last are ignored. + +@code{Mclasserase} accepts the following command line options: + +@table @code +@item d +Stop after each erase cycle, for testing purposes +@item p +Not yet implemented +@end table + + +@code{Mclasserase} returns 0 on success or -1 on failure. + + +@node mcopy, mdel, mclasserase, Commands +@section Mcopy +@pindex mcopy +@cindex Reading MS-DOS files +@cindex Writing MS-DOS files +@cindex Copying MS-DOS files +@cindex Concatenating MS-DOS files +@cindex Text files +@cindex CR/LF conversions + +The @code{mcopy} command is used to copy MS-DOS files to and from +Unix. It uses the following syntax: + +@example +@code{mcopy} [@code{-bspanvmQT}] [@code{-D} @var{clash_option}] @var{sourcefile} @var{targetfile} +@code{mcopy} [@code{-bspanvmQT}] [@code{-D} @var{clash_option}] @var{sourcefile} [ @var{sourcefiles}@dots{} ] @var{targetdirectory} +@code{mcopy} [@code{-tnvm}] @var{MSDOSsourcefile} +@end example + + + +@code{Mcopy} copies the specified file to the named file, or copies +multiple files to the named directory. The source and target can be +either MS-DOS or Unix files. + +The use of a drive letter designation on the MS-DOS files, 'a:' for +example, determines the direction of the transfer. A missing drive +designation implies a Unix file whose path starts in the current +directory. If a source drive letter is specified with no attached file +name (e.g. @code{mcopy a: .}), all files are copied from that drive. + +If only a single, MS-DOS source parameter is provided (e.g. "mcopy +a:foo.exe"), an implied destination of the current directory +(`@code{.}') is assumed. + +A filename of `@code{-}' means standard input or standard output, depending +on its position on the command line. + +@code{Mcopy} accepts the following command line options: + +@table @code +@item t +Text file transfer. Mcopy translates incoming carriage return/line +feeds to line feeds when copying from MS-DOS to Unix, and vice-versa when +copying from Unix to MS-DOS. +@item b +Batch mode. Optimized for huge recursive copies, but less secure if a +crash happens during the copy. +@item s +Recursive copy. Also copies directories and their contents +@item p +Preserves the attributes of the copied files +@item Q +When mcopying multiple files, quits as soon as one copy fails (for +example due to lacking storage space on the target disk) +@item a +Text (ASCII) file transfer. @code{ASCII} translates incoming carriage +return/line feeds to line feeds. +@item T +Text (ASCII) file transfer with character set conversion. Differs from +@code{-a} in the @code{ASCII} also translates incoming PC-8 characters +to ISO-8859-1 equivalents as far as possible. When reading DOS files, +untranslatable characters are replaced by '@code{#}'; when writing DOS files, +untranslatable characters are replaced by '@code{.}'. +@item n +No confirmation when overwriting Unix files. @code{ASCII} doesn't warn +the user when overwriting an existing Unix file. If the target file already exists, +and the @code{-n} option is not in effect, @code{mcopy} asks whether to +overwrite the file or to rename the new file (@ref{name clashes}) for +details). In order to switch off confirmation for DOS files, use @code{-o}. +@item m +Preserve the file modification time. +@item v +Verbose. Displays the name of each file as it is copied. +@end table + +@subsection Bugs +Unlike MS-DOS, the '+' operator (append) from MS-DOS is not +supported. However, you may use @code{mtype} to produce the same effect: +@example +mtype a:file1 a:file2 a:file3 >unixfile +mtype a:file1 a:file2 a:file3 | mcopy - a:msdosfile +@end example + +@node mdel, mdeltree, mcopy, Commands +@section Mdel +@pindex mdel +@cindex removing MS-DOS files +@cindex erasing MS-DOS files +@cindex deleting MS-DOS files + +The @code{mdel} command is used to delete an MS-DOS file. Its syntax +is: + +@display +@code{mdel} [@code{-v}] @var{msdosfile} [ @var{msdosfiles} @dots{} ] +@end display + +@code{Mdel} deletes files on an MS-DOS file system. + +@code{Mdel} asks for verification prior to removing a read-only file. + +@node mdeltree, mdir, mdel, Commands +@section Mdeltree +@pindex mdeltree +@cindex removing an MS-DOS directory recursively +@cindex erasing an MS-DOS directory recursively +@cindex deleting an MS-DOS directory recursively +@cindex recursively removing an MS-DOS directory + +The @code{mdeltree} command is used to delete an MS-DOS file. Its syntax +is: + +@display +@code{mdeltree} [@code{-v}] @var{msdosdirectory} [@var{msdosdirectories}@dots{}] +@end display + +@code{Mdeltree} removes a directory and all the files and subdirectories +it contains from an MS-DOS file system. An error occurs if the directory +to be removed does not exist. + +@node mdir, mdu, mdeltree, Commands +@section Mdir +@pindex mdir +@cindex Read-only files (listing them) +@cindex Listing a directory +@cindex Directory listing + +The @code{mdir} command is used to display an MS-DOS directory. Its +syntax is: + +@code{mdir} [@code{-/}] [@code{-f}] [@code{-w}] [@code{-a}] [@code{-b}] @var{msdosfile} [ @var{msdosfiles}@dots{}] + +@code{Mdir} +displays the contents of MS-DOS directories, or the entries for some +MS-DOS files. + +@code{Mdir} supports the following command line options: + +@table @code +@item / +Recursive output, just like MS-DOS' @code{-s} option +@item w +Wide output. With this option, @code{mdir} prints the filenames across +the page without displaying the file size or creation date. +@item a +Also list hidden files. +@item f +Fast. Do not try to find out free space. On larger disks, finding out +the amount of free space takes up some non trivial amount of time, as +the whole FAT must be read in and scanned. The @code{-f} flag bypasses +this step. This flag is not needed on FAT32 file systems, which store +the size explicitly. +@item b +Concise listing. Lists each directory name or filename, one per line +(including the filename extension). This switch displays no heading +information and no summary. Only a newline separated list of pathnames +is displayed. +@end table + +An error occurs if a component of the path is not a directory. + +@node mdu, mformat, mdir, Commands +@section Mdu +@pindex mdu +@cindex Space occupied by directories and files +@cindex du +@cindex Listing space occupied by directories and files +@cindex Occupation of space by directories and files + +@code{Mdu} is used to list the space occupied by a directory, its +subdirectories and its files. It is similar to the @code{du} command on +Unix. The unit used are clusters. Use the minfo command to find out +the cluster size. + +@code{mdu} [@code{-a}] [ @var{msdosfiles} @dots{} ] + + +@table @code +@item a +All files. List also the space occupied for individual files. +@item s +Only list the total space, don't give details for each subdirectory. +@end table + + + +@node mformat, mkmanifest, mdu, Commands +@section Mformat +@pindex mformat +@cindex Initializing disks +@cindex Formatting disks +@cindex File system creation + +The @code{mformat} command is used to add an MS-DOS file system to a +low-level formatted diskette. Its syntax is: + +@display +@code{mformat} [@code{-t} @var{cylinders}|@code{-T} @var{tot_sectors}] [@code{-h} @var{heads}] [@code{-s} @var{sectors}] + [@code{-f} @var{size}] [@code{-1}] [@code{-4}] [@code{-8}] + [@code{-v} @var{volume_label}] + [@code{-F}] [@code{-S} @var{sizecode}] + [@code{-M} @var{software_sector_size}] + [@code{-N} @var{serial_number}] [@code{-a}] + [@code{-C}] [@code{-H} @var{hidden_sectors}] [@code{-I} @var{fsVersion}] + [@code{-r} @var{root_sectors}] [@code{-L} @var{fat_len}] + [@code{-B} @var{boot_sector}] [@code{-k}] + [@code{-m} @var{media_descriptor}] + [@code{-K} @var{backup_boot}] + [@code{-c} @var{clusters_per_sector}] + [@code{-d} @var{fat_copies}] + [@code{-X}] [@code{-2} @var{sectors_on_track_0}] [@code{-3}] + [@code{-0} @var{rate_on_track_0}] [@code{-A} @var{rate_on_other_tracks}] + @var{drive:} +@end display + +@code{Mformat} adds a minimal MS-DOS file system (boot sector, FAT, and +root directory) to a diskette that has already been formatted by a Unix +low-level format. + + +The following options are supported: (The S, 2, 1 and M options may not +exist if this copy of mtools has been compiled without the USE_2M +option) + +The following options are the same as for MS-DOS's format command: + +@comment xMANoptions + +@table @code +@item v +Specifies the volume label. A volume label identifies the disk and can +be a maximum of 11 characters. If you omit the -v switch, mformat will +assign no label to the disk. +@item f +Specifies the size of the DOS file system to format. Only a certain +number of predefined sizes are supported by this flag; for others use +the -h/-t/-s flags. The following sizes are supported: +@table @asis +@item 160 +160K, single-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD) +@item 180 +160K, single-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD) +@item 320 +320K, double-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD) +@item 360 +360K, double-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD) +@item 720 +720K, double-sided, 9 sectors per track, 80 cylinders (for 3 1/2 DD) +@item 1200 +1200K, double-sided, 15 sectors per track, 80 cylinders (for 5 1/4 HD) +@item 1440 +1440K, double-sided, 18 sectors per track, 80 cylinders (for 3 1/2 HD) +@item 2880 +2880K, double-sided, 36 sectors per track, 80 cylinders (for 3 1/2 ED) +@end table + +@item t +Specifies the number of tracks on the disk. +@item T +Specifies the number of total sectors on the disk. Only one of these 2 +options may be specified (tracks or total sectors) +@item h +The number of heads (sides). +@item s +Specifies the number of sectors per track. If the 2m option is given, +number of 512-byte sector equivalents on generic tracks (i.e. not head 0 +track 0). If the 2m option is not given, number of physical sectors per +track (which may be bigger than 512 bytes). + +@item 1 +Formats a single side (equivalent to -h 1) + +@item 4 +Formats a 360K double-sided disk (equivalent to -f 360). When used +together with -the 1 switch, this switch formats a 180K disk + +@item 8 +Formats a disk with 8 sectors per track. + +@end table + +MS-DOS format's @code{q}, @code{u} and @code{b} options are not +supported, and @code{s} has a different meaning. + +The following options are specific to mtools: + +@table @code + +@item F +Format the partition as FAT32. + +@item S +The size code. The size of the sector is 2 ^ (sizecode + 7). +@item X +formats the disk as an XDF disk. @xref{XDF}, for more details. The disk +has first to be low-level formatted using the xdfcopy utility included +in the fdutils package. XDF disks are used for instance for OS/2 install +disks. +@item 2 +2m format. The parameter to this option describes the number of +sectors on track 0, head 0. This option is recommended for sectors +bigger than normal. +@item 3 +don't use a 2m format, even if the current geometry of the disk is a 2m +geometry. +@item 0 +Data transfer rate on track 0 +@item A +Data transfer rate on tracks other than 0 +@item M +software sector size. This parameter describes the sector size in bytes used +by the MS-DOS file system. By default it is the physical sector size. +@item N +Uses the requested serial number, instead of generating one +automatically +@item a +If this option is given, an Atari style serial number is generated. +Ataris store their serial number in the OEM label. +@item C +creates the disk image file to install the MS-DOS file system on +it. Obviously, this is useless on physical devices such as floppies +and hard disk partitions, but is interesting for image files. +@item H +number of hidden sectors. This parameter is useful for formatting hard +disk partition, which are not aligned on track boundaries (i.e. first +head of first track doesn't belong to the partition, but contains a +partition table). In that case the number of hidden sectors is in +general the number of sectors per cylinder. This is untested. +@item I +Sets the fsVersion id when formatting a FAT32 drive. In order to find +this out, run minfo on an existing FAT32 drive, and mail me about it, so +I can include the correct value in future versions of mtools. +@item c +Sets the size of a cluster (in sectors). If this cluster size would +generate a FAT that too big for its number of bits, mtools automatically +increases the cluster size, until the FAT is small enough. +@item d +Sets the number of FAT copies. Default is 2. This setting can also be +specified using the @code{MTOOLS_NFATS} environment variable. +@item r +Sets the size of the root directory (in sectors). Only applicable to 12 +and 16 bit FATs. This setting can also be specified using the +@code{MTOOLS_DIR_LEN} environment variable. +@item L +Sets the length of the FAT. +@item B +Use the boot sector stored in the given file or device, instead of using +its own. Only the geometry fields are updated to match the target disks +parameters. +@item k +Keep the existing boot sector as much as possible. Only the geometry +fields and other similar file system data are updated to match the target +disks parameters. +@item K +Sets the sector number where the backup of the boot sector should be +stored (only relevant on FAT32). + +@item m +Use a non-standard media descriptor byte for this disk. The media +descriptor is stored at position 21 of the boot sector, and as first +byte in each FAT copy. Using this option may confuse DOS or older mtools +version, and may make the disk unreadable. Only use if you know what you +are doing. + +@end table + +To format a diskette at a density other than the default, you must supply +(at least) those command line parameters that are different from the +default. + +@code{Mformat} returns 0 on success or 1 on failure. + +It doesn't record bad block information to the Fat, use +@code{mbadblocks} for that. + +@node mkmanifest, minfo, mformat, Commands +@section Mkmanifest +@pindex mkmanifest +@cindex packing list + +The @code{mkmanifest} command is used to create a shell script (packing +list) to restore Unix filenames. Its syntax is: + +@code{mkmanifest} [ @var{files} ] + +@code{Mkmanifest} creates a shell script that aids in the restoration of +Unix filenames that got clobbered by the MS-DOS filename restrictions. +MS-DOS filenames are restricted to 8 character names, 3 character +extensions, upper case only, no device names, and no illegal characters. + + +The mkmanifest program is compatible with the methods used in +@code{pcomm, arc,} and @code{mtools} to change perfectly good Unix +filenames to fit the MS-DOS restrictions. This command is only useful if +the target system which will read the diskette cannot handle VFAT long +names. + +@subsection Example +You want to copy the following Unix files to a MS-DOS diskette (using the +@code{mcopy} command). + +@example + very_long_name + 2.many.dots + illegal: + good.c + prn.dev + Capital +@end example + +@code{ASCII} +converts the names to: + +@example + very_lon + 2xmany.dot + illegalx + good.c + xprn.dev + capital +@end example + +The command: +@example +mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital >manifest +@end example +would produce the following: +@example + mv very_lon very_long_name + mv 2xmany.dot 2.many.dots + mv illegalx illegal: + mv xprn.dev prn.dev + mv capital Capital +@end example + +Notice that "good.c" did not require any conversion, so it did not +appear in the output. + +Suppose I've copied these files from the diskette to another Unix +system, and I now want the files back to their original names. If the +file "manifest" (the output captured above) was sent along with those +files, it could be used to convert the filenames. + +@subsection Bugs + +The short names generated by @code{mkmanifest} follow the old convention +(from mtools-2.0.7) and not the one from Windows 95 and mtools-3.0. + + +@node minfo, mlabel, mkmanifest, Commands +@section Minfo +@pindex minfo +@cindex mformat parameters +@cindex getting parameters of a MS-DOS file system + +The @code{minfo} command prints the parameters of a MS-DOS file system, such +as number of sectors, heads and cylinders. It also prints an mformat +command line which can be used to create a similar MS-DOS file system on +another media. However, this doesn't work with 2m or XDF media, and +with MS-DOS 1.0 file systems +@display +@code{minfo} @var{drive}: +@end display + +Minfo supports the following option: +@table @code +@item v +Prints a hexdump of the boot sector, in addition to the other information +@end table + + +@node mlabel, mmd, minfo, Commands +@section Mlabel +@pindex mlabel +@cindex Labeling a disk +@cindex Disk label + +The @code{mlabel} command adds a volume label to a disk. Its syntax is: +@display +@code{mlabel} [@code{-vcsn}] [@code{-N} @var{serial}] @var{drive}:[@var{new_label}] +@end display + +@code{Mlabel} displays the current volume label, if present. If +@var{new_label} is not given, and if neither the @code{c} nor the +@code{s} options are set, it prompts the user for a new volume label. +To delete an existing volume label, press return at the prompt. + +The label is limited to 11 single-byte characters, +e.g. @code{Name1234567}. + +Reasonable care is taken to create a valid MS-DOS volume label. If an +invalid label is specified, @code{mlabel} changes the label (and +displays the new label if the verbose mode is set). @code{Mlabel} +returns 0 on success or 1 on failure. + +Mlabel supports the following options: +@table @code +@item c +Clears an existing label, without prompting the user +@item s +Shows the existing label, without prompting the user. +@item n +Assigns a new (random) serial number to the disk +@item N @var{serial} +Sets the supplied serial number. The serial number should be supplied as +an 8 digit hexadecimal number, without spaces +@end table + + +@node mmd, mmount, mlabel, Commands +@section Mmd +@pindex mmd +@cindex Making a directory +@cindex Creating a directory +@cindex Directory creation +@cindex Subdirectory creation + +The @code{mmd} command is used to make an MS-DOS subdirectory. Its +syntax is: + +@code{mmd} [@code{-D} @var{clash_option}] @var{msdosdirectory} [ +@var{msdosdirectories}@dots{} ] + +@code{Mmd} makes a new directory on an MS-DOS file system. An error occurs +if the directory already exists. + + +@node mmount, mmove, mmd, Commands +@section Mmount +@pindex mmount +@cindex Linux enhancements (mmount) +@cindex Mounting a disk +@cindex High capacity formats, mounting + +The @code{mmount} command is used to mount an MS-DOS disk. It is only +available on Linux, as it is only useful if the OS kernel allows to +configure the disk geometry. Its syntax is: + +@code{mmount} @var{msdosdrive} [@var{mountargs}] + +@code{Mmount} +reads the boot sector of an MS-DOS disk, configures the drive geometry, +and finally mounts it passing +@code{mountargs} to @code{mount. } +If no mount arguments are specified, the name of the device is +used. If the disk is write protected, it is automatically mounted read +only. + + +@node mmove, mpartition, mmount, Commands +@section Mmove +@pindex mmove +@cindex Moving files (mmove) +@cindex Renaming files (mmove) + +The @code{mmove} command is used to moves or renames an existing MS-DOS +file or subdirectory. +@display +@code{mmove} [@code{-v}] [@code{-D} @var{clash_option}] @var{sourcefile} @var{targetfile} +@code{mmove} [@code{-v}] [@code{-D} @var{clash_option}] @var{sourcefile} [ @var{sourcefiles}@dots{} ] @var{targetdirectory} +@end display +@code{Mmove} moves or renames an existing MS-DOS file or +subdirectory. Unlike the MS-DOS version of @code{MOVE}, @code{mmove} is +able to move subdirectories. Files or directories can only be moved +within one file system. Data cannot be moved from MS-DOS to Unix or +vice-versa. If you omit the drive letter from the target file or +directory, the same letter as for the source is assumed. If you omit +the drive letter from all parameters, drive a: is assumed by default. + +@node mpartition, mrd, mmove, Commands +@section Mpartition +@pindex mpartition +@cindex partitions (creating) +@cindex Zip disks (partitioning them) +@cindex Jaz disks (partitioning them) + +The @code{mpartition} command is used to create MS-DOS file systems as +partitions. This is intended to be used on non-Linux systems, +i.e. systems where fdisk and easy access to SCSI devices are not +available. This command only works on drives whose partition variable +is set. + +@display +@code{mpartition} @code{-p} @var{drive} +@code{mpartition} @code{-r} @var{drive} +@code{mpartition} @code{-I} [@code{-B} @var{bootSector}] @var{drive} +@code{mpartition} @code{-a} @var{drive} +@code{mpartition} @code{-d} @var{drive} +@code{mpartition} @code{-c} [@code{-s} @var{sectors}] [@code{-h} @var{heads}] +[@code{-t} @var{cylinders}] [@code{-v} [@code{-T} @var{type}] [@code{-b} +@var{begin}] [@code{-l} length] [@code{-f}] + +@end display + +Mpartition supports the following operations: + +@table @code +@item p +Prints a command line to recreate the partition for the drive. Nothing +is printed if the partition for the drive is not defined, or an +inconsistency has been detected. If verbose (@code{-v}) is also set, +prints the current partition table. +@item r +Removes the partition described by @var{drive}. +@item I +Initializes the partition table, and removes all partitions. +@item c +Creates the partition described by @var{drive}. +@item a +"Activates" the partition, i.e. makes it bootable. Only one partition +can be bootable at a time. +@item d +"Deactivates" the partition, i.e. makes it unbootable. +@end table + +If no operation is given, the current settings are printed. + +For partition creations, the following options are available: +@table @code +@item s @var{sectors} +The number of sectors per track of the partition (which is also the +number of sectors per track for the whole drive). +@item h @var{heads} +The number of heads of the partition (which is also the number of heads +for the whole drive). By default, the geometry information (number of +sectors and heads) is figured out from neighboring partition table +entries, or guessed from the size. +@item t @var{cylinders} +The number of cylinders of the partition (not the number of cylinders of +the whole drive. +@item b @var{begin} +The starting offset of the partition, expressed in sectors. If begin is +not given, mpartition lets the partition begin at the start of the disk +(partition number 1), or immediately after the end of the previous +partition. +@item l @var{length} +The size (length) of the partition, expressed in sectors. If end is not +given, mpartition figures out the size from the number of sectors, heads +and cylinders. If these are not given either, it gives the partition +the biggest possible size, considering disk size and start of the next +partition. +@end table + +The following option is available for all operation which modify the +partition table: +@table @code +@item f +Usually, before writing back any changes to the partition, mpartition +performs certain consistency checks, such as checking for overlaps and +proper alignment of the partitions. If any of these checks fails, the +partition table is not changes. The @code{-f} allows you to override +these safeguards. +@end table + +The following options are available for all operations: +@table @code +@item v +Together with @code{-p} prints the partition table as it is now (no +change operation), or as it is after it is modified. +@item vv +If the verbosity flag is given twice, mpartition will print out a +hexdump of the partition table when reading it from and writing it to +the device. +@end table + +The following option is available for partition table initialization: +@table @code +@item B @var{bootSector} +Reads the template master boot record from file @var{bootSector}. +@end table + + +@node mrd, mren, mpartition, Commands +@section Mrd +@pindex mrd +@cindex Removing a directory +@cindex Erasing a directory +@cindex Deleting a directory +@cindex Directory removing +@cindex Subdirectory removing + +The @code{mrd} command is used to remove an MS-DOS subdirectory. Its +syntax is: + +@display +@code{mrd} [@code{-v}] @var{msdosdirectory} [ @var{msdosdirectories}@dots{} ] +@end display + +@code{Mrd} removes a directory from an MS-DOS file system. An error occurs +if the directory does not exist or is not empty. + +@node mren, mshortname, mrd, Commands +@section Mren +@pindex mren +@cindex Renaming files (mren) +@cindex Moving files (mren) + +The @code{mren} command is used to rename or move an existing MS-DOS +file or subdirectory. Its syntax is: + +@display +@code{mren} [@code{-voOsSrRA}] @var{sourcefile} @var{targetfile} +@end display + +@code{Mren} +renames an existing file on an MS-DOS file system. + +In verbose mode, @code{Mren} displays the new filename if the name +supplied is invalid. + +If the first syntax is used (only one source file), and if the target +name doesn't contain any slashes or colons, the file (or subdirectory) +is renamed in the same directory, instead of being moved to the current +@code{mcd} directory as would be the case with @code{mmove}. Unlike the +MS-DOS version of @code{REN}, @code{mren} can be used to rename +directories. + +@node mshortname, mshowfat, mren, Commands +@section Mshortname +@pindex mshortname + +The @code{mshortname} command is used to display the short name of a +file. Syntax: + +@display +@code{mshortname} @var{files} +@end display + +The shortname is displayed as it is stored in raw format on disk, +without any character set conversion. + +@node mshowfat, mtoolstest, mshortname, Commands +@section Mshowfat +@pindex mshowfat +@cindex Clusters of a file +@cindex Fat + +The @code{mshowfat} command is used to display the FAT entries for a +file. Syntax: + +@display +@code{mshowfat} [@code{-o} @var{offset}] @var{files} +@end display + +If no offset is given, a list of all clusters occupied by the file is +printed. If an offset is given, only the number of the cluster +containing that offset is printed. + +@node mtoolstest, mtype, mshowfat, Commands +@section Mtoolstest +@pindex mtoolstest +@cindex Testing configuration file for correctness +@cindex Checking configuration file +@cindex Verifying configuration file + +The @code{mtoolstest} command is used to tests the mtools configuration +files. To invoke it, just type @code{mtoolstest} without any arguments. +@code{Mtoolstest} reads the mtools configuration files, and prints the +cumulative configuration to @code{stdout}. The output can be used as a +configuration file itself (although you might want to remove redundant +clauses). You may use this program to convert old-style configuration +files into new style configuration files. + +@node mtype, mzip, mtoolstest, Commands +@section Mtype + +The @code{mtype} command is used to display contents of an MS-DOS +file. Its syntax is: + +@display +@code{mtype} [@code{-ts}] @var{msdosfile} [ @var{msdosfiles}@dots{} ] +@end display + +@code{Mtype} displays the specified MS-DOS file on the screen. + +In addition to the standard options, @code{Mtype} allows the following +command line options: + +@table @code +@item t +Text file viewing. @code{Mtype} translates incoming carriage +return/line feeds to line feeds. +@item s +@code{Mtype} strips the high bit from the data. +@end table + +The @code{mcd} command may be used to establish the device and the +current working directory (relative to MS-DOS), otherwise the default is +@code{A:/}. + +@code{Mtype} returns 0 on success, 1 on utter failure, or 2 on partial +failure. + +Unlike the MS-DOS version of @code{TYPE}, @code{mtype} allows multiple +arguments. + + +@node mzip, , mtype, Commands +@section Mzip +@cindex Zip disk (utilities) +@cindex Jaz disk (utilities) +@cindex Ejecting a Zip/Jaz disk +@cindex Write protecting a Zip/Jaz disk +@pindex mzip +@cindex ZipTools disk +@cindex Tools disk (Zip and Jaz drives) +@cindex APlaceForYourStuff +@cindex password protected Zip disks + +The @code{mzip} command is used to issue ZIP disk specific commands on +Linux, Solaris or HP-UX. Its syntax is: + +@display +@code{mzip} [@code{-epqrwx}] +@end display + +@code{Mzip} allows the following +command line options: + +@table @code +@item e +Ejects the disk. +@item f +Force eject even if the disk is mounted (must be given in addition to +@code{-e}). +@item r +Write protect the disk. +@item w +Remove write protection. +@item p +Password write protect. +@item x +Password protect +@item u +Temporarily unprotect the disk until it is ejected. The disk becomes +writable, and reverts back to its old state when ejected. +@item q +Queries the status +@end table + +To remove the password, set it to one of the password-less modes +@code{-r} or @code{-w}: mzip will then ask you for the password, and +unlock the disk. If you have forgotten the password, you can get rid of +it by low-level formatting the disk (using your SCSI adapter's BIOS +setup). + +The ZipTools disk shipped with the drive is also password protected. On +MS-DOS or on a Mac, this password is automatically removed once the +ZipTools have been installed. From various articles posted to Usenet, I +learned that the password for the tools disk is +@code{APlaceForYourStuff}@footnote{To see the articles, search for +@code{APlaceForYourStuff} using Google Groups}. Mzip knows about this +password, and tries it first, before prompting you for a password. Thus +@code{mzip -w z:} unlocks the tools disk@footnote{I didn't know about +this yet when I bought my own Zip drive. Thus I ended up reformatting +my tools disk, and hence I haven't had the opportunity to test the +password yet. If anybody still has their tools disk with the original +password, could you try it out? Thanks in advance}. The tools disk is +formatted in a special way so as to be usable both in a PC and in a Mac. +On a PC, the Mac file system appears as a hidden file named +@file{partishn.mac}. You may erase it to reclaim the 50 Megs of space +taken up by the Mac file system. + + +@subsection Bugs + +This command is a big kludge. A proper implementation would take a +rework of significant parts of mtools, but unfortunately I don't have +the time for this right now. The main downside of this implementation is +that it is inefficient on some architectures (several successive calls +to mtools, which defeats mtools' caching). + +@node Compiling mtools, Porting mtools, Commands, Top +@chapter Architecture specific compilation flags +@cindex XDF disks (compile time configuration) +@cindex Solaris (compile time configuration of vold) +@cindex Vold (compile time configuration) +@cindex Compile time configuration + +To compile mtools, first invoke @code{./configure} before +@code{make}. In addition to the standard @code{autoconfigure} flags, +there are two architecture specific flags available. + +@table @code +@item ./configure --enable-xdf +@itemx ./configure --disable-xdf +Enables support for XDF disks. This is on by default. @xref{XDF}, +for details. +@item ./configure --enable-vold +@itemx ./configure --disable-vold +Enables support for vold on Solaris. When used in conjunction with vold, +mtools should use different device nodes than for direct access. + +@item ./configure --enable-new-vold +@itemx ./configure --disable-new-vold +Enables new support for vold on Solaris. This is supposed to work more +smoothly than the old support. + +@item ./configure --enable-floppyd +@itemx ./configure --disable-floppyd +Enables support for floppyd. By default, floppyd support is enabled as +long as the necessary X includes and libraries are available. +@end table + +@node Porting mtools, Command Index, Compiling mtools, Top +@chapter Porting mtools to architectures which are not supported yet +@cindex Porting +@cindex Compiled-in defaults + + This chapter is only interesting for those who want to port mtools to +an architecture which is not yet supported. For most common systems, +default drives are already defined. If you want to add default drives +for a still unsupported system, run configuration.guess, to see which +identification autoconf uses for that system. This identification is +of the form cpu-vendor-os (for example sparc-sun-sunos). The cpu and +the OS parts are passed to the compiler as preprocessor flags. + The OS part is passed to the compiler in three forms. +@enumerate +@item +The complete OS name, with dots replaced by underscores. SCO3.2v2 would +yield sco3_2v2 +@item +The base OS name. SCO3.2v2 would yield Sco +@item +The base OS name plus its major version. SCO3.2v2 would yield Sco3 +@end enumerate + + All three versions are passed, if they are different. + + To define the devices, use the entries for the systems that are already +present as templates. In general, they have the following form: + +@example +#if (defined (my_cpu) && defined(my_os)) +#define predefined_devices +struct device devices[] = @{ + @{ "/dev/first_drive", 'drive_letter', drive_description@}, + @dots{} + @{ "/dev/last_drive", 'drive_letter', drive_description@} +@} +#define INIT_NOOP +#endif +@end example + + "/dev/first_drive" is the name of the device or image file +representing the drive. Drive_letter is a letter ranging from a to z +giving access to the drive. Drive_description describes the type of the +drive: +@table @code +@item ED312 +extra density (2.88M) 3 1/2 disk +@item HD312 +high density 3 1/2 disk +@item DD312 +double density 3 1/2 disk +@item HD514 +high density 5 1/4 disk +@item DD514 +double density 5 1/4 disk +@item DDsmall +8 sector double density 5 1/4 disk +@item SS514 +single sided double density 5 1/4 disk +@item SSsmall +single sided 8 sector double density 5 1/4 disk +@item GENFD +generic floppy drive (12 bit FAT) +@item GENHD +generic hard disk (16 bit FAT) +@item GEN +generic device (all parameters match) +@item ZIPJAZ(flags) +generic ZIP drive using normal access. This uses partition 4. +@code{Flags} are any special flags to be passed to open. +@item RZIPJAZ(flags) +generic ZIP drive using raw SCSI access. This uses partition 4. +@code{Flags} are any special flags to be passed to open. +@item REMOTE +the remote drive used for floppyd. Unlike the other items, this macro +also includes the file name ($DISPLAY) and the drive letter (X) +@end table + + Entries may be described in more detail: +@example + fat_bits,open_flags,cylinders,heads,sectors,DEF_ARG +@end example + or, if you need to describe an offset (file system doesn't start at +beginning of file system) +@example + fat_bits, open_flags, cylinders, heads, sectors, offset, DEF_ARG0 +@end example + +@table @code +@item fat_bits +is either 12, 16 or 0. 0 means that the device accepts both types of +FAT. +@item open_flags +may include flags such as O_NDELAY, or O_RDONLY, which might be +necessary to open the device. 0 means no special flags are needed. +@item cylinders,heads,sectors +describe the geometry of the disk. If cylinders is 0, the heads and sectors +parameters are ignored, and the drive accepts any geometry. +@item offset +is used if the DOS file system doesn't begin at the start of the device +or image file. This is mostly useful for Atari Ram disks (which contain +their device driver at the beginning of the file) or for DOS emulator +images (which may represent a partitioned device. +@end table + + Definition of defaults in the devices file should only be done if these +same devices are found on a large number of hosts of this type. In that +case, could you also let me know about your new definitions, so that I +can include them into the next release. For purely local file, I +recommend that you use the @code{@value{SYSCONFDIR}mtools.conf} and +@code{~/.mtoolsrc} configuration files. + + However, the devices files also allows to supply geometry setting +routines. These are necessary if you want to access high capacity +disks. + + Two routines should be supplied: + +@enumerate +@item +Reading the current parameters +@example +static inline int get_parameters(int fd, struct generic_floppy_struct *floppy) +@end example + + This probes the current configured geometry, and return it in +the structure generic_floppy_struct (which must also be declared). + Fd is an open file descriptor for the device, and buf is an already +filled in stat structure, which may be useful. + This routine should return 1 if the probing fails, and 0 otherwise. + +@item +Setting new parameters +@example +static inline int set_parameters(int fd, struct generic_floppy_struct *floppy) + struct stat *buf) +@end example + This configures the geometry contained in floppy on the file descriptor +fd. Buf is the result of a stat call (already filled in). This should +return 1 if the new geometry cannot be configured, and 0 otherwise. +@end enumerate + + A certain number of preprocessor macros should also be supplied: + +@table @code +@item TRACKS(floppy) +refers to the track field in the floppy structure +@item HEADS(floppy) +refers to the heads field in the floppy structure +@item SECTORS(floppy) +refers to the sectors per track field in the floppy structure +@item SECTORS_PER_DISK(floppy) +refers to the sectors per disk field in the floppy structure (if +applicable, otherwise leave undefined) + +@item BLOCK_MAJOR +major number of the floppy device, when viewed as a block device + +@item CHAR_MAJOR +major number of the floppy device, when viewed as a character device +(a.k.a. "raw" device, used for fsck) (leave this undefined, if your OS +doesn't have raw devices) +@end table + + For the truly high capacity formats (XDF, 2m, etc), there is no clean +and documented interface yet. + +@comment MANskip 1 + +@node Command Index, Variable Index, Porting mtools, Top +@unnumbered Command Index +@printindex pg + +@node Variable Index, Concept Index, Command Index, Top +@unnumbered Variable index +@printindex vr + +@node Concept Index, , Variable Index, Top +@unnumbered Concept index +@printindex cp + +@comment MANend-skip 1 +@comment MANend-skip 5 +@bye |