1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename mtools.info
5 @settitle Mtools @value{VERSION}
7 @comment %**end of header
12 This manual is for Mtools (version @value{VERSION}, @value{UPDATED}),
13 which is a collection of tools to allow Unix systems to manipulate
16 Copyright @copyright{} 2007, 2009 Free Software Foundation, Inc.
17 Copyright @copyright{} 1996-2005,2007-2009 Alain Knaff.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
24 Texts. A copy of the license is included in the section entitled
25 ``GNU Free Documentation License''.
31 mtools - utilities to access DOS disks in Unix.
40 * Mtools: (mtools). Mtools: utilities to access DOS disks in Unix.
47 @c The following two commands start the copyright page.
49 @vskip 0pt plus 1filll
53 @c Output the table contents at the beginning
57 @node Top, Location, (dir), (dir)
60 This is mtools' documentation.
65 @unnumbered Introduction
66 Mtools is a collection of tools to allow Unix systems to manipulate
67 MS-DOS files: read, write, and move around files on an MS-DOS
68 filesystem (typically a floppy disk). Where reasonable, each program
69 attempts to emulate the MS-DOS equivalent command. However,
70 unnecessary restrictions and oddities of DOS are not emulated. For
71 instance, it is possible to move subdirectories from one subdirectory
74 Mtools is sufficient to give access to MS-DOS filesystems. For
75 instance, commands such as @code{mdir a:} work on the @code{a:} floppy
76 without any preliminary mounting or initialization (assuming the default
77 @file{/etc/mtools.conf} works on your machine). With mtools, one can
78 change floppies too without unmounting and mounting.
83 * Location:: Where to find mtools and early bug fixes
84 * Common features:: Common features of all mtools commands
85 * Configuration:: How to configure mtools for your environment
86 * Commands:: The available mtools commands
87 * Compiling mtools:: Architecture specific compilation flags
88 * Porting mtools:: Porting mtools to architectures which are not
91 * Command Index:: Command Index
92 * Variable Index:: Variable Index
93 * Concept Index:: Concept Index
96 @node Location, Common features, Top, Top
97 @chapter Where to get mtools
104 Mtools can be found at the following places (and their mirrors):
106 http://ftp.gnu.org/gnu/mtools/mtools-@value{VERSION}.tar.gz
107 http://mtools.linux.lu/mtools-@value{VERSION}.tar.gz
108 ftp://www.tux.org/pub/knaff/mtools/mtools-@value{VERSION}.tar.gz
109 ftp://ibiblio.unc.edu/pub/Linux/utils/disk-management/mtools-@value{VERSION}.tar.gz
112 Before reporting a bug, make sure that it has not yet been fixed in the
113 Alpha patches which can be found at:
115 http://ftp.gnu.org/gnu/mtools/
116 http://mtools.linux.lu/
117 ftp://www.tux.org/pub/knaff/mtools
120 These patches are named
121 @code{mtools-}@var{version}@code{-}@var{ddmm}@code{.taz}, where version
122 stands for the base version, @var{dd} for the day and @var{mm} for the
123 month. Due to a lack of space, I usually leave only the most recent
126 There is an mtools mailing list at mtools @@ tux.org . Please
127 send all bug reports to this list. You may subscribe to the list by
128 sending a message with 'subscribe mtools @@ tux.org' in its
129 body to majordomo @@ tux.org . (N.B. Please remove the spaces
130 around the "@@" both times. I left them there in order to fool
131 spambots.) Announcements of new mtools versions will also be sent to
132 the list, in addition to the linux announce newsgroups. The mailing
133 list is archived at http://lists.gnu.org/pipermail/info-mtools/
136 @node Common features, Configuration, Location, Top
137 @chapter Common features of all mtools commands
140 * arguments:: What the command line parameters of mtools
142 * drive letters:: Which drives are defined by default
143 * directory:: Current working directory
144 * long names:: VFAT-style long filenames
145 * name clashes:: Name clash handling, and associated command
147 * case sensitivity:: Case sensitivity
148 * high capacity formats:: How to fit more data on your floppies
149 * exit codes:: Exit codes
150 * bugs:: Happens to everybody
153 @node arguments, drive letters, Common features, Common features
154 @section Options and filenames
157 MS-DOS filenames are composed of a drive letter followed by a colon, a
158 subdirectory, and a filename. Only the filename part is mandatory, the
159 drive letter and the subdirectory are optional. Filenames without a
160 drive letter refer to Unix files. Subdirectory names can use either the
161 '@code{/}' or '@code{\}' separator. The use of the '@code{\}' separator
162 or wildcards requires the names to be enclosed in quotes to protect them
163 from the shell. However, wildcards in Unix filenames should not be
164 enclosed in quotes, because here we @strong{want} the shell to expand
167 The regular expression "pattern matching" routines follow the Unix-style
168 rules. For example, `@code{*}' matches all MS-DOS files in lieu of
169 `@code{*.*}'. The archive, hidden, read-only and system attribute bits
170 are ignored during pattern matching.
172 All options use the @code{-} (minus) as their first character, not
173 @code{/} as you'd expect in MS-DOS.
175 Most mtools commands allow multiple filename parameters, which
176 doesn't follow MS-DOS conventions, but which is more user-friendly.
178 Most mtools commands allow options that instruct them how to handle file
179 name clashes. @xref{name clashes}, for more details on these. All
180 commands accept the @code{-V} flags which prints the version, and most
181 accept the @code{-v} flag, which switches on verbose mode. In verbose
182 mode, these commands print out the name of the MS-DOS files upon which
183 they act, unless stated otherwise. @xref{Commands}, for a description of
184 the options which are specific to each command.
187 @node drive letters, directory, arguments, Common features
188 @section Drive letters
190 The meaning of the drive letters depends on the target architectures.
191 However, on most target architectures, drive A is the first floppy
192 drive, drive B is the second floppy drive (if available), drive J is a
193 Jaz drive (if available), and drive Z is a Zip drive (if available). On
194 those systems where the device name is derived from the SCSI id, the Jaz
195 drive is assumed to be at Scsi target 4, and the Zip at Scsi target 5
196 (factory default settings). On Linux, both drives are assumed to be the
197 second drive on the Scsi bus (/dev/sdb). The default settings can be
198 changes using a configuration file (@pxref{Configuration}).
200 The drive letter : (colon) has a special meaning. It is used to access
201 image files which are directly specified on the command line using the
206 mcopy -i my-image-file.bin ::file1 ::file2 .
209 This copies @code{file1} and @code{file2} from the image file
210 (@code{my-image-file.bin}) to the @code{/tmp} directory.
212 You can also supply an offset within the image file by including
213 @code{@@@@}@var{offset} into the file name.
217 mcopy -i my-image-file.bin@@@@1M ::file1 ::file2 .
220 This looks for the image at the offset of 1M in the file, rather than
223 @node directory, long names, drive letters, Common features
224 @section Current working directory
225 @pindex mcd (introduction)
227 @cindex Working directory
228 @cindex Current working directory
229 @cindex Default directory
231 The @code{mcd} command (@ref{mcd}) is used to establish the device and
232 the current working directory (relative to the MS-DOS filesystem),
233 otherwise the default is assumed to be @code{A:/}. However, unlike
234 MS-DOS, there is only one working directory for all drives, and not one
237 @node long names, name clashes, directory, Common features
238 @section VFAT-style long file names
239 @cindex Long file name
240 @cindex Windows 95-style file names
241 @cindex VFAT-style file names
242 @cindex Primary file name (long names)
243 @cindex Secondary file name (long names)
245 This version of mtools supports VFAT style long filenames. If a Unix
246 filename is too long to fit in a short DOS name, it is stored as a
247 VFAT long name, and a companion short name is generated. This short
248 name is what you see when you examine the disk with a pre-7.0 version
250 The following table shows some examples of short names:
253 Long name MS-DOS name Reason for the change
254 --------- ---------- ---------------------
255 thisisatest THISIS~1 filename too long
256 alain.knaff ALAIN~1.KNA extension too long
257 prn.txt PRN~1.TXT PRN is a device name
258 .abc ABC~1 null filename
259 hot+cold HOT_CO~1 illegal character
262 As you see, the following transformations happen to derive a short
266 Illegal characters are replaced by underscores. The illegal characters
267 are @code{;+=[]',\"*\\<>/?:|}.
269 Extra dots, which cannot be interpreted as a main name/extension
270 separator are removed
272 A @code{~}@var{n} number is generated,
274 The name is shortened so as to fit in the 8+3 limitation
277 The initial Unix-style file name (whether long or short) is also called
278 the @dfn{primary} name, and the derived short name is also called the
279 @dfn{secondary} name.
283 mcopy /etc/motd a:Reallylongname
285 Mtools creates a VFAT entry for Reallylongname, and uses REALLYLO as
286 a short name. Reallylongname is the primary name, and REALLYLO is the
289 mcopy /etc/motd a:motd
291 Motd fits into the DOS filename limits. Mtools doesn't need to
292 derivate another name. Motd is the primary name, and there is no
295 In a nutshell: The primary name is the long name, if one exists, or
296 the short name if there is no long name.
298 Although VFAT is much more flexible than FAT, there are still names
299 that are not acceptable, even in VFAT. There are still some illegal
300 characters left (@code{\"*\\<>/?:|}), and device names are still
304 Unix name Long name Reason for the change
305 --------- ---------- ---------------------
306 prn prn-1 PRN is a device name
307 ab:c ab_c-1 illegal character
310 As you see, the following transformations happen if a long name is
314 Illegal characters are replaces by underscores,
316 A @code{-}@var{n} number is generated,
319 @node name clashes, case sensitivity, long names, Common features
320 @section Name clashes
322 @cindex Duplicate file names
323 @cindex Overwriting files
324 @cindex Primary file name (name clashes)
325 @cindex Secondary file name (name clashes)
327 When writing a file to disk, its long name or short name may collide
328 with an already existing file or directory. This may happen for all
329 commands which create new directory entries, such as @code{mcopy},
330 @code{mmd}, @code{mren}, @code{mmove}. When a name clash happens, mtools
331 asks you what it should do. It offers several choices:
335 Overwrites the existing file. It is not possible to overwrite a
336 directory with a file.
338 Renames the newly created file. Mtools prompts for the new filename
340 Renames the newly created file. Mtools chooses a name by itself, without
343 Gives up on this file, and moves on to the next (if any)
346 To chose one of these actions, type its first letter at the prompt. If
347 you use a lower case letter, the action only applies for this file only,
348 if you use an upper case letter, the action applies to all files, and
349 you won't be prompted again.
351 You may also chose actions (for all files) on the command line, when
356 Overwrites primary names by default.
358 Overwrites secondary names by default.
360 Renames primary name by default.
362 Renames secondary name by default.
364 Autorenames primary name by default.
366 Autorenames secondary name by default.
368 Skip primary name by default.
370 Skip secondary name by default.
372 Ask user what to do with primary name.
374 Ask user what to do with secondary name.
377 Note that for command line switches lower/upper differentiates between
378 primary/secondary name whereas for interactive choices, lower/upper
379 differentiates between just-this-time/always.
381 The primary name is the name as displayed in Windows 95 or Windows NT:
382 i.e. the long name if it exists, and the short name otherwise. The
383 secondary name is the "hidden" name, i.e. the short name if a long name
386 By default, the user is prompted if the primary name clashes, and the
387 secondary name is autorenamed.
389 If a name clash occurs in a Unix directory, mtools only asks whether
390 to overwrite the file, or to skip it.
392 @node case sensitivity, high capacity formats, name clashes, Common features
393 @section Case sensitivity of the VFAT filesystem
394 @cindex Case sensitivity
396 The VFAT filesystem is able to remember the case of the
397 filenames. However, filenames which differ only in case are not allowed
398 to coexist in the same directory. For example if you store a file called
399 LongFileName on a VFAT filesystem, mdir shows this file as LongFileName,
400 and not as Longfilename. However, if you then try to add LongFilename to
401 the same directory, it is refused, because case is ignored for clash
404 The VFAT filesystem allows to store the case of a filename in the
405 attribute byte, if all letters of the filename are the same case, and if
406 all letters of the extension are the same case too. Mtools uses this
407 information when displaying the files, and also to generate the Unix
408 filename when mcopying to a Unix directory. This may have unexpected
409 results when applied to files written using an pre-7.0 version of DOS:
410 Indeed, the old style filenames map to all upper case. This is different
411 from the behavior of the old version of mtools which used to generate
412 lower case Unix filenames.
414 @node high capacity formats, exit codes, case sensitivity, Common features
415 @section high capacity formats
416 @cindex Special formats
417 @cindex High capacity formats
419 @cindex Weird formats
420 @cindex Formats, high capacity
421 @cindex Linux enhancements (High Capacity Formats)
423 Mtools supports a number of formats which allow to store more data on
424 disk as usual. Due to different operating system abilities, these
425 formats are not supported on all OS'es. Mtools recognizes these formats
426 transparently where supported.
428 In order to format these disks, you need to use an operating system
429 specific tool. For Linux, suitable floppy tools can be found in the
430 @code{fdutils} package at the following locations~:
432 @code{ftp://www.tux.org/pub/knaff/fdutils/}.
433 @code{ftp://ibiblio.unc.edu/pub/Linux/utils/disk-management/fdutils-*}
436 See the manpages included in that package for further detail: Use
437 @code{superformat} to format all formats except XDF, and use
438 @code{xdfcopy} to format XDF.
441 * more sectors:: Putting more sectors per track on the disk
442 * bigger sectors:: Use bigger sectors to save header space
443 * 2m:: Use a standard first track
444 * XDF:: OS/2's eXtended density format
447 @node more sectors, bigger sectors, high capacity formats, high capacity formats
448 @subsection More sectors
452 @cindex Windows 95 (DMF disks)
454 The oldest method of fitting more data on a disk is to use more sectors
455 and more cylinders. Although the standard format uses 80 cylinders and
456 18 sectors (on a 3 1/2 high density disk), it is possible to use up to
457 83 cylinders (on most drives) and up to 21 sectors. This method allows
458 to store up to 1743K on a 3 1/2 HD disk. However, 21 sector disks are
459 twice as slow as the standard 18 sector disks because the sectors are
460 packed so close together that we need to interleave them. This problem
461 doesn't exist for 20 sector formats.
463 These formats are supported by numerous DOS shareware utilities such as
464 @code{fdformat} and @code{vgacopy}. In his infinite hybris, Bill Gate$
465 believed that he invented this, and called it @samp{DMF disks}, or
466 @samp{Windows formatted disks}. But in reality, it has already existed
467 years before! Mtools supports these formats on Linux, on SunOs and on
470 @node bigger sectors, 2m, more sectors, high capacity formats
471 @subsection Bigger sectors
472 @cindex bigger sectors
473 By using bigger sectors it is possible to go beyond the capacity which
474 can be obtained by the standard 512-byte sectors. This is because of the
475 sector header. The sector header has the same size, regardless of how
476 many data bytes are in the sector. Thus, we save some space by using
477 @emph{fewer}, but bigger sectors. For example, 1 sector of 4K only takes
478 up header space once, whereas 8 sectors of 512 bytes have also 8
479 headers, for the same amount of useful data.
481 This method allows to store up to 1992K on a 3 1/2 HD disk.
483 Mtools supports these formats only on Linux.
485 @node 2m, XDF, bigger sectors, high capacity formats
489 The 2m format was originally invented by Ciriaco Garcia de Celis. It
490 also uses bigger sectors than usual in order to fit more data on the
491 disk. However, it uses the standard format (18 sectors of 512 bytes
492 each) on the first cylinder, in order to make these disks easyer to
493 handle by DOS. Indeed this method allows to have a standard sized
494 bootsector, which contains a description of how the rest of the disk
497 However, the drawback of this is that the first cylinder can hold less
498 data than the others. Unfortunately, DOS can only handle disks where
499 each track contains the same amount of data. Thus 2m hides the fact that
500 the first track contains less data by using a @dfn{shadow
501 FAT}. (Usually, DOS stores the FAT in two identical copies, for
502 additional safety. XDF stores only one copy, and it tells DOS that it
503 stores two. Thus the same that would be taken up by the second FAT copy
504 is saved.) This also means that your should @strong{never use a 2m disk
505 to store anything else than a DOS fs}.
507 Mtools supports these format only on Linux.
509 @node XDF, , 2m, high capacity formats
512 @cindex OS/2 (XDF disks)
514 XDF is a high capacity format used by OS/2. It can hold 1840 K per
515 disk. That's lower than the best 2m formats, but its main advantage is
516 that it is fast: 600 milliseconds per track. That's faster than the 21
517 sector format, and almost as fast as the standard 18 sector format. In
518 order to access these disks, make sure mtools has been compiled with XDF
519 support, and set the @code{use_xdf} variable for the drive in the
520 configuration file. @xref{Compiling mtools}, and @ref{misc variables},
521 for details on how to do this. Fast XDF access is only available for
522 Linux kernels which are more recent than 1.1.34.
524 Mtools supports this format only on Linux.
526 @strong{Caution / Attention distributors}: If mtools is compiled on a
527 Linux kernel more recent than 1.3.34, it won't run on an older
528 kernel. However, if it has been compiled on an older kernel, it still
529 runs on a newer kernel, except that XDF access is slower. It is
530 recommended that distribution authors only include mtools binaries
531 compiled on kernels older than 1.3.34 until 2.0 comes out. When 2.0 will
532 be out, mtools binaries compiled on newer kernels may (and should) be
533 distributed. Mtools binaries compiled on kernels older than 1.3.34 won't
534 run on any 2.1 kernel or later.
536 @node exit codes, bugs, high capacity formats, Common features
538 All the Mtools commands return 0 on success, 1 on utter failure, or 2
539 on partial failure. All the Mtools commands perform a few sanity
540 checks before going ahead, to make sure that the disk is indeed an
541 MS-DOS disk (as opposed to, say an ext2 or minix disk). These checks
542 may reject partially corrupted disks, which might otherwise still be
543 readable. To avoid these checks, set the MTOOLS_SKIP_CHECK
544 environmental variable or the corresponding configuration file variable
545 (@pxref{global variables})
546 @node bugs, , exit codes, Common features
548 An unfortunate side effect of not guessing the proper device (when
549 multiple disk capacities are supported) is an occasional error message
550 from the device driver. These can be safely ignored.
552 The fat checking code chokes on 1.72 Mb disks mformatted with pre-2.0.7
553 mtools. Set the environmental variable MTOOLS_FAT_COMPATIBILITY (or the
554 corresponding configuration file variable, @ref{global variables}) to
555 bypass the fat checking.
561 mtools.conf - mtools configuration files
563 @comment MANend-skip 5
566 This manpage describes the configuration files for mtools. They
571 @node Configuration, Commands, Common features, Top
574 @chapter How to configure mtools for your environment
576 @cindex Configuration files
579 This sections explains the syntax of the configurations files for
580 mtools. The configuration files
581 @comment MANend-skip 5
582 are called @file{/usr/local/etc/mtools.conf} and @file{~/.mtoolsrc}. If
583 the environmental variable @code{MTOOLSRC} is set, its contents is used
584 as the filename for a third configuration file. These configuration
585 files describe the following items:
588 @item Global configuration flags and variables
589 @item Per drive flags and variables
594 * config file location:: Where mtools looks for its configuration files
595 * general syntax:: The layout of the configuration files
596 * default values:: Why you don't need a config file in most cases
597 * global variables:: Variables that are independent of the drive
598 * per drive variables:: Variables that are specific to a given drive
599 * parsing order:: Location of configuration files and parsing order
600 * old style config:: Backwards compatibility
603 @node config file location, general syntax, Configuration, Configuration
604 @section Location of the configuration files
606 @cindex Configuration file name
607 @cindex Name of configuration files
608 @cindex Location of configuration files
610 @file{/usr/local/etc/mtools.conf} is the system-wide configuration file,
611 and @file{~/.mtoolsrc} is the user's private configuration file.
613 On some systems, the system-wide configuration file is called
614 @file{/etc/default/mtools.conf} instead.
617 @node general syntax, default values, config file location, Configuration
618 @subsection General configuration file syntax
619 @cindex Syntax of the configuration file
620 @cindex Configuration file syntax
622 The configuration files is made up of sections. Each section starts
623 with a keyword identifying the section followed by a colon.
624 Then follow variable assignments and flags. Variable assignments take
629 Flags are lone keywords without an equal sign and value following
630 them. A section either ends at the end of the file or where the next
633 Lines starting with a hash (@code{#}) are comments. Newline characters
634 are equivalent to whitespace (except where ending a comment). The
635 configuration file is case insensitive, except for item enclosed in
636 quotes (such as filenames).
638 @node default values, global variables, general syntax, Configuration
639 @section Default values
640 @cindex Default values
641 @cindex Default configuration
642 @cindex Configuration file
643 For most platforms, mtools contains reasonable compiled-in defaults for
644 physical floppy drives. Thus, you usually don't need to bother with the
645 configuration file, if all you want to do with mtools is to access your
646 floppy drives. On the other hand, the configuration file is needed if
647 you also want to use mtools to access your hard disk partitions and
650 @node global variables, per drive variables, default values, Configuration
651 @section Global variables
652 @cindex Global configuration variables
653 @cindex Drive independent configuration variables
654 @cindex Environmental variables
655 @vindex MTOOLS_SKIP_CHECK
656 @vindex MTOOLS_FAT_COMPATIBILITY
657 @vindex MTOOLS_LOWER_CASE
658 @vindex MTOOLS_NO_VFAT
661 Global flags may be set to 1 or to 0.
663 The following global flags are recognized:
666 @item MTOOLS_SKIP_CHECK
667 If this is set to 1, mtools skips most of its sanity checks. This is
668 needed to read some Atari disks which have been made with the earlier
669 ROMs, and which would not be recognized otherwise.
670 @item MTOOLS_FAT_COMPATIBILITY
671 If this is set to 1, mtools skips the fat size checks. Some disks have
672 a bigger FAT than they really need to. These are rejected if this
674 @item MTOOLS_LOWER_CASE
675 If this is set to 1, mtools displays all-upper-case short filenames as
676 lowercase. This has been done to allow a behavior which is consistent
677 with older versions of mtools which didn't know about the case bits.
679 If this is set to 1, mtools won't generate VFAT entries for filenames
680 which are mixed-case, but otherwise legal dos filenames. This is useful
681 when working with DOS versions which can't grok VFAT longnames, such as
683 @item MTOOLS_DOTTED_DIR
684 In a wide directory, prints the short name with a dot instead of spaces
685 separating the basename and the extension.
686 @item MTOOLS_NAME_NUMERIC_TAIL
687 If this is set to one (default), generate numeric tails for all long
688 names (~1). If set to zero, only generate numeric tails if otherwise a
689 clash would have happened.
690 @item MTOOLS_TWENTY_FOUR_HOUR_CLOCK
691 If 1, uses the European notation for times (twenty four hour clock),
692 else uses the UK/US notation (am/pm)
696 Inserting the following line into your configuration file instructs
697 mtools to skip the sanity checks:
702 Global variables may also be set via the environment:
704 export MTOOLS_SKIP_CHECK=1
707 Global string variables may be set to any value:
709 @item MTOOLS_DATE_STRING
710 The format used for printing dates of files. By default, is dd-mm-yyyy.
713 @node per drive variables, parsing order, global variables, Configuration
714 @section Per drive flags and variables
715 @cindex Drive description
716 @cindex Drive configuration
719 * general information:: What a drive description looks like
720 * location information:: Where is the drive data physically stored
721 * geometry description:: Describes the physical characteristics of
723 * open flags:: Flags passed to the open system call when the
725 * misc variables:: Variables which don't fit in either category
726 * misc flags:: Switch variables, which can be enabled or disabled
727 * multiple descriptions:: How to supply several descriptions for a
728 drive, to be tried one after the other.
731 @node general information, location information, per drive variables, per drive variables
732 @subsection General information
733 @cindex Drive description, example
734 @cindex Drive configuration, example
737 Per drive flags and values may be described in a drive section. A
738 drive section starts with
739 @code{drive} "@var{driveletter}" :
741 Then follow variable-value pairs and flags.
743 This is a sample drive description:
746 file="/dev/fd0" use_xdf=1
749 @node location information, geometry description, general information, per drive variables
750 @subsection Location information
753 For each drive, you need to describe where its data is physically
754 stored (imag file, physical device, partition, offset).
759 @cindex Name of device node
760 @cindex File name of device node
762 The name of the file or device holding the disk image. This is
763 mandatory. The file name should be enclosed in quotes.
766 @cindex Dosemu hard disk image
767 @cindex Zip disks (partitions)
768 @cindex Jaz disks (partitions)
769 @cindex Syquest disks
770 @cindex Magneto-optical disks
771 @cindex OS/2 (layout of removable media)
772 @cindex Windows NT (layout of removable media)
773 @cindex Removable media
774 @cindex Partitioned image file
775 Tells mtools to treat the drive as a partitioned device, and to use the
776 given partition. Only primary partitions are accessible using this
777 method, and they are numbered from 1 to 4. For logical partitions, use
778 the more general @code{offset} variable. The @code{partition} variable
779 is intended for removable media such as Syquests, ZIP drives, and
780 magneto-optical disks. Although traditional DOS sees Syquests and
781 magneto-optical disks as @samp{giant floppy disks} which are
782 unpartitioned, OS/2 and Windows NT treat them like hard disks,
783 i.e. partioned devices. The @code{partition} flag is also useful DOSEMU
784 hdimages. It is not recommended for hard disks for which direct access
785 to partitions is available through mounting.
789 @cindex Atari Ram disk
790 Describes where in the file the MS-DOS filesystem starts. This is useful
791 for logical partitions in DOSEMU hdimages, and for ATARI ram disks. By
792 default, this is zero, meaning that the filesystem starts right at the
793 beginning of the device or file.
796 @node geometry description, open flags, location information, per drive variables
797 @subsection Disk Geometry Configuration
798 @cindex Disk Geometry
799 @cindex Configuration of disk geometry
800 @cindex Description of disk geometry
801 @cindex Format of disk
802 @cindex High density disk
803 @cindex Low density disk
804 @pindex mformat (geometry used for)
806 Geometry information describes the physical characteristics about the
807 disk. Its has three purposes:
811 The geometry information is written into the boot sector of the newly
812 made disk. However, you may also describe the geometry information on
813 the command line. @xref{mformat}, for details.
815 On some Unices there are device nodes which only support one physical
816 geometry. For instance, you might need a different node to access a disk
817 as high density or as low density. The geometry is compared to the
818 actual geometry stored on the boot sector to make sure that this device
819 node is able to correctly read the disk. If the geometry doesn't match,
820 this drive entry fails, and the next drive entry bearing the same drive
821 letter is tried. @xref{multiple descriptions}, for more details on
822 supplying several descriptions for one drive letter.
824 If no geometry information is supplied in the configuration file, all
825 disks are accepted. On Linux (and on Sparc) there exist device nodes
826 with configurable geometry (@file{/dev/fd0}, @file{/dev/fd1} etc),
827 and thus filtering is not needed (and ignored) for disk drives. (Mtools
828 still does do filtering on plain files (disk images) in Linux: this is
829 mainly intended for test purposes, as I don't have access to a Unix
830 which would actually need filtering).
832 If you do not need filtering, but want still a default geometry for
833 mformatting, you may switch off filtering using the @code{mformat_only}
836 If you want filtering, you should supply the @code{filter} flag. If you
837 supply a geometry, you must supply one of both flags.
839 @item initial geometry
840 On devices that support it (usually floppy devices), the geometry
841 information is also used to set the initial geometry. This initial
842 geometry is applied while reading the boot sector, which contains the
843 real geometry. If no geometry information is supplied in the
844 configuration file, or if the @code{mformat_only} flag is supplied, no
845 initial configuration is done.
847 On Linux, initial geometry is not really needed, as the configurable
848 devices are able to auto-detect the disk type accurately enough (for
849 most common formats) to read the boot sector.
852 Wrong geometry information may lead to very bizarre errors. That's why I
853 strongly recommend that you add the @code{mformat_only} flag to your
854 drive description, unless you really need filtering or initial geometry.
856 The following geometry related variables are available:
863 The number of cylinders. (@code{cylinders} is the preferred form,
864 @code{tracks} is considered obsolete)
867 The number of heads (sides).
870 The number of sectors per track.
873 Example: the following drive section describes a 1.44M drive:
879 cylinders=80 heads=2 sectors=18
883 The following shorthand geometry descriptions are available:
887 high density 3 1/2 disk. Equivalent to:
888 @code{fat_bits=12 cylinders=80 heads=2 sectors=18}
890 high density 5 1/4 disk. Equivalent to:
891 @code{fat_bits=12 cylinders=80 heads=2 sectors=15}
893 double density 3 1/2 disk. Equivalent to:
894 @code{fat_bits=12 cylinders=80 heads=2 sectors=9}
896 double density 5 1/4 disk. Equivalent to:
897 @code{fat_bits=12 cylinders=40 heads=2 sectors=9}
900 The shorthand format descriptions may be amended. For example,
901 @code{360k sectors=8}
902 describes a 320k disk and is equivalent to:
903 @code{fat_bits=12 cylinders=40 heads=2 sectors=8}
905 @node open flags, misc variables, geometry description, per drive variables
906 @subsection Open Flags
911 @cindex synchronous writing
912 @cindex exclusive access to a drive
914 Moreover, the following flags are available:
918 All i/o operations are done synchronously
920 The device or file is opened with the O_NDELAY flag. This is needed on
921 some non-Linux architectures.
923 The device or file is opened with the O_EXCL flag. On Linux, this
924 ensures exclusive access to the floppy drive. On most other
925 architectures, and for plain files it has no effect at all.
929 @node misc variables, misc flags, open flags, per drive variables
930 @subsection General Purpose Drive Variables
932 The following general purpose drive variables are available. Depending
933 to their type, these variables can be set to a string (precmd) or
934 an integer (all others)
939 The number of FAT bits. This may be 12 or 16. This is very rarely
940 needed, as it can almost always be deduced from information in the
941 boot sector. On the contrary, describing the number of fat bits may
942 actually be harmful if you get it wrong. You should only use it if
943 mtools gets the autodetected number of fat bits wrong, or if you want
944 to mformat a disk with a weird number of fat bits.
946 Describes the DOS codepage used for short filenames. This is a number
947 between 1 and 999. By default, codepage 850 is used. The reason for
948 this is because this codepage contains most of the characters that are
949 also available in ISO-Latin-1. You may also specify a global codepage
950 for all drives by using the global @code{default_codepage} parameter
951 (outside of any drive description). This parameters exists starting at
954 @cindex Solaris (volcheck)
955 @cindex Executing commands before opening the device
956 On some variants of Solaris, it is necessary to call 'volcheck -v'
957 before opening a floppy device, in order for the system to notice that
958 there is indeed a disk in the drive. @code{precmd="volcheck -v"} in the
959 drive clause establishes the desired behavior.
963 @cindex character devices
965 This parameter represents a default block size to be always used on this
966 device. All I/O is done with multiples of this block size,
967 independantly of the sector size registered in the filesystem's boot
968 sector. This is useful for character devices whose sector size is not
969 512, such as for example CD Rom drives on Solaris.
973 Only the @code{file} variable is mandatory. The other parameters may
974 be left out. In that case a default value or an autodetected value is
979 @node misc flags, multiple descriptions, misc variables, per drive variables
980 @subsection General Purpose Drive Flags
982 A flag can either be set to 1 (enabled) or 0 (disabled). If the value is
983 ommitted, it is enabled. For example, @code{scsi} is equivalent to
988 @cindex disable locking
989 @cindex locking (disabling it)
990 @cindex plain floppy: device xxx busy
991 Instruct mtools to not use locking on this drive. This is needed on
992 systems with buggy locking semantics. However, enabling this makes
993 operation less safe in cases where several users may access the same
994 drive at the same time.
997 @cindex setuid installation (needed for raw SCSI I/O)
998 @cindex Solaris (Raw access to SCSI devices such as Zip & Jaz)
999 @cindex SunOS (Raw access to SCSI devices such as Zip & Jaz)
1000 @cindex Zip disks (raw Scsi access)
1001 @cindex Jaz disks (raw Scsi access)
1002 @cindex Syquests (raw Scsi access)
1003 @cindex SCSI devices
1004 When set to 1, this option tells mtools to use raw SCSI I/O instead of
1005 the standard read/write calls to access the device. Currently, this is
1006 supported on HP/UX, Solaris and SunOs. This is needed because on some
1007 architectures, such as SunOs or Solaris, PC media can't be accessed
1008 using the @code{read} and @code{write} syscalls, because the OS expects
1009 them to contain a Sun specific "disk label".
1011 As raw Scsi access always uses the whole device, you need to specify the
1012 "partition" flag in addition
1014 On some architectures, such as Solaris, mtools needs root privileges to
1015 be able to use the @code{scsi} option. Thus mtools should be installed
1016 set uid root on Solaris if you want to access Zip/Jaz drives. Thus, if
1017 the @code{scsi} flag is given, @code{privileged} is automatically
1018 implied, unless explicitly disabled by @code{privileged=0}
1020 Mtools uses its root privileges to open the device, and to issue the
1021 actual SCSI I/O calls. Moreover, root privileges are only used for
1022 drives described in a system-wide configuration file such as
1023 @file{/usr/local/etc/mtools.conf}, and not for those described in
1024 @file{~/.mtoolsrc} or @file{$MTOOLSRC}.
1027 @cindex setuid installation
1028 @cindex setgid installation
1029 When set to 1, this instructs mtools to use its set-uid and set-gid
1030 privileges for opening the given drive. This option is only valid for
1031 drives described in the system-wide configuration files (such as
1032 @file{/usr/local/etc/mtools.conf}, not @file{~/.mtoolsrc} or
1033 @file{$MTOOLSRC}). Obviously, this option is also a no op if mtools is
1034 not installed setuid or setgid. This option is implied by 'scsi=1', but
1035 again only for drives defined in system-wide configuration files.
1036 Privileged may also be set explicitely to 0, in order to tell mtools not
1037 to use its privileges for a given drive even if @code{scsi=1} is set.
1039 Mtools only needs to be installed setuid if you use the
1040 @code{privileged} or @code{scsi} drive variables. If you do not use
1041 these options, mtools works perfectly well even when not installed
1045 @cindex Solaris (vold)
1046 @cindex Vold (mediamgr)
1048 Instructs mtools to interpret the device name as a vold identifier
1049 rather than as a filename. The vold identifier is translated into a
1050 real filename using the @code{media_findname()} and
1051 @code{media_oldaliases()} functions of the @code{volmgt} library. This
1052 flag is only available if you configured mtools with the
1053 @code{--enable-new-vold} option before compilation.
1059 Consider the media as a word-swapped Atari disk.
1062 @cindex XDF disks (how to configure)
1064 If this is set to a non-zero value, mtools also tries to access this
1065 disk as an XDF disk. XDF is a high capacity format used by OS/2. This
1066 is off by default. @xref{XDF}, for more details.
1068 @vindex mformat_only
1069 Tells mtools to use the geometry for this drive only for mformatting and
1074 Tells mtools to use the geometry for this drive both for mformatting and
1078 Tells mtools to connect to floppyd (@pxref{floppyd}).
1082 @node multiple descriptions, , misc flags, per drive variables
1083 @subsection Supplying multiple descriptions for a drive
1085 It is possible to supply multiple descriptions for a drive. In that
1086 case, the descriptions are tried in order until one is found that
1087 fits. Descriptions may fail for several reasons:
1091 because the geometry is not appropriate,
1093 because there is no disk in the drive,
1095 or because of other problems.
1098 Multiple definitions are useful when using physical devices which are
1099 only able to support one single disk geometry.
1102 drive a: file="/dev/fd0H1440" 1.44m
1103 drive a: file="/dev/fd0H720" 720k
1106 This instructs mtools to use /dev/fd0H1440 for 1.44m (high density)
1107 disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this
1108 feature is not really needed, as the /dev/fd0 device is able to handle
1111 You may also use multiple drive descriptions to access both of your
1112 physical drives through one drive letter:
1115 drive z: file="/dev/fd0"
1116 drive z: file="/dev/fd1"
1119 With this description, @code{mdir z:} accesses your first physical
1120 drive if it contains a disk. If the first drive doesn't contain a disk,
1121 mtools checks the second drive.
1123 When using multiple configuration files, drive descriptions in the files
1124 parsed last override descriptions for the same drive in earlier
1125 files. In order to avoid this, use the @code{drive+} or @code{+drive}
1126 keywords instead of @code{drive}. The first adds a description to the
1127 end of the list (i.e. it will be tried last), and the first adds it to
1128 the start of the list.
1130 @node parsing order, old style config, per drive variables, Configuration
1131 @section Location of configuration files and parsing order
1132 @cindex Parsing order
1133 @cindex Configuration file parsing order
1134 @cindex Configuration file name (parsing order)
1135 @cindex Name of configuration files (parsing order)
1136 @cindex Location of configuration files (parsing order)
1138 The configuration files are parsed in the following order:
1141 compiled-in defaults
1143 @file{/usr/local/etc/mtools.conf}
1146 This is for backwards compatibility only, and is only parsed if
1152 @file{$MTOOLSRC} (file pointed by the @code{MTOOLSRC} environmental
1156 Options described in the later files override those described in the
1157 earlier files. Drives defined in earlier files persist if they are not
1158 overridden in the later files. For instance, drives A and B may be
1159 defined in @file{/usr/local/etc/mtools.conf} and drives C and D may be
1160 defined in @file{~/.mtoolsrc} However, if @file{~/.mtoolsrc} also
1161 defines drive A, this new description would override the description of
1162 drive A in @file{/usr/local/etc/mtools.conf} instead of adding to it. If
1163 you want to add a new description to a drive already described in an
1164 earlier file, you need to use either the @code{+drive} or @code{drive+}
1167 @node old style config, , parsing order, Configuration
1168 @section Backwards compatibility with old configuration file syntax
1169 @cindex Backwards compatibility
1170 @cindex Old configuration file syntax
1171 @cindex Configuration file, old syntax
1173 The syntax described herein is new for version @code{mtools-3.0}. The
1174 old line-oriented syntax is still supported. Each line beginning with a
1175 single letter is considered to be a drive description using the old
1176 syntax. Old style and new style drive sections may be mixed within the
1177 same configuration file, in order to make upgrading easier. Support for
1178 the old syntax will be phased out eventually, and in order to discourage
1179 its use, I purposefully omit its description here.
1183 @node Commands, Compiling mtools, Configuration, Top
1184 @chapter Command list
1185 @cindex Command list
1186 @cindex List of available commands
1188 This section describes the available mtools commands, and the command
1189 line parameters that each of them accepts. Options which are common to
1190 all mtools commands are not described here, @ref{arguments} for a
1191 description of those.
1194 * floppyd:: floppy daemon to run on your X server box
1195 * floppyd_installtest:: small utility to check for the presence of floppyd
1196 * mattrib:: change MS-DOS file attribute flags
1197 * mbadblocks:: tests a floppy disk, and marks the bad blocks in the FAT
1198 * mcat:: same as cat. Only usefull with floppyd.
1199 * mcd:: change MS-DOS directory
1200 * mclasserase:: erase memory card
1201 * mcopy:: copy MS-DOS files to/from Unix
1202 * mdel:: delete an MS-DOS file
1203 * mdeltree:: recursively delete an MS-DOS directory
1204 * mdir:: display an MS-DOS directory
1205 * mdu:: list space occupied by directory and its contents
1206 * mformat:: add an MS-DOS filesystem to a low-level formatted floppy disk
1207 * minfo:: get information about an MS-DOS filesystem.
1208 * mlabel:: make an MS-DOS volume label
1209 * mkmanifest:: makes a list of short name equivalents
1210 * mmd:: make an MS-DOS subdirectory
1211 * mmount:: mount an MS-DOS disk
1212 * mpartition:: create an MS-DOS as a partition
1213 * mrd:: remove an MS-DOS subdirectory
1214 * mmove:: move or rename an MS-DOS file or subdirectory
1215 * mren:: rename an existing MS-DOS file
1216 * mshowfat:: shows the FAT map of a file
1217 * mtoolstest:: tests and displays the configuration
1218 * mtype:: display contents of an MS-DOS file
1219 * mzip:: zip disk specific commands
1222 @node floppyd, floppyd_installtest, Commands, Commands
1226 @cindex remote floppy access
1228 @code{Floppyd} is used as a server to grant access to the floppy drive
1229 to clients running on a remote machine, just as an X server grants
1230 access to the display to remote clients. It has the following syntax:
1232 @code{floppyd} [@code{-d}] [@code{-l}] [@code{-s} @var{port}] [@code{-r}
1233 @var{user}] [@code{-b} @var{ipaddr}] [@code{-x} @var{display}] @var{devicenames}
1236 @code{floppyd} is always associated with an X server. It runs on the
1237 same machine as its X server, and listens on port 5703 and above.
1239 @subsection Authentication
1241 @code{floppyd} authenticates remote clients using the @code{Xauthority}
1242 protocol. Xhost authentication is not supported. Each floppyd is
1243 associated with an X server. When a remote client attempts to connect
1244 to floppyd, it sends floppyd the X authority record corresponding to
1245 floppyd's X server. Floppyd in turn then tries to open up a connection
1246 to the X server in order to verify the authenticity of the xauth record.
1247 If the connection to the X server succeeds, the client is granted
1251 @strong{Caution}: In order to make authentication work correctly, the
1252 local host should @strong{not} be listed in the @code{xhost} list of
1254 Indeed, hosts listed in @code{xhost} do not need a correct
1255 @code{Xauthority} cookie to connect to the X server. As @code{floppyd}
1256 runs on the same host as the X server, all its probe connection would
1257 succeed even for clients who supplied a bad cookie. This means that
1258 your floppy drive would be open to the world, i.e. a huge security hole.
1259 If your X server does not allow you to remove @code{localhost:0} and
1260 @code{:0} from the @code{xhost} list, you can prevent floppyd from
1261 probing those display names with the @code{-l} option.
1263 @subsection Command line options
1267 Daemon mode. Floppyd runs its own server loop. Do not supply this if
1268 you start floppyd from @code{inetd.conf}
1270 Port number for deamon mode. Default is 5703 + @var{displaynumber}.
1271 This flag implies daemon mode. For example, for display
1272 @code{hitchhiker:5}, the port would be 5708.
1273 @item b @var{ipaddr}
1274 Bind address (for multihomed hosts). This flag implies daemon mode
1276 Run the server under as the given user
1277 @item x @var{display}
1278 X display to use for authentication. By default, this is taken from the
1279 @code{DISPLAY} variable. If neither the @code{x} attribute is present
1280 nor @code{DISPLAY} is set, floppyd uses @code{:0.0}.
1283 @var{devicenames} is a list of device nodes to be opened. Default
1284 is @code{/dev/fd0}. Multiple devices are only supported on mtools
1285 versions newer than 3.9.11.
1288 @subsection Connecting to floppyd
1290 In order to use floppyd, add the flag @code{remote} to the device
1291 description in your @file{~/.mtoolsrc} file. If the flag @code{remote}
1292 is given, the @code{file} parameter of the device description is taken
1293 to be a remote address. It's format is the following:
1294 @var{hostname}@code{:}@var{displaynumber}[@code{/}[@var{baseport}][@code{/}@var{drive}]]. When
1295 using this entry, mtools connects to port
1296 @var{baseport}+@var{displaynumber} at @var{hostname}. By default
1297 @var{baseport} is 5703. The drive parameter is to distinguish among
1298 multiple drives associated with a single display (only mtools versions
1299 more recent than 3.9.11)
1301 @subsection Examples:
1303 The following starts a floppy daemon giving access to @file{/dev/fd0},
1304 listening on the default port 5703, tied to the default X servers:
1310 Each of the following starts a floppy daemon giving access to
1311 @file{/dev/fd1}, tied to the :1 local X servers, and listening on port
1312 5704. We assume that the local host is named @code{hitchhiker}.
1316 floppyd -d -x :1 -p 5704 /dev/fd0
1319 If you want to start floppyd by @code{inetd} instead of running it as a
1320 daemon, insert the following lines into @file{/etc/services}:
1323 floppyd-0 5703/tcp # floppy daemon for X server :0
1324 floppyd-1 5704/tcp # floppy daemon for X server :1
1327 And insert the following into @file{/etc/inetd.conf} (assuming that you
1328 have defined a user named floppy in your @file{/etc/passwd}):
1332 floppyd-0 stream tcp wait floppy /usr/sbin/floppyd floppyd /dev/fd0
1333 floppyd-1 stream tcp wait floppy /usr/sbin/floppyd floppyd -x :1 /dev/fd0
1336 Note that you need to supply the X display names for the second
1337 floppyd. This is because the port is opened by inetd.conf, and hence
1338 floppyd cannot know its number to interfere the display number.
1341 On the client side, insert the following into your @file{~/.mtoolsrc}
1342 to define a drive letter accessing floppy drive in your X terminal:
1344 drive x: file="$DISPLAY" remote
1347 If your X terminal has more than one drive, you may access the
1348 additional drives as follows:
1350 drive y: file="$DISPLAY//1" remote
1351 drive z: file="$DISPLAY//2" remote
1354 @node floppyd_installtest, mattrib, floppyd, Commands
1355 @section Floppyd_installtest
1356 @pindex floppyd_installtest
1358 @cindex remote floppy access
1360 @code{Floppyd_installtest} is used to check for the presence of a running
1361 floppyd daemon. This is usefull, if you have a small frontend script to
1362 mtools, which decides whether to use floppyd or not.
1364 @code{floppyd_installtest} [@code{-f}] Connect-String
1366 If the @code{-f} option is specified, @code{floppyd_installtest} does a
1367 full X-Cookie authentication and complains if this does not work.
1369 The connect-String has the format described in the floppyd-section:
1370 @var{hostname}@code{:}@var{displaynumber}[@code{/}@var{baseport}]
1372 @node mattrib, mbadblocks, floppyd_installtest, Commands
1375 @cindex Changing file attributes
1376 @cindex Hidden files
1377 @cindex Read-only files (changing the attribute)
1378 @cindex System files
1381 @code{Mattrib} is used to change MS-DOS file attribute flags. It has the
1384 @code{mattrib} [@code{-a|+a}] [@code{-h|+h}] [@code{-r|+r}]
1385 [@code{-s|+s}] [@code{-/}] [@code{-p}] [@code{-X}] @var{msdosfile} [ @var{msdosfiles} @dots{} ]
1387 @code{Mattrib} adds attribute flags to an MS-DOS file (with the
1388 `@code{+}' operator) or remove attribute flags (with the `@code{-}'
1391 @code{Mattrib} supports the following attribute bits:
1395 Archive bit. Used by some backup programs to indicate a new file.
1397 Read-only bit. Used to indicate a read-only file. Files with this bit
1398 set cannot be erased by @code{DEL} nor modified.
1400 System bit. Used by MS-DOS to indicate a operating system file.
1402 Hidden bit. Used to make files hidden from @code{DIR}.
1405 @code{Mattrib} supports the following command line flags:
1408 Recursive. Recursively list the attributes of the files in the subdirectories.
1410 Concise. Prints the attributes whithout any whitespace padding. If
1411 neither the "/" option is given, nor the @var{msdosfile} contains a
1412 wildcard, and there is only one Msdos file parameter on the command
1413 line, only the attribute is printed, and not the filename. This option
1414 is convenient for scripts
1416 Replay mode. Outputs a series of mformat commands that will reproduce
1417 the current situation, starting from a situation as left by untarring
1418 the Dos filesystem. Commands are only output for attribute settings
1419 that differ from the default (archive bit set for files, unset for
1420 directories). This option is intended to be used in addition to
1421 tar. The @code{readonly} attribute is not taken into account, as tar can
1422 set that one itself.
1425 @node mbadblocks, mcat, mattrib, Commands
1428 The @code{mbadblocks} command is used to scan an MS-DOS floppy and mark
1429 its unused bad blocks as bad. It uses the following syntax:
1431 @code{mbadblocks} @var{drive}@code{:}
1433 @cindex Marking blocks as bad
1437 @code{Mbadblocks} scans an MS-DOS floppy for bad blocks. All unused bad
1438 blocks are marked as such in the FAT. This is intended to be used right
1439 after @code{mformat}. It is not intended to salvage bad disks.
1441 @code{Mbadblocks} should (but doesn't yet :-( ) also try to salvage bad
1442 blocks which are in use by reading them repeatedly, and then mark them
1445 @node mcat, mcd, mbadblocks, Commands
1448 The @code{mcat} command is used to copy an entire disk image from or
1449 to the floppy device. It uses the following syntax:
1451 @code{mcat} [@code{-w}] @var{drive}@code{:}
1453 @cindex Copying an entire disk image
1457 @code{Mcat} performs the same task as the unix @code{cat} command. It
1458 is included into the mtools package, since @code{cat} cannot access
1459 remote floppy devices offered by the mtools floppy daemon.
1460 Now it is possible to create boot floppies remotely.
1462 The default operation is reading. The output is written to stdout.
1464 If the @code{-w} option is specified, mcat reads a disk-image from
1465 stdin and writes it to the given device.
1466 @strong{Use this carefully!} Because of the lowlevel nature of this
1467 command, it will happily destroy any data written before on the
1468 disk without warning!
1470 @node mcd, mclasserase, mcat, Commands
1473 @cindex Directory (changing)
1474 @cindex Working directory
1475 @cindex Current working directory (changing the)
1476 @cindex Default directory (changing the)
1479 The @code{mcd} command is used to change the mtools working directory
1480 on the MS-DOS disk. It uses the following syntax:
1483 @code{mcd} [@var{msdosdirectory}]
1486 Without arguments, @code{mcd} reports the current device and working
1487 directory. Otherwise, @code{mcd} changes the current device and current
1488 working directory relative to an MS-DOS filesystem.
1490 The environmental variable @code{MCWD} may be used to locate the file
1491 where the device and current working directory information is stored.
1492 The default is @file{$HOME/.mcwd}. Information in this file is ignored
1493 if the file is more than 6 hours old.
1495 @code{Mcd} returns 0 on success or 1 on failure.
1497 Unlike MS-DOS versions of @code{CD}, @code{mcd} can be used to change to
1498 another device. It may be wise to remove old @file{.mcwd} files at logout.
1500 @node mclasserase, mcopy, mcd, Commands
1501 @section Mclasserase
1504 @cindex Physically erase
1506 The @code{mclasserase} command is used to wipe memory cards by
1507 overwriting it three times: first with @code{0xff}, then with
1508 @code{0x00}, then with @code{0xff} again. The command uses the following
1512 @code{mclasserase} [@code{-d}] @var{msdosdrive}
1515 Dos drive is optional, if none is specified, use @code{A:}. If more than
1516 one drive are specified, all but the last are ignored.
1518 @code{Mclasserase} accepts the following command line options:
1522 Stop after each erase cycle, for testing purposes
1528 @code{Mclasserase} returns 0 on success or -1 on failure.
1531 @node mcopy, mdel, mclasserase, Commands
1534 @cindex Reading MS-DOS files
1535 @cindex Writing MS-DOS files
1536 @cindex Copying MS-DOS files
1537 @cindex Concatenating MS-DOS files
1539 @cindex CR/LF conversions
1541 The @code{mcopy} command is used to copy MS-DOS files to and from
1542 Unix. It uses the following syntax:
1545 @code{mcopy} [@code{-bspanvmQT}] [@code{-D} @var{clash_option}] @var{sourcefile} @var{targetfile}
1546 @code{mcopy} [@code{-bspanvmQT}] [@code{-D} @var{clash_option}] @var{sourcefile} [ @var{sourcefiles}@dots{} ] @var{targetdirectory}
1547 @code{mcopy} [@code{-tnvm}] @var{MSDOSsourcefile}
1552 @code{Mcopy} copies the specified file to the named file, or copies
1553 multiple files to the named directory. The source and target can be
1554 either MS-DOS or Unix files.
1556 The use of a drive letter designation on the MS-DOS files, 'a:' for
1557 example, determines the direction of the transfer. A missing drive
1558 designation implies a Unix file whose path starts in the current
1559 directory. If a source drive letter is specified with no attached file
1560 name (e.g. @code{mcopy a: .}), all files are copied from that drive.
1562 If only a single, MS-DOS source parameter is provided (e.g. "mcopy
1563 a:foo.exe"), an implied destination of the current directory
1564 (`@code{.}') is assumed.
1566 A filename of `@code{-}' means standard input or standard output, depending
1567 on its position on the command line.
1569 @code{Mcopy} accepts the following command line options:
1573 Text file transfer. Mcopy translates incoming carriage return/line
1574 feeds to line feeds when copying from Dos to Unix, and vice-versa when
1575 copying from Unix to Dos.
1577 Batch mode. Optimized for huge recursive copies, but less secure if a
1578 crash happens during the copy.
1580 Recursive copy. Also copies directories and their contents
1582 Preserves the attributes of the copied files
1584 When mcopying multiple files, quits as soon as one copy fails (for
1585 example due to lacking storage space on the target disk)
1587 Text (Ascii) file transfer. @code{Mcopy} translates incoming carriage
1588 return/line feeds to line feeds.
1590 Text (Ascii) file transfer with charset conversion. Differs from
1591 @code{-a} in the @code{Mcopy} also translates incoming PC-8 characters
1592 to ISO-8859-1 equivalents as far as possible. When reading DOS files,
1593 untranslatable characters are replaced by '@code{#}'; when writing DOS files,
1594 untranslatable characters are replaced by '@code{.}'.
1596 No confirmation when overwriting Unix files. @code{Mcopy} doesn't warn
1597 the user when overwriting an existing Unix file. If the target file already exists,
1598 and the @code{-n} option is not in effect, @code{mcopy} asks whether to
1599 overwrite the file or to rename the new file (@ref{name clashes}) for
1600 details). In order to switch off confirmation for DOS files, use @code{-o}.
1602 Preserve the file modification time.
1604 Verbose. Displays the name of each file as it is copied.
1608 Unlike MS-DOS, the '+' operator (append) from MS-DOS is not
1609 supported. However, you may use @code{mtype} to produce the same effect:
1611 mtype a:file1 a:file2 a:file3 >unixfile
1612 mtype a:file1 a:file2 a:file3 | mcopy - a:msdosfile
1615 @node mdel, mdeltree, mcopy, Commands
1618 @cindex removing MS-DOS files
1619 @cindex erasing MS-DOS files
1620 @cindex deleting MS-DOS files
1622 The @code{mdel} command is used to delete an MS-DOS file. Its syntax
1626 @code{mdel} [@code{-v}] @var{msdosfile} [ @var{msdosfiles} @dots{} ]
1629 @code{Mdel} deletes files on an MS-DOS filesystem.
1631 @code{Mdel} asks for verification prior to removing a read-only file.
1633 @node mdeltree, mdir, mdel, Commands
1636 @cindex removing an MS-DOS directory recursively
1637 @cindex erasing an MS-DOS directory recursively
1638 @cindex deleting an MS-DOS directory recursively
1639 @cindex recursively removing an MS-DOS directory
1641 The @code{mdeltree} command is used to delete an MS-DOS file. Its syntax
1645 @code{mdeltree} [@code{-v}] @var{msdosdirectory} [@var{msdosdirectories}@dots{}]
1648 @code{Mdeltree} removes a directory and all the files and subdirectories
1649 it contains from an MS-DOS filesystem. An error occurs if the directory
1650 to be removed does not exist.
1652 @node mdir, mdu, mdeltree, Commands
1655 @cindex Read-only files (listing them)
1656 @cindex Listing a directory
1657 @cindex Directory listing
1659 The @code{mdir} command is used to display an MS-DOS directory. Its
1662 @code{mdir} [@code{-/}] [@code{-f}] [@code{-w}] [@code{-a}] [@code{-b}] @var{msdosfile} [ @var{msdosfiles}@dots{}]
1665 displays the contents of MS-DOS directories, or the entries for some
1668 @code{Mdir} supports the following command line options:
1672 Recursive output, just like Dos' @code{-s} option
1674 Wide output. With this option, @code{mdir} prints the filenames across
1675 the page without displaying the file size or creation date.
1677 Also list hidden files.
1679 Fast. Do not try to find out free space. On larger disks, finding out
1680 the amount of free space takes up some non trivial amount of time, as
1681 the whole FAT must be read in and scanned. The @code{-f} flag bypasses
1682 this step. This flag is not needed on FAT32 filesystems, which store
1683 the size explicitely.
1685 Concise listing. Lists each directory name or filename, one per line
1686 (including the filename extension). This switch displays no heading
1687 information and no summary. Only a newline separated list of pathnames
1691 An error occurs if a component of the path is not a directory.
1693 @node mdu, mformat, mdir, Commands
1696 @cindex Space occupied by directories and files
1698 @cindex Listing space occupied by directories and files
1699 @cindex Occupation of space by directories and files
1701 @code{Mdu} is used to list the space occupied by a directory, its
1702 subdirectories and its files. It is similar to the @code{du} command on
1703 Unix. The unit used are clusters. Use the minfo command to find out
1706 @code{mdu} [@code{-a}] [ @var{msdosfiles} @dots{} ]
1711 All files. List also the space occupied for individual files.
1713 Only list the total space, don't give details for each subdirectory.
1718 @node mformat, mkmanifest, mdu, Commands
1721 @cindex Initializing disks
1722 @cindex Formatting disks
1723 @cindex Filesystem creation
1725 The @code{mformat} command is used to add an MS-DOS filesystem to a
1726 low-level formatted diskette. Its syntax is:
1729 @code{mformat} [@code{-t} @var{cylinders}] [@code{-h} @var{heads}] [@code{-s} @var{sectors}]
1730 [@code{-f} @var{size}] [@code{-1}] [@code{-4}] [@code{-8}]
1731 [@code{-v} @var{volume_label}]
1732 [@code{-F}] [@code{-S} @var{sizecode}] [@code{-X}]
1733 [@code{-2} @var{sectors_on_track_0}] [@code{-3}]
1734 [@code{-0} @var{rate_on_track_0}] [@code{-A} @var{rate_on_other_tracks}]
1735 [@code{-M} @var{software_sector_size}]
1736 [@code{-N} @var{serial_number}] [@code{-a}]
1737 [@code{-C}] [@code{-H} @var{hidden_sectors}] [@code{-I} @var{fsVersion}]
1738 [@code{-r} @var{root_sectors}] [@code{-L} @var{fat_len}]
1739 [@code{-B} @var{boot_sector}] [@code{-k}]
1740 [@code{-m} @var{media_descriptor}]
1744 @code{Mformat} adds a minimal MS-DOS filesystem (boot sector, FAT, and
1745 root directory) to a diskette that has already been formatted by a Unix
1749 The following options are supported: (The S, 2, 1 and M options may not
1750 exist if this copy of mtools has been compiled without the USE_2M
1753 The following options are the same as for Dos's format command:
1755 @comment xMANoptions
1759 Specifies the volume label. A volume label identifies the disk and can
1760 be a maximum of 11 characters. If you omit the -v switch, mlabel will
1761 assign no label to the disk.
1763 Specifies the size of the DOS filesystem to format. Only a certain
1764 number of predefined sizes are supported by this flag; for others use
1765 the -h/-t/-s flags. The following sizes are supported:
1768 160K, single-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD)
1770 160K, single-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD)
1772 320K, double-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD)
1774 360K, double-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD)
1776 720K, double-sided, 9 sectors per track, 80 cylinders (for 3 1/2 DD)
1778 1200K, double-sided, 15 sectors per track, 80 cylinders (for 5 1/4 HD)
1780 1440K, double-sided, 18 sectors per track, 80 cylinders (for 3 1/2 HD)
1782 2880K, double-sided, 36 sectors per track, 80 cylinders (for 3 1/2 ED)
1786 Specifies the number of tracks on the disk.
1788 The number of heads (sides).
1790 Specifies the number of sectors per track. If the 2m option is given,
1791 number of 512-byte sector equivalents on generic tracks (i.e. not head 0
1792 track 0). If the 2m option is not given, number of physical sectors per
1793 track (which may be bigger than 512 bytes).
1796 Formats a single side (equivalent to -h 1)
1799 Formats a 360K double-sided disk (equivalent to -f 360). When used
1800 together with -the 1 switch, this switch formats a 180K disk
1803 Formats a disk with 8 sectors per track.
1807 MSDOS format's @code{q}, @code{u} and @code{b} options are not
1808 supported, and @code{s} has a different meaning.
1810 The following options are specific to mtools:
1815 Format the partition as FAT32.
1818 The sizecode. The size of the sector is 2 ^ (sizecode + 7).
1820 formats the disk as an XDF disk. @xref{XDF}, for more details. The disk
1821 has first to be low-level formatted using the xdfcopy utility included
1822 in the fdutils package. XDF disks are used for instance for OS/2 install
1825 2m format. The parameter to this option describes the number of
1826 sectors on track 0, head 0. This option is recommended for sectors
1829 don't use a 2m format, even if the current geometry of the disk is a 2m
1832 Data transfer rate on track 0
1834 Data transfer rate on tracks other than 0
1836 software sector size. This parameter describes the sector size in bytes used
1837 by the MS-DOS filesystem. By default it is the physical sector size.
1839 Uses the requested serial number, instead of generating one
1842 If this option is given, an Atari style serial number is generated.
1843 Ataris store their serial number in the OEM label.
1845 creates the disk image file to install the MS-DOS filesystem on
1846 it. Obviously, this is useless on physical devices such as floppies
1847 and hard disk partitions, but is interesting for image files.
1849 number of hidden sectors. This parameter is useful for formatting hard
1850 disk partition, which are not aligned on track boundaries (i.e. first
1851 head of first track doesn't belong to the partition, but contains a
1852 partition table). In that case the number of hidden sectors is in
1853 general the number of sectors per cylinder. This is untested.
1855 Sets the fsVersion id when formatting a FAT32 drive. In order to find
1856 this out, run minfo on an existing FAT32 drive, and mail me about it, so
1857 I can include the correct value in future versions of mtools.
1859 Sets the size of a cluster (in sectors). If this cluster size would
1860 generate a FAT that too big for its number of bits, mtools automatically
1861 increases the cluster size, until the FAT is small enough.
1863 Sets the number of FAT copies. Default is 2. This setting can also be
1864 specified using the @code{MTOOLS_NFATS} environment variable.
1866 Sets the size of the root directory (in sectors). Only applicable to 12
1867 and 16 bit FATs. This setting can also be specified using the
1868 @code{MTOOLS_DIR_LEN} environment variable.
1870 Sets the length of the FAT.
1872 Use the bootsector stored in the given file or device, instead of using
1873 its own. Only the geometry fields are updated to match the target disks
1876 Keep the existing boot sector as much as possible. Only the geometry
1877 fields and other similar filesystem data are updated to match the target
1881 Use a non-standard media descriptor byte for this disk. The media
1882 descriptor is stored at position 21 of the boot sector, and as first
1883 byte in each FAT copy. Using this option may confuse DOS or older mtools
1884 version, and may make the disk unreadable. Only use if you know what you
1889 To format a diskette at a density other than the default, you must supply
1890 (at least) those command line parameters that are different from the
1893 @code{Mformat} returns 0 on success or 1 on failure.
1895 It doesn't record bad block information to the Fat, use
1896 @code{mbadblocks} for that.
1898 @node mkmanifest, minfo, mformat, Commands
1901 @cindex packing list
1903 The @code{mkmanifest} command is used to create a shell script (packing
1904 list) to restore Unix filenames. Its syntax is:
1906 @code{mkmanifest} [ @var{files} ]
1908 @code{Mkmanifest} creates a shell script that aids in the restoration of
1909 Unix filenames that got clobbered by the MS-DOS filename restrictions.
1910 MS-DOS filenames are restricted to 8 character names, 3 character
1911 extensions, upper case only, no device names, and no illegal characters.
1914 The mkmanifest program is compatible with the methods used in
1915 @code{pcomm, arc,} and @code{mtools} to change perfectly good Unix
1916 filenames to fit the MS-DOS restrictions. This command is only useful if
1917 the target system which will read the diskette cannot handle vfat long
1921 You want to copy the following Unix files to a MS-DOS diskette (using the
1922 @code{mcopy} command).
1934 converts the names to:
1947 mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital >manifest
1949 would produce the following:
1951 mv very_lon very_long_name
1952 mv 2xmany.dot 2.many.dots
1953 mv illegalx illegal:
1958 Notice that "good.c" did not require any conversion, so it did not
1959 appear in the output.
1961 Suppose I've copied these files from the diskette to another Unix
1962 system, and I now want the files back to their original names. If the
1963 file "manifest" (the output captured above) was sent along with those
1964 files, it could be used to convert the filenames.
1968 The short names generated by @code{mkmanifest} follow the old convention
1969 (from mtools-2.0.7) and not the one from Windows 95 and mtools-3.0.
1972 @node minfo, mlabel, mkmanifest, Commands
1975 @cindex mformat parameters
1976 @cindex getting parameters of a Dos fs
1978 The @code{minfo} command prints the parameters of a Dos filesystem, such
1979 as number of sectors, heads and cylinders. It also prints an mformat
1980 command line which can be used to create a similar Dos filesystem on
1981 another media. However, this doesn't work with 2m or Xdf media, and
1982 with Dos 1.0 filesystems
1984 @code{minfo} @var{drive}:
1987 Mlabel supports the following option:
1990 Prints a hexdump of the bootsector, in addition to the other information
1994 @node mlabel, mmd, minfo, Commands
1997 @cindex Labeling a disk
2000 The @code{mlabel} command adds a volume label to a disk. Its syntax is:
2002 @code{mlabel} [@code{-vcsn}] [@code{-N} @var{serial}] @var{drive}:[@var{new_label}]
2005 @code{Mlabel} displays the current volume label, if present. If
2006 @var{new_label} is not given, and if neither the @code{c} nor the
2007 @code{s} options are set, it prompts the user for a new volume label.
2008 To delete an existing volume label, press return at the prompt.
2010 Reasonable care is taken to create a valid MS-DOS volume label. If an
2011 invalid label is specified, @code{mlabel} changes the label (and
2012 displays the new label if the verbose mode is set). @code{Mlabel}
2013 returns 0 on success or 1 on failure.
2015 Mlabel supports the following options:
2018 Clears an existing label, without prompting the user
2020 Shows the existing label, without prompting the user.
2022 Assigns a new (random) serial number to the disk
2023 @item N @var{serial}
2024 Sets the supplied serial number. The serial number should be supplied as
2025 an 8 digit hexadecimal number, without spaces
2029 @node mmd, mmount, mlabel, Commands
2032 @cindex Making a directory
2033 @cindex Creating a directory
2034 @cindex Directory creation
2035 @cindex Subdirectory creation
2037 The @code{mmd} command is used to make an MS-DOS subdirectory. Its
2040 @code{mmd} [@code{-D} @var{clash_option}] @var{msdosdirectory} [
2041 @var{msdosdirectories}@dots{} ]
2043 @code{Mmd} makes a new directory on an MS-DOS filesystem. An error occurs
2044 if the directory already exists.
2047 @node mmount, mmove, mmd, Commands
2050 @cindex Linux enhancements (mmount)
2051 @cindex Mounting a disk
2052 @cindex High capacity formats, mounting
2054 The @code{mmount} command is used to mount an MS-DOS disk. It is only
2055 available on Linux, as it is only useful if the OS kernel allows to
2056 configure the disk geometry. Its syntax is:
2058 @code{mmount} @var{msdosdrive} [@var{mountargs}]
2061 reads the boot sector of an MS-DOS disk, configures the drive geometry,
2062 and finally mounts it passing
2063 @code{mountargs} to @code{mount. }
2064 If no mount arguments are specified, the name of the device is
2065 used. If the disk is write protected, it is automatically mounted read
2069 @node mmove, mpartition, mmount, Commands
2072 @cindex Moving files (mmove)
2073 @cindex Renaming files (mmove)
2075 The @code{mmove} command is used to moves or renames an existing MS-DOS
2076 file or subdirectory.
2078 @code{mmove} [@code{-v}] [@code{-D} @var{clash_option}] @var{sourcefile} @var{targetfile}
2079 @code{mmove} [@code{-v}] [@code{-D} @var{clash_option}] @var{sourcefile} [ @var{sourcefiles}@dots{} ] @var{targetdirectory}
2081 @code{Mmove} moves or renames an existing MS-DOS file or
2082 subdirectory. Unlike the MS-DOS version of @code{MOVE}, @code{mmove} is
2083 able to move subdirectories. Files or directories can only be moved
2084 within one filesystem. Data cannot be moved from Dos to Unix or
2085 vice-versa. If you omit the drive letter from the target file or
2086 directory, the same letter as for the source is assumed. If you omit
2087 the drive letter from all parameters, drive a: is assumed by default.
2089 @node mpartition, mrd, mmove, Commands
2092 @cindex partitions (creating)
2093 @cindex Zip disks (partitioning them)
2094 @cindex Jaz disks (partitioning them)
2096 The @code{mpartition} command is used to create MS-DOS filesystems as
2097 partitions. This is intended to be used on non-Linux systems,
2098 i.e. systems where fdisk and easy access to Scsi devices are not
2099 available. This command only works on drives whose partition variable
2103 @code{mpartition} @code{-p} @var{drive}
2104 @code{mpartition} @code{-r} @var{drive}
2105 @code{mpartition} @code{-I} [@code{-B} @var{bootSector}] @var{drive}
2106 @code{mpartition} @code{-a} @var{drive}
2107 @code{mpartition} @code{-d} @var{drive}
2108 @code{mpartition} @code{-c} [@code{-s} @var{sectors}] [@code{-h} @var{heads}]
2109 [@code{-t} @var{cylinders}] [@code{-v} [@code{-T} @var{type}] [@code{-b}
2110 @var{begin}] [@code{-l} length] [@code{-f}]
2114 Mpartition supports the following operations:
2118 Prints a command line to recreate the partition for the drive. Nothing
2119 is printed if the partition for the drive is not defined, or an
2120 inconsistency has been detected. If verbose (@code{-v}) is also set,
2121 prints the current partition table.
2123 Removes the partition described by @var{drive}.
2125 Initializes the partition table, and removes all partitions.
2127 Creates the partition described by @var{drive}.
2129 "Activates" the partition, i.e. makes it bootable. Only one partition
2130 can be bootable at a time.
2132 "Desactivates" the partition, i.e. makes it unbootable.
2135 If no operation is given, the current settings are printed.
2137 For partition creations, the following options are available:
2139 @item s @var{sectors}
2140 The number of sectors per track of the partition (which is also the
2141 number of sectors per track for the whole drive).
2143 The number of heads of the partition (which is also the number of heads
2144 for the whole drive). By default, the geometry information (number of
2145 sectors and heads) is figured out from neighbouring partition table
2146 entries, or guessed from the size.
2147 @item t @var{cylinders}
2148 The number of cylinders of the partition (not the number of cylinders of
2151 The starting offset of the partition, expressed in sectors. If begin is
2152 not given, mpartition lets the partition begin at the start of the disk
2153 (partition number 1), or immediately after the end of the previous
2155 @item l @var{length}
2156 The size (length) of the partition, expressed in sectors. If end is not
2157 given, mpartition figures out the size from the number of sectors, heads
2158 and cylinders. If these are not given either, it gives the partition
2159 the biggest possible size, considering disk size and start of the next
2163 The following option is available for all operation which modify the
2167 Usually, before writing back any changes to the partition, mpartition
2168 performs certain consistenct checks, such as checking for overlaps and
2169 proper alignment of the partitions. If any of these checks fails, the
2170 partition table is not changes. The @code{-f} allows you to override
2174 The following options are available for all operations:
2177 Together with @code{-p} prints the partition table as it is now (no
2178 change operation), or as it is after it is modified.
2180 If the verbosity flag is given twice, mpartition will print out a
2181 hexdump of the partition table when reading it from and writing it to
2185 The following option is available for partition table initialization:
2187 @item B @var{bootSector}
2188 Reads the template master boot record from file @var{bootSector}.
2192 @node mrd, mren, mpartition, Commands
2195 @cindex Removing a directory
2196 @cindex Erasing a directory
2197 @cindex Deleting a directory
2198 @cindex Directory removing
2199 @cindex Subdirectory removing
2201 The @code{mrd} command is used to remove an MS-DOS subdirectory. Its
2205 @code{mrd} [@code{-v}] @var{msdosdirectory} [ @var{msdosdirectories}@dots{} ]
2208 @code{Mrd} removes a directory from an MS-DOS filesystem. An error occurs
2209 if the directory does not exist or is not empty.
2211 @node mren, mshowfat, mrd, Commands
2214 @cindex Renaming files (mren)
2215 @cindex Moving files (mren)
2217 The @code{mren} command is used to rename or move an existing MS-DOS
2218 file or subdirectory. Its syntax is:
2221 @code{mren} [@code{-voOsSrRA}] @var{sourcefile} @var{targetfile}
2225 renames an existing file on an MS-DOS filesystem.
2227 In verbose mode, @code{Mren} displays the new filename if the name
2228 supplied is invalid.
2230 If the first syntax is used (only one sourcefile), and if the target
2231 name doesn't contain any slashes or colons, the file (or subdirectory)
2232 is renamed in the same directory, instead of being moved to the current
2233 @code{mcd} directory as would be the case with @code{mmove}. Unlike the
2234 MS-DOS version of @code{REN}, @code{mren} can be used to rename
2237 @node mshowfat, mtoolstest, mren, Commands
2240 @cindex Clusters of a file
2243 The @code{mshowfat} command is used to display the FAT entries for a
2247 @code{$ mshowfat files}
2250 @node mtoolstest, mtype, mshowfat, Commands
2253 @cindex Testing configuration file for correctness
2254 @cindex Checking configuration file
2255 @cindex Verifying configuration file
2257 The @code{mtoolstest} command is used to tests the mtools configuration
2258 files. To invoke it, just type @code{mtoolstest} without any arguments.
2259 @code{Mtoolstest} reads the mtools configuration files, and prints the
2260 cumulative configuration to @code{stdout}. The output can be used as a
2261 configuration file itself (although you might want to remove redundant
2262 clauses). You may use this program to convert old-style configuration
2263 files into new style configuration files.
2265 @node mtype, mzip, mtoolstest, Commands
2268 The @code{mtype} command is used to display contents of an MS-DOS
2269 file. Its syntax is:
2272 @code{mtype} [@code{-ts}] @var{msdosfile} [ @var{msdosfiles}@dots{} ]
2275 @code{Mtype} displays the specified MS-DOS file on the screen.
2277 In addition to the standard options, @code{Mtype} allows the following
2278 command line options:
2282 Text file viewing. @code{Mtype} translates incoming carriage
2283 return/line feeds to line feeds.
2285 @code{Mtype} strips the high bit from the data.
2288 The @code{mcd} command may be used to establish the device and the
2289 current working directory (relative to MS-DOS), otherwise the default is
2292 @code{Mtype} returns 0 on success, 1 on utter failure, or 2 on partial
2295 Unlike the MS-DOS version of @code{TYPE}, @code{mtype} allows multiple
2299 @node mzip, , mtype, Commands
2301 @cindex Zip disk (utilities)
2302 @cindex Jaz disk (utilities)
2303 @cindex Ejecting a Zip/Jaz disk
2304 @cindex Write protecting a Zip/Jaz disk
2306 @cindex ZipTools disk
2307 @cindex Tools disk (Zip and Jaz drives)
2308 @cindex APlaceForYourStuff
2309 @cindex password protected Zip disks
2311 The @code{mzip} command is used to issue ZIP disk specific commands on
2312 Linux, Solaris or HPUX. Its syntax is:
2315 @code{mzip} [@code{-epqrwx}]
2318 @code{Mzip} allows the following
2319 command line options:
2325 Force eject even if the disk is mounted (must be given in addition to
2328 Write protect the disk.
2330 Remove write protection.
2332 Password write protect.
2336 Temporarily unprotect the disk until it is ejected. The disk becomes
2337 writable, and reverts back to its old state when ejected.
2342 To remove the password, set it to one of the passwordless modes
2343 @code{-r} or @code{-w}: mzip will then ask you for the password, and
2344 unlock the disk. If you have forgotten the password, you can get rid of
2345 it by low-level formatting the disk (using your SCSI adaptor's BIOS
2348 The ZipTools disk shipped with the drive is also password protected. On
2349 Dos or on a Mac, this password is automatically removed once the
2350 ZipTools have been installed. From various articles posted to Usenet, I
2351 learned that the password for the tools disk is
2352 @code{APlaceForYourStuff}@footnote{To see the articles, search for
2353 @code{APlaceForYourStuff} using Dejanews}. Mzip knows about this
2354 password, and tries it first, before prompting you for a password. Thus
2355 @code{mzip -w z:} unlocks the tools disk@footnote{I didn't know about
2356 this yet when I bought my own Zip drive. Thus I ended up reformatting
2357 my tools disk, and hence I haven't had the opportunity to test the
2358 password yet. If anybody still has their tools disk with the original
2359 password, could you try it out? Thanks in advance}. The tools disk is
2360 formatted in a special way so as to be usable both in a PC and in a Mac.
2361 On a PC, the Mac filesystem appears as a hidden file named
2362 @file{partishn.mac}. You may erase it to reclaim the 50 Megs of space
2363 taken up by the Mac filesystem.
2368 This command is a big kludge. A proper implementation would take a
2369 rework of significant parts of mtools, but unfortunately I don't have
2370 the time for this right now. The main downside of this implementation is
2371 that it is inefficient on some architectures (several successive calls
2372 to mtools, which defeats mtools' caching).
2374 @node Compiling mtools, Porting mtools, Commands, Top
2375 @chapter Architecture specific compilation flags
2376 @cindex XDF disks (compile time configuration)
2377 @cindex Solaris (compile time configuration of vold)
2378 @cindex Vold (compile time configuration)
2379 @cindex Compile time configuration
2381 To compile mtools, first invoke @code{./configure} before
2382 @code{make}. In addition to the standard @code{autoconfigure} flags,
2383 there are two architecture specific flags available.
2386 @item ./configure --enable-xdf
2387 @itemx ./configure --disable-xdf
2388 Enables support for XDF disks. This is on by default. @xref{XDF},
2390 @item ./configure --enable-vold
2391 @itemx ./configure --disable-vold
2392 Enables support for vold on Solaris. When used in conjunction with vold,
2393 mtools should use different device nodes than for direct access.
2395 @item ./configure --enable-new-vold
2396 @itemx ./configure --disable-new-vold
2397 Enables new support for vold on Solaris. This is supposed to work more
2398 smoothly than the old support.
2400 @item ./configure --enable-floppyd
2401 @itemx ./configure --disable-floppyd
2402 Enables support for floppyd. By default, floppyd support is enabled as
2403 long as the necessary X includes and libraries are available.
2406 @node Porting mtools, Command Index, Compiling mtools, Top
2407 @chapter Porting mtools to architectures which are not supported yet
2409 @cindex Compiled-in defaults
2411 This chapter is only interesting for those who want to port mtools to
2412 an architecture which is not yet supported. For most common systems,
2413 default drives are already defined. If you want to add default drives
2414 for a still unsupported system, run config.guess, to see which
2415 identification autoconf uses for that system. This identification is
2416 of the form cpu-vendor-os (for example sparc-sun-sunos). The cpu and
2417 the os parts are passed to the compiler as preprocessor flags.
2418 The OS part is passed to the compiler in three forms.
2421 The complete os name, with dots replaced by underscores. sco3.2v2 would
2424 The base os name. Sco3.2v2 would yield Sco
2426 The base os name plus its major version. Sco3.2v2 would yield Sco3
2429 All three versions are passed, if they are different.
2431 To define the devices, use the entries for the systems that are already
2432 present as templates. In general, they have the following form:
2435 #if (defined (my_cpu) && defined(my_os))
2436 #define predefined_devices
2437 struct device devices[] = @{
2438 @{ "/dev/first_drive", 'drive_letter', drive_description@},
2440 @{ "/dev/last_drive", 'drive_letter', drive_description@}
2446 "/dev/first_drive" is the name of the device or image file
2447 representing the drive. Drive_letter is a letter ranging from a to z
2448 giving access to the drive. Drive_description describes the type of the
2452 extra density (2.88M) 3 1/2 disk
2454 high density 3 1/2 disk
2456 double density 3 1/2 disk
2458 high density 5 1/4 disk
2460 double density 5 1/4 disk
2462 8 sector double density 5 1/4 disk
2464 single sided double density 5 1/4 disk
2466 single sided 8 sector double density 5 1/4 disk
2468 generic floppy drive (12 bit FAT)
2470 generic hard disk (16 bit FAT)
2472 generic device (all parameters match)
2474 generic ZIP drive using normal access. This uses partition 4.
2475 @code{Flags} are any special flags to be passed to open.
2476 @item RZIPJAZ(flags)
2477 generic ZIP drive using raw SCSI access. This uses partition 4.
2478 @code{Flags} are any special flags to be passed to open.
2480 the remote drive used for floppyd. Unlike the other items, this macro
2481 also includes the file name ($DISPLAY) and the drive letter (X)
2484 Entries may be described in more detail:
2486 fat_bits,open_flags,cylinders,heads,sectors,DEF_ARG
2488 or, if you need to describe an offset (filesystem doesn't start at
2489 beginning of filesystem)
2491 fat_bits, open_flags, cylinders, heads, sectors, offset, DEF_ARG0
2496 is either 12, 16 or 0. 0 means that the device accepts both types of
2499 may include flags such as O_NDELAY, or O_RDONLY, which might be
2500 necessary to open the device. 0 means no special flags are needed.
2501 @item cylinders,heads,sectors
2502 describe the geometry of the disk. If cylinders is 0, the heads and sectors
2503 parameters are ignored, and the drive accepts any geometry.
2505 is used if the DOS filesystem doesn't begin at the start of the device
2506 or image file. This is mostly useful for Atari Ram disks (which contain
2507 their device driver at the beginning of the file) or for DOS emulator
2508 images (which may represent a partitioned device.
2511 Definition of defaults in the devices file should only be done if these
2512 same devices are found on a large number of hosts of this type. In that
2513 case, could you also let me know about your new definitions, so that I
2514 can include them into the next release. For purely local file, I
2515 recommend that you use the @code{/usr/local/etc/mtools.conf} and
2516 @code{~/.mtoolsrc} configuration files.
2518 However, the devices files also allows to supply geometry setting
2519 routines. These are necessary if you want to access high capacity
2522 Two routines should be supplied:
2526 Reading the current parameters
2528 static inline int get_parameters(int fd, struct generic_floppy_struct *floppy)
2531 This probes the current configured geometry, and return it in
2532 the structure generic_floppy_struct (which must also be declared).
2533 Fd is an open file descriptor for the device, and buf is an already
2534 filled in stat structure, which may be useful.
2535 This routine should return 1 if the probing fails, and 0 otherwise.
2538 Setting new parameters
2540 static inline int set_parameters(int fd, struct generic_floppy_struct *floppy)
2543 This configures the geometry contained in floppy on the file descriptor
2544 fd. Buf is the result of a stat call (already filled in). This should
2545 return 1 if the new geometry cannot be configured, and 0 otherwise.
2548 A certain number of preprocessor macros should also be supplied:
2551 @item TRACKS(floppy)
2552 refers to the track field in the floppy structure
2554 refers to the heads field in the floppy structure
2555 @item SECTORS(floppy)
2556 refers to the sectors per track field in the floppy structure
2557 @item SECTORS_PER_DISK(floppy)
2558 refers to the sectors per disk field in the floppy structure (if
2559 applicable, otherwise leave undefined)
2562 major number of the floppy device, when viewed as a block device
2565 major number of the floppy device, when viewed as a character device
2566 (a.k.a. "raw" device, used for fsck) (leave this undefined, if your OS
2567 doesn't have raw devices)
2570 For the truly high capacity formats (XDF, 2m, etc), there is no clean
2571 and documented interface yet.
2575 @node Command Index, Variable Index, Porting mtools, Top
2576 @unnumbered Command Index
2579 @node Variable Index, Concept Index, Command Index, Top
2580 @unnumbered Variable index
2583 @node Concept Index, , Variable Index, Top
2584 @unnumbered Concept index
2587 @comment MANend-skip 1
2588 @comment MANend-skip 5