1\input texinfo @c -*-texinfo-*- 2@comment %**start of header 3@setfilename mtools.info 4@include version.texi 5@settitle Mtools @value{VERSION} 6@syncodeindex pg cp 7@comment %**end of header 8 9@comment MANskip 5 10 11@copying 12This manual is for Mtools (version @value{VERSION}, @value{UPDATED}), 13which is a collection of tools to allow Unix systems to manipulate 14MS-DOS files. 15 16Copyright @copyright{} 2007, 2009 Free Software Foundation, Inc. 17Copyright @copyright{} 1996-2005,2007-2009 Alain Knaff. 18 19@quotation 20Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.3 or 22any later version published by the Free Software Foundation; with no 23Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 24Texts. A copy of the license is included in the section entitled 25``GNU Free Documentation License''. 26@end quotation 27@end copying 28 29@ignore 30@unnumbered Name 31mtools - utilities to access DOS disks in Unix. 32@end ignore 33 34@iftex 35@finalout 36@end iftex 37 38@dircategory DOS 39@direntry 40* Mtools: (mtools). Mtools: utilities to access DOS disks in Unix. 41@end direntry 42 43 44@titlepage 45@title Mtools 46 47@c The following two commands start the copyright page. 48@page 49@vskip 0pt plus 1filll 50@insertcopying 51@end titlepage 52 53@c Output the table contents at the beginning 54@contents 55 56@ifnottex 57@node Top, Location, (dir), (dir) 58@top Mtools doc 59 60This is mtools' documentation. 61@end ifnottex 62 63@comment MANstart 1 64 65@unnumbered Introduction 66Mtools is a collection of tools to allow Unix systems to manipulate 67MS-DOS files: read, write, and move around files on an MS-DOS 68filesystem (typically a floppy disk). Where reasonable, each program 69attempts to emulate the MS-DOS equivalent command. However, 70unnecessary restrictions and oddities of DOS are not emulated. For 71instance, it is possible to move subdirectories from one subdirectory 72to another. 73 74Mtools is sufficient to give access to MS-DOS filesystems. For 75instance, commands such as @code{mdir a:} work on the @code{a:} floppy 76without any preliminary mounting or initialization (assuming the default 77@file{/etc/mtools.conf} works on your machine). With mtools, one can 78change floppies too without unmounting and mounting. 79 80@insertcopying 81 82@menu 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 89 yet supported 90 91* Command Index:: Command Index 92* Variable Index:: Variable Index 93* Concept Index:: Concept Index 94@end menu 95 96@node Location, Common features, Top, Top 97@chapter Where to get mtools 98@cindex bugs 99@cindex ALPHA patches 100@cindex patches 101@cindex diffs 102@cindex mailing list 103 104Mtools can be found at the following places (and their mirrors): 105@example 106http://ftp.gnu.org/gnu/mtools/mtools-@value{VERSION}.tar.gz 107http://mtools.linux.lu/mtools-@value{VERSION}.tar.gz 108ftp://www.tux.org/pub/knaff/mtools/mtools-@value{VERSION}.tar.gz 109ftp://ibiblio.unc.edu/pub/Linux/utils/disk-management/mtools-@value{VERSION}.tar.gz 110@end example 111 112Before reporting a bug, make sure that it has not yet been fixed in the 113Alpha patches which can be found at: 114@example 115http://ftp.gnu.org/gnu/mtools/ 116http://mtools.linux.lu/ 117ftp://www.tux.org/pub/knaff/mtools 118@end example 119 120These patches are named 121@code{mtools-}@var{version}@code{-}@var{ddmm}@code{.taz}, where version 122stands for the base version, @var{dd} for the day and @var{mm} for the 123month. Due to a lack of space, I usually leave only the most recent 124patch. 125 126There is an mtools mailing list at mtools @@ tux.org . Please 127send all bug reports to this list. You may subscribe to the list by 128sending a message with 'subscribe mtools @@ tux.org' in its 129body to majordomo @@ tux.org . (N.B. Please remove the spaces 130around the "@@" both times. I left them there in order to fool 131spambots.) Announcements of new mtools versions will also be sent to 132the list, in addition to the linux announce newsgroups. The mailing 133list is archived at http://lists.gnu.org/pipermail/info-mtools/ 134 135 136@node Common features, Configuration, Location, Top 137@chapter Common features of all mtools commands 138 139@menu 140* arguments:: What the command line parameters of mtools 141 mean 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 146 line options 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 151@end menu 152 153@node arguments, drive letters, Common features, Common features 154@section Options and filenames 155@cindex Filenames 156@cindex Options 157MS-DOS filenames are composed of a drive letter followed by a colon, a 158subdirectory, and a filename. Only the filename part is mandatory, the 159drive letter and the subdirectory are optional. Filenames without a 160drive letter refer to Unix files. Subdirectory names can use either the 161'@code{/}' or '@code{\}' separator. The use of the '@code{\}' separator 162or wildcards requires the names to be enclosed in quotes to protect them 163from the shell. However, wildcards in Unix filenames should not be 164enclosed in quotes, because here we @strong{want} the shell to expand 165them. 166 167The regular expression "pattern matching" routines follow the Unix-style 168rules. For example, `@code{*}' matches all MS-DOS files in lieu of 169`@code{*.*}'. The archive, hidden, read-only and system attribute bits 170are ignored during pattern matching. 171 172All options use the @code{-} (minus) as their first character, not 173@code{/} as you'd expect in MS-DOS. 174 175Most mtools commands allow multiple filename parameters, which 176doesn't follow MS-DOS conventions, but which is more user-friendly. 177 178Most mtools commands allow options that instruct them how to handle file 179name clashes. @xref{name clashes}, for more details on these. All 180commands accept the @code{-V} flags which prints the version, and most 181accept the @code{-v} flag, which switches on verbose mode. In verbose 182mode, these commands print out the name of the MS-DOS files upon which 183they act, unless stated otherwise. @xref{Commands}, for a description of 184the options which are specific to each command. 185 186 187@node drive letters, directory, arguments, Common features 188@section Drive letters 189 190The meaning of the drive letters depends on the target architectures. 191However, on most target architectures, drive A is the first floppy 192drive, drive B is the second floppy drive (if available), drive J is a 193Jaz drive (if available), and drive Z is a Zip drive (if available). On 194those systems where the device name is derived from the SCSI id, the Jaz 195drive 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 197second drive on the Scsi bus (/dev/sdb). The default settings can be 198changes using a configuration file (@pxref{Configuration}). 199 200The drive letter : (colon) has a special meaning. It is used to access 201image files which are directly specified on the command line using the 202@code{-i} options. 203 204Example: 205@example 206 mcopy -i my-image-file.bin ::file1 ::file2 . 207@end example 208 209This copies @code{file1} and @code{file2} from the image file 210(@code{my-image-file.bin}) to the @code{/tmp} directory. 211 212You can also supply an offset within the image file by including 213@code{@@@@}@var{offset} into the file name. 214 215Example: 216@example 217 mcopy -i my-image-file.bin@@@@1M ::file1 ::file2 . 218@end example 219 220This looks for the image at the offset of 1M in the file, rather than 221at its beginning. 222 223@node directory, long names, drive letters, Common features 224@section Current working directory 225@pindex mcd (introduction) 226@cindex Directory 227@cindex Working directory 228@cindex Current working directory 229@cindex Default directory 230 231The @code{mcd} command (@ref{mcd}) is used to establish the device and 232the current working directory (relative to the MS-DOS filesystem), 233otherwise the default is assumed to be @code{A:/}. However, unlike 234MS-DOS, there is only one working directory for all drives, and not one 235per drive. 236 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) 244 245This version of mtools supports VFAT style long filenames. If a Unix 246filename is too long to fit in a short DOS name, it is stored as a 247VFAT long name, and a companion short name is generated. This short 248name is what you see when you examine the disk with a pre-7.0 version 249of DOS. 250 The following table shows some examples of short names: 251 252@example 253Long name MS-DOS name Reason for the change 254--------- ---------- --------------------- 255thisisatest THISIS~1 filename too long 256alain.knaff ALAIN~1.KNA extension too long 257prn.txt PRN~1.TXT PRN is a device name 258.abc ABC~1 null filename 259hot+cold HOT_CO~1 illegal character 260@end example 261 262 As you see, the following transformations happen to derive a short 263name: 264@itemize @bullet 265@item 266Illegal characters are replaced by underscores. The illegal characters 267are @code{;+=[]',\"*\\<>/?:|}. 268@item 269Extra dots, which cannot be interpreted as a main name/extension 270separator are removed 271@item 272A @code{~}@var{n} number is generated, 273@item 274The name is shortened so as to fit in the 8+3 limitation 275@end itemize 276 277 The initial Unix-style file name (whether long or short) is also called 278the @dfn{primary} name, and the derived short name is also called the 279@dfn{secondary} name. 280 281 Example: 282@example 283 mcopy /etc/motd a:Reallylongname 284@end example 285 Mtools creates a VFAT entry for Reallylongname, and uses REALLYLO as 286a short name. Reallylongname is the primary name, and REALLYLO is the 287secondary name. 288@example 289 mcopy /etc/motd a:motd 290@end example 291 Motd fits into the DOS filename limits. Mtools doesn't need to 292derivate another name. Motd is the primary name, and there is no 293secondary name. 294 295 In a nutshell: The primary name is the long name, if one exists, or 296the short name if there is no long name. 297 298 Although VFAT is much more flexible than FAT, there are still names 299that are not acceptable, even in VFAT. There are still some illegal 300characters left (@code{\"*\\<>/?:|}), and device names are still 301reserved. 302 303@example 304Unix name Long name Reason for the change 305--------- ---------- --------------------- 306prn prn-1 PRN is a device name 307ab:c ab_c-1 illegal character 308@end example 309 310 As you see, the following transformations happen if a long name is 311illegal: 312@itemize @bullet 313@item 314Illegal characters are replaces by underscores, 315@item 316A @code{-}@var{n} number is generated, 317@end itemize 318 319@node name clashes, case sensitivity, long names, Common features 320@section Name clashes 321@cindex 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) 326 327When writing a file to disk, its long name or short name may collide 328with an already existing file or directory. This may happen for all 329commands which create new directory entries, such as @code{mcopy}, 330@code{mmd}, @code{mren}, @code{mmove}. When a name clash happens, mtools 331asks you what it should do. It offers several choices: 332 333@table @code 334@item overwrite 335Overwrites the existing file. It is not possible to overwrite a 336directory with a file. 337@item rename 338Renames the newly created file. Mtools prompts for the new filename 339@item autorename 340Renames the newly created file. Mtools chooses a name by itself, without 341prompting 342@item skip 343Gives up on this file, and moves on to the next (if any) 344@end table 345 346To chose one of these actions, type its first letter at the prompt. If 347you use a lower case letter, the action only applies for this file only, 348if you use an upper case letter, the action applies to all files, and 349you won't be prompted again. 350 351You may also chose actions (for all files) on the command line, when 352invoking mtools: 353 354@table @code 355@item -D o 356Overwrites primary names by default. 357@item -D O 358Overwrites secondary names by default. 359@item -D r 360Renames primary name by default. 361@item -D R 362Renames secondary name by default. 363@item -D a 364Autorenames primary name by default. 365@item -D A 366Autorenames secondary name by default. 367@item -D s 368Skip primary name by default. 369@item -D S 370Skip secondary name by default. 371@item -D m 372Ask user what to do with primary name. 373@item -D M 374Ask user what to do with secondary name. 375@end table 376 377Note that for command line switches lower/upper differentiates between 378primary/secondary name whereas for interactive choices, lower/upper 379differentiates between just-this-time/always. 380 381The primary name is the name as displayed in Windows 95 or Windows NT: 382i.e. the long name if it exists, and the short name otherwise. The 383secondary name is the "hidden" name, i.e. the short name if a long name 384exists. 385 386By default, the user is prompted if the primary name clashes, and the 387secondary name is autorenamed. 388 389If a name clash occurs in a Unix directory, mtools only asks whether 390to overwrite the file, or to skip it. 391 392@node case sensitivity, high capacity formats, name clashes, Common features 393@section Case sensitivity of the VFAT filesystem 394@cindex Case sensitivity 395 396The VFAT filesystem is able to remember the case of the 397filenames. However, filenames which differ only in case are not allowed 398to coexist in the same directory. For example if you store a file called 399LongFileName on a VFAT filesystem, mdir shows this file as LongFileName, 400and not as Longfilename. However, if you then try to add LongFilename to 401the same directory, it is refused, because case is ignored for clash 402checks. 403 404The VFAT filesystem allows to store the case of a filename in the 405attribute byte, if all letters of the filename are the same case, and if 406all letters of the extension are the same case too. Mtools uses this 407information when displaying the files, and also to generate the Unix 408filename when mcopying to a Unix directory. This may have unexpected 409results when applied to files written using an pre-7.0 version of DOS: 410Indeed, the old style filenames map to all upper case. This is different 411from the behavior of the old version of mtools which used to generate 412lower case Unix filenames. 413 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 418@cindex Odd formats 419@cindex Weird formats 420@cindex Formats, high capacity 421@cindex Linux enhancements (High Capacity Formats) 422 423Mtools supports a number of formats which allow to store more data on 424disk as usual. Due to different operating system abilities, these 425formats are not supported on all OS'es. Mtools recognizes these formats 426transparently where supported. 427 428In order to format these disks, you need to use an operating system 429specific tool. For Linux, suitable floppy tools can be found in the 430@code{fdutils} package at the following locations~: 431@example 432@code{ftp://www.tux.org/pub/knaff/fdutils/}. 433@code{ftp://ibiblio.unc.edu/pub/Linux/utils/disk-management/fdutils-*} 434@end example 435 436See 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. 439 440@menu 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 445@end menu 446 447@node more sectors, bigger sectors, high capacity formats, high capacity formats 448@subsection More sectors 449@cindex fdformat 450@cindex vgacopy 451@cindex DMF disks 452@cindex Windows 95 (DMF disks) 453 454The oldest method of fitting more data on a disk is to use more sectors 455and more cylinders. Although the standard format uses 80 cylinders and 45618 sectors (on a 3 1/2 high density disk), it is possible to use up to 45783 cylinders (on most drives) and up to 21 sectors. This method allows 458to store up to 1743K on a 3 1/2 HD disk. However, 21 sector disks are 459twice as slow as the standard 18 sector disks because the sectors are 460packed so close together that we need to interleave them. This problem 461doesn't exist for 20 sector formats. 462 463These formats are supported by numerous DOS shareware utilities such as 464@code{fdformat} and @code{vgacopy}. In his infinite hybris, Bill Gate$ 465believed that he invented this, and called it @samp{DMF disks}, or 466@samp{Windows formatted disks}. But in reality, it has already existed 467years before! Mtools supports these formats on Linux, on SunOs and on 468the DELL Unix PC. 469 470@node bigger sectors, 2m, more sectors, high capacity formats 471@subsection Bigger sectors 472@cindex bigger sectors 473By using bigger sectors it is possible to go beyond the capacity which 474can be obtained by the standard 512-byte sectors. This is because of the 475sector header. The sector header has the same size, regardless of how 476many 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 478up header space once, whereas 8 sectors of 512 bytes have also 8 479headers, for the same amount of useful data. 480 481This method allows to store up to 1992K on a 3 1/2 HD disk. 482 483Mtools supports these formats only on Linux. 484 485@node 2m, XDF, bigger sectors, high capacity formats 486@subsection 2m 487@cindex 2m 488 489The 2m format was originally invented by Ciriaco Garcia de Celis. It 490also uses bigger sectors than usual in order to fit more data on the 491disk. However, it uses the standard format (18 sectors of 512 bytes 492each) on the first cylinder, in order to make these disks easyer to 493handle by DOS. Indeed this method allows to have a standard sized 494bootsector, which contains a description of how the rest of the disk 495should be read. 496 497However, the drawback of this is that the first cylinder can hold less 498data than the others. Unfortunately, DOS can only handle disks where 499each track contains the same amount of data. Thus 2m hides the fact that 500the first track contains less data by using a @dfn{shadow 501FAT}. (Usually, DOS stores the FAT in two identical copies, for 502additional safety. XDF stores only one copy, and it tells DOS that it 503stores two. Thus the same that would be taken up by the second FAT copy 504is saved.) This also means that your should @strong{never use a 2m disk 505to store anything else than a DOS fs}. 506 507Mtools supports these format only on Linux. 508 509@node XDF, , 2m, high capacity formats 510@subsection XDF 511@cindex XDF disks 512@cindex OS/2 (XDF disks) 513 514XDF is a high capacity format used by OS/2. It can hold 1840 K per 515disk. That's lower than the best 2m formats, but its main advantage is 516that it is fast: 600 milliseconds per track. That's faster than the 21 517sector format, and almost as fast as the standard 18 sector format. In 518order to access these disks, make sure mtools has been compiled with XDF 519support, and set the @code{use_xdf} variable for the drive in the 520configuration file. @xref{Compiling mtools}, and @ref{misc variables}, 521for details on how to do this. Fast XDF access is only available for 522Linux kernels which are more recent than 1.1.34. 523 524Mtools supports this format only on Linux. 525 526@strong{Caution / Attention distributors}: If mtools is compiled on a 527Linux kernel more recent than 1.3.34, it won't run on an older 528kernel. However, if it has been compiled on an older kernel, it still 529runs on a newer kernel, except that XDF access is slower. It is 530recommended that distribution authors only include mtools binaries 531compiled on kernels older than 1.3.34 until 2.0 comes out. When 2.0 will 532be out, mtools binaries compiled on newer kernels may (and should) be 533distributed. Mtools binaries compiled on kernels older than 1.3.34 won't 534run on any 2.1 kernel or later. 535 536@node exit codes, bugs, high capacity formats, Common features 537@section Exit codes 538All the Mtools commands return 0 on success, 1 on utter failure, or 2 539on partial failure. All the Mtools commands perform a few sanity 540checks before going ahead, to make sure that the disk is indeed an 541MS-DOS disk (as opposed to, say an ext2 or minix disk). These checks 542may reject partially corrupted disks, which might otherwise still be 543readable. To avoid these checks, set the MTOOLS_SKIP_CHECK 544environmental variable or the corresponding configuration file variable 545(@pxref{global variables}) 546@node bugs, , exit codes, Common features 547@section Bugs 548An unfortunate side effect of not guessing the proper device (when 549multiple disk capacities are supported) is an occasional error message 550from the device driver. These can be safely ignored. 551 552The fat checking code chokes on 1.72 Mb disks mformatted with pre-2.0.7 553mtools. Set the environmental variable MTOOLS_FAT_COMPATIBILITY (or the 554corresponding configuration file variable, @ref{global variables}) to 555bypass the fat checking. 556 557@comment MANskip 1 558 559@ignore 560@unnumbered Name 561mtools.conf - mtools configuration files 562 563@comment MANend-skip 5 564@section Description 565 566This manpage describes the configuration files for mtools. They 567@comment MANskip 5 568@end ignore 569 570 571@node Configuration, Commands, Common features, Top 572 573 574@chapter How to configure mtools for your environment 575@section Description 576@cindex Configuration files 577@vindex MTOOLSRC 578 579 This sections explains the syntax of the configurations files for 580mtools. The configuration files 581@comment MANend-skip 5 582are called @file{/usr/local/etc/mtools.conf} and @file{~/.mtoolsrc}. If 583the environmental variable @code{MTOOLSRC} is set, its contents is used 584as the filename for a third configuration file. These configuration 585files describe the following items: 586 587@itemize @bullet 588@item Global configuration flags and variables 589@item Per drive flags and variables 590@end itemize 591 592 593@menu 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 601@end menu 602 603@node config file location, general syntax, Configuration, Configuration 604@section Location of the configuration files 605 606@cindex Configuration file name 607@cindex Name of configuration files 608@cindex Location of configuration files 609 610@file{/usr/local/etc/mtools.conf} is the system-wide configuration file, 611and @file{~/.mtoolsrc} is the user's private configuration file. 612 613On some systems, the system-wide configuration file is called 614@file{/etc/default/mtools.conf} instead. 615 616 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 621 622The configuration files is made up of sections. Each section starts 623with a keyword identifying the section followed by a colon. 624Then follow variable assignments and flags. Variable assignments take 625the following form: 626@display 627name=value 628@end display 629Flags are lone keywords without an equal sign and value following 630them. A section either ends at the end of the file or where the next 631section begins. 632 633Lines starting with a hash (@code{#}) are comments. Newline characters 634are equivalent to whitespace (except where ending a comment). The 635configuration file is case insensitive, except for item enclosed in 636quotes (such as filenames). 637 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 643For most platforms, mtools contains reasonable compiled-in defaults for 644physical floppy drives. Thus, you usually don't need to bother with the 645configuration file, if all you want to do with mtools is to access your 646floppy drives. On the other hand, the configuration file is needed if 647you also want to use mtools to access your hard disk partitions and 648dosemu image files. 649 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 659@cindex FreeDos 660 661Global flags may be set to 1 or to 0. 662 663The following global flags are recognized: 664 665@table @code 666@item MTOOLS_SKIP_CHECK 667If this is set to 1, mtools skips most of its sanity checks. This is 668needed to read some Atari disks which have been made with the earlier 669ROMs, and which would not be recognized otherwise. 670@item MTOOLS_FAT_COMPATIBILITY 671If this is set to 1, mtools skips the fat size checks. Some disks have 672a bigger FAT than they really need to. These are rejected if this 673option is not set. 674@item MTOOLS_LOWER_CASE 675If this is set to 1, mtools displays all-upper-case short filenames as 676lowercase. This has been done to allow a behavior which is consistent 677with older versions of mtools which didn't know about the case bits. 678@item MTOOLS_NO_VFAT 679If this is set to 1, mtools won't generate VFAT entries for filenames 680which are mixed-case, but otherwise legal dos filenames. This is useful 681when working with DOS versions which can't grok VFAT longnames, such as 682FreeDos. 683@item MTOOLS_DOTTED_DIR 684In a wide directory, prints the short name with a dot instead of spaces 685separating the basename and the extension. 686@item MTOOLS_NAME_NUMERIC_TAIL 687If this is set to one (default), generate numeric tails for all long 688names (~1). If set to zero, only generate numeric tails if otherwise a 689clash would have happened. 690@item MTOOLS_TWENTY_FOUR_HOUR_CLOCK 691If 1, uses the European notation for times (twenty four hour clock), 692else uses the UK/US notation (am/pm) 693@end table 694 695Example: 696Inserting the following line into your configuration file instructs 697mtools to skip the sanity checks: 698@example 699 MTOOLS_SKIP_CHECK=1 700@end example 701 702Global variables may also be set via the environment: 703@example 704 export MTOOLS_SKIP_CHECK=1 705@end example 706 707Global string variables may be set to any value: 708@table @code 709@item MTOOLS_DATE_STRING 710The format used for printing dates of files. By default, is dd-mm-yyyy. 711@end table 712 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 717 718@menu 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 722 the media 723* open flags:: Flags passed to the open system call when the 724 device is opened 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. 729@end menu 730 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 735@vindex drive 736 737Per drive flags and values may be described in a drive section. A 738drive section starts with 739@code{drive} "@var{driveletter}" : 740 741Then follow variable-value pairs and flags. 742 743This is a sample drive description: 744@example 745 drive a: 746 file="/dev/fd0" use_xdf=1 747@end example 748 749@node location information, geometry description, general information, per drive variables 750@subsection Location information 751@cindex Hdimage 752 753For each drive, you need to describe where its data is physically 754stored (imag file, physical device, partition, offset). 755 756@table @code 757@item file 758@cindex Image file 759@cindex Name of device node 760@cindex File name of device node 761@vindex file 762The name of the file or device holding the disk image. This is 763mandatory. The file name should be enclosed in quotes. 764 765@item partition 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 775Tells mtools to treat the drive as a partitioned device, and to use the 776given partition. Only primary partitions are accessible using this 777method, and they are numbered from 1 to 4. For logical partitions, use 778the more general @code{offset} variable. The @code{partition} variable 779is intended for removable media such as Syquests, ZIP drives, and 780magneto-optical disks. Although traditional DOS sees Syquests and 781magneto-optical disks as @samp{giant floppy disks} which are 782unpartitioned, OS/2 and Windows NT treat them like hard disks, 783i.e. partioned devices. The @code{partition} flag is also useful DOSEMU 784hdimages. It is not recommended for hard disks for which direct access 785to partitions is available through mounting. 786 787@item offset 788@cindex Ram disk 789@cindex Atari Ram disk 790Describes where in the file the MS-DOS filesystem starts. This is useful 791for logical partitions in DOSEMU hdimages, and for ATARI ram disks. By 792default, this is zero, meaning that the filesystem starts right at the 793beginning of the device or file. 794@end table 795 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) 805 806Geometry information describes the physical characteristics about the 807disk. Its has three purposes: 808 809@table @asis 810@item formatting 811The geometry information is written into the boot sector of the newly 812made disk. However, you may also describe the geometry information on 813the command line. @xref{mformat}, for details. 814@item filtering 815On some Unices there are device nodes which only support one physical 816geometry. For instance, you might need a different node to access a disk 817as high density or as low density. The geometry is compared to the 818actual geometry stored on the boot sector to make sure that this device 819node is able to correctly read the disk. If the geometry doesn't match, 820this drive entry fails, and the next drive entry bearing the same drive 821letter is tried. @xref{multiple descriptions}, for more details on 822supplying several descriptions for one drive letter. 823 824If no geometry information is supplied in the configuration file, all 825disks are accepted. On Linux (and on Sparc) there exist device nodes 826with configurable geometry (@file{/dev/fd0}, @file{/dev/fd1} etc), 827and thus filtering is not needed (and ignored) for disk drives. (Mtools 828still does do filtering on plain files (disk images) in Linux: this is 829mainly intended for test purposes, as I don't have access to a Unix 830which would actually need filtering). 831 832If you do not need filtering, but want still a default geometry for 833mformatting, you may switch off filtering using the @code{mformat_only} 834flag. 835 836If you want filtering, you should supply the @code{filter} flag. If you 837supply a geometry, you must supply one of both flags. 838 839@item initial geometry 840On devices that support it (usually floppy devices), the geometry 841information is also used to set the initial geometry. This initial 842geometry is applied while reading the boot sector, which contains the 843real geometry. If no geometry information is supplied in the 844configuration file, or if the @code{mformat_only} flag is supplied, no 845initial configuration is done. 846 847On Linux, initial geometry is not really needed, as the configurable 848devices are able to auto-detect the disk type accurately enough (for 849most common formats) to read the boot sector. 850@end table 851 852Wrong geometry information may lead to very bizarre errors. That's why I 853strongly recommend that you add the @code{mformat_only} flag to your 854drive description, unless you really need filtering or initial geometry. 855 856The following geometry related variables are available: 857 858@table @code 859@item cylinders 860@itemx tracks 861@vindex cylinders 862@vindex tracks 863The number of cylinders. (@code{cylinders} is the preferred form, 864@code{tracks} is considered obsolete) 865@item heads 866@vindex heads 867The number of heads (sides). 868@item sectors 869@vindex sectors 870The number of sectors per track. 871@end table 872 873Example: the following drive section describes a 1.44M drive: 874 875@example 876 drive a: 877 file="/dev/fd0H1440" 878 fat_bits=12 879 cylinders=80 heads=2 sectors=18 880 mformat_only 881@end example 882 883The following shorthand geometry descriptions are available: 884 885@table @code 886@item 1.44m 887high density 3 1/2 disk. Equivalent to: 888@code{fat_bits=12 cylinders=80 heads=2 sectors=18} 889@item 1.2m 890high density 5 1/4 disk. Equivalent to: 891@code{fat_bits=12 cylinders=80 heads=2 sectors=15} 892@item 720k 893double density 3 1/2 disk. Equivalent to: 894@code{fat_bits=12 cylinders=80 heads=2 sectors=9} 895@item 360k 896double density 5 1/4 disk. Equivalent to: 897@code{fat_bits=12 cylinders=40 heads=2 sectors=9} 898@end table 899 900The shorthand format descriptions may be amended. For example, 901@code{360k sectors=8} 902describes a 320k disk and is equivalent to: 903@code{fat_bits=12 cylinders=40 heads=2 sectors=8} 904 905@node open flags, misc variables, geometry description, per drive variables 906@subsection Open Flags 907@vindex sync 908@vindex nodelay 909@vindex exclusive 910@cindex open flags 911@cindex synchronous writing 912@cindex exclusive access to a drive 913 914Moreover, the following flags are available: 915 916@table @code 917@item sync 918All i/o operations are done synchronously 919@item nodelay 920The device or file is opened with the O_NDELAY flag. This is needed on 921some non-Linux architectures. 922@item exclusive 923The device or file is opened with the O_EXCL flag. On Linux, this 924ensures exclusive access to the floppy drive. On most other 925architectures, and for plain files it has no effect at all. 926@end table 927 928 929@node misc variables, misc flags, open flags, per drive variables 930@subsection General Purpose Drive Variables 931 932The following general purpose drive variables are available. Depending 933to their type, these variables can be set to a string (precmd) or 934an integer (all others) 935 936@table @code 937@item fat_bits 938@vindex fat_bits 939The number of FAT bits. This may be 12 or 16. This is very rarely 940needed, as it can almost always be deduced from information in the 941boot sector. On the contrary, describing the number of fat bits may 942actually be harmful if you get it wrong. You should only use it if 943mtools gets the autodetected number of fat bits wrong, or if you want 944to mformat a disk with a weird number of fat bits. 945@item codepage 946Describes the DOS codepage used for short filenames. This is a number 947between 1 and 999. By default, codepage 850 is used. The reason for 948this is because this codepage contains most of the characters that are 949also available in ISO-Latin-1. You may also specify a global codepage 950for all drives by using the global @code{default_codepage} parameter 951(outside of any drive description). This parameters exists starting at 952version 4.0.0 953@item precmd 954@cindex Solaris (volcheck) 955@cindex Executing commands before opening the device 956On some variants of Solaris, it is necessary to call 'volcheck -v' 957before opening a floppy device, in order for the system to notice that 958there is indeed a disk in the drive. @code{precmd="volcheck -v"} in the 959drive clause establishes the desired behavior. 960 961@item blocksize 962@cindex raw device 963@cindex character devices 964@cindex blocksize 965This parameter represents a default block size to be always used on this 966device. All I/O is done with multiples of this block size, 967independantly of the sector size registered in the filesystem's boot 968sector. This is useful for character devices whose sector size is not 969512, such as for example CD Rom drives on Solaris. 970 971@end table 972 973Only the @code{file} variable is mandatory. The other parameters may 974be left out. In that case a default value or an autodetected value is 975used. 976 977 978 979@node misc flags, multiple descriptions, misc variables, per drive variables 980@subsection General Purpose Drive Flags 981 982A flag can either be set to 1 (enabled) or 0 (disabled). If the value is 983ommitted, it is enabled. For example, @code{scsi} is equivalent to 984@code{scsi=1} 985 986@table @code 987@item nolock 988@cindex disable locking 989@cindex locking (disabling it) 990@cindex plain floppy: device xxx busy 991Instruct mtools to not use locking on this drive. This is needed on 992systems with buggy locking semantics. However, enabling this makes 993operation less safe in cases where several users may access the same 994drive at the same time. 995 996@item scsi 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 1004When set to 1, this option tells mtools to use raw SCSI I/O instead of 1005the standard read/write calls to access the device. Currently, this is 1006supported on HP/UX, Solaris and SunOs. This is needed because on some 1007architectures, such as SunOs or Solaris, PC media can't be accessed 1008using the @code{read} and @code{write} syscalls, because the OS expects 1009them to contain a Sun specific "disk label". 1010 1011As raw Scsi access always uses the whole device, you need to specify the 1012"partition" flag in addition 1013 1014On some architectures, such as Solaris, mtools needs root privileges to 1015be able to use the @code{scsi} option. Thus mtools should be installed 1016set uid root on Solaris if you want to access Zip/Jaz drives. Thus, if 1017the @code{scsi} flag is given, @code{privileged} is automatically 1018implied, unless explicitly disabled by @code{privileged=0} 1019 1020Mtools uses its root privileges to open the device, and to issue the 1021actual SCSI I/O calls. Moreover, root privileges are only used for 1022drives 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}. 1025 1026@item privileged 1027@cindex setuid installation 1028@cindex setgid installation 1029When set to 1, this instructs mtools to use its set-uid and set-gid 1030privileges for opening the given drive. This option is only valid for 1031drives 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 1034not installed setuid or setgid. This option is implied by 'scsi=1', but 1035again only for drives defined in system-wide configuration files. 1036Privileged may also be set explicitely to 0, in order to tell mtools not 1037to use its privileges for a given drive even if @code{scsi=1} is set. 1038 1039Mtools only needs to be installed setuid if you use the 1040@code{privileged} or @code{scsi} drive variables. If you do not use 1041these options, mtools works perfectly well even when not installed 1042setuid root. 1043 1044@item vold 1045@cindex Solaris (vold) 1046@cindex Vold (mediamgr) 1047 1048Instructs mtools to interpret the device name as a vold identifier 1049rather than as a filename. The vold identifier is translated into a 1050real filename using the @code{media_findname()} and 1051@code{media_oldaliases()} functions of the @code{volmgt} library. This 1052flag is only available if you configured mtools with the 1053@code{--enable-new-vold} option before compilation. 1054 1055@item swap 1056@cindex Atari 1057@cindex Wordswapped 1058 1059Consider the media as a word-swapped Atari disk. 1060 1061@item use_xdf 1062@cindex XDF disks (how to configure) 1063@vindex use_xdf 1064If this is set to a non-zero value, mtools also tries to access this 1065disk as an XDF disk. XDF is a high capacity format used by OS/2. This 1066is off by default. @xref{XDF}, for more details. 1067@item mformat_only 1068@vindex mformat_only 1069Tells mtools to use the geometry for this drive only for mformatting and 1070not for filtering. 1071 1072@item filter 1073@vindex filter 1074Tells mtools to use the geometry for this drive both for mformatting and 1075filtering. 1076 1077@item remote 1078Tells mtools to connect to floppyd (@pxref{floppyd}). 1079@end table 1080 1081 1082@node multiple descriptions, , misc flags, per drive variables 1083@subsection Supplying multiple descriptions for a drive 1084 1085It is possible to supply multiple descriptions for a drive. In that 1086case, the descriptions are tried in order until one is found that 1087fits. Descriptions may fail for several reasons: 1088 1089@enumerate 1090@item 1091because the geometry is not appropriate, 1092@item 1093because there is no disk in the drive, 1094@item 1095or because of other problems. 1096@end enumerate 1097 1098Multiple definitions are useful when using physical devices which are 1099only able to support one single disk geometry. 1100Example: 1101@example 1102 drive a: file="/dev/fd0H1440" 1.44m 1103 drive a: file="/dev/fd0H720" 720k 1104@end example 1105 1106This instructs mtools to use /dev/fd0H1440 for 1.44m (high density) 1107disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this 1108feature is not really needed, as the /dev/fd0 device is able to handle 1109any geometry. 1110 1111You may also use multiple drive descriptions to access both of your 1112physical drives through one drive letter: 1113 1114@example 1115 drive z: file="/dev/fd0" 1116 drive z: file="/dev/fd1" 1117@end example 1118 1119With this description, @code{mdir z:} accesses your first physical 1120drive if it contains a disk. If the first drive doesn't contain a disk, 1121mtools checks the second drive. 1122 1123When using multiple configuration files, drive descriptions in the files 1124parsed last override descriptions for the same drive in earlier 1125files. In order to avoid this, use the @code{drive+} or @code{+drive} 1126keywords instead of @code{drive}. The first adds a description to the 1127end of the list (i.e. it will be tried last), and the first adds it to 1128the start of the list. 1129 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) 1137 1138The configuration files are parsed in the following order: 1139@enumerate 1140@item 1141compiled-in defaults 1142@item 1143@file{/usr/local/etc/mtools.conf} 1144@item 1145@file{/etc/mtools} 1146This is for backwards compatibility only, and is only parsed if 1147@file{mtools.conf} 1148doesn't exist. 1149@item 1150@file{~/.mtoolsrc}. 1151@item 1152@file{$MTOOLSRC} (file pointed by the @code{MTOOLSRC} environmental 1153variable) 1154@end enumerate 1155 1156Options described in the later files override those described in the 1157earlier files. Drives defined in earlier files persist if they are not 1158overridden in the later files. For instance, drives A and B may be 1159defined in @file{/usr/local/etc/mtools.conf} and drives C and D may be 1160defined in @file{~/.mtoolsrc} However, if @file{~/.mtoolsrc} also 1161defines drive A, this new description would override the description of 1162drive A in @file{/usr/local/etc/mtools.conf} instead of adding to it. If 1163you want to add a new description to a drive already described in an 1164earlier file, you need to use either the @code{+drive} or @code{drive+} 1165keyword. 1166 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 1172 1173The syntax described herein is new for version @code{mtools-3.0}. The 1174old line-oriented syntax is still supported. Each line beginning with a 1175single letter is considered to be a drive description using the old 1176syntax. Old style and new style drive sections may be mixed within the 1177same configuration file, in order to make upgrading easier. Support for 1178the old syntax will be phased out eventually, and in order to discourage 1179its use, I purposefully omit its description here. 1180 1181@comment MANskip 5 1182 1183@node Commands, Compiling mtools, Configuration, Top 1184@chapter Command list 1185@cindex Command list 1186@cindex List of available commands 1187 1188 This section describes the available mtools commands, and the command 1189line parameters that each of them accepts. Options which are common to 1190all mtools commands are not described here, @ref{arguments} for a 1191description of those. 1192 1193@menu 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 1220@end menu 1221 1222@node floppyd, floppyd_installtest, Commands, Commands 1223@section Floppyd 1224@pindex floppyd 1225@cindex X terminal 1226@cindex remote floppy access 1227 1228@code{Floppyd} is used as a server to grant access to the floppy drive 1229to clients running on a remote machine, just as an X server grants 1230access to the display to remote clients. It has the following syntax: 1231 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} 1234 1235 1236@code{floppyd} is always associated with an X server. It runs on the 1237same machine as its X server, and listens on port 5703 and above. 1238 1239@subsection Authentication 1240 1241@code{floppyd} authenticates remote clients using the @code{Xauthority} 1242protocol. Xhost authentication is not supported. Each floppyd is 1243associated with an X server. When a remote client attempts to connect 1244to floppyd, it sends floppyd the X authority record corresponding to 1245floppyd's X server. Floppyd in turn then tries to open up a connection 1246to the X server in order to verify the authenticity of the xauth record. 1247If the connection to the X server succeeds, the client is granted 1248access. 1249@code{DISPLAY}. 1250 1251@strong{Caution}: In order to make authentication work correctly, the 1252local host should @strong{not} be listed in the @code{xhost} list of 1253allowed hosts. 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} 1256runs on the same host as the X server, all its probe connection would 1257succeed even for clients who supplied a bad cookie. This means that 1258your 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 1261probing those display names with the @code{-l} option. 1262 1263@subsection Command line options 1264 1265@table @code 1266@item d 1267Daemon mode. Floppyd runs its own server loop. Do not supply this if 1268you start floppyd from @code{inetd.conf} 1269@item s @var{port} 1270Port number for deamon mode. Default is 5703 + @var{displaynumber}. 1271This flag implies daemon mode. For example, for display 1272@code{hitchhiker:5}, the port would be 5708. 1273@item b @var{ipaddr} 1274Bind address (for multihomed hosts). This flag implies daemon mode 1275@item r @var{user} 1276Run the server under as the given user 1277@item x @var{display} 1278X display to use for authentication. By default, this is taken from the 1279@code{DISPLAY} variable. If neither the @code{x} attribute is present 1280nor @code{DISPLAY} is set, floppyd uses @code{:0.0}. 1281@end table 1282 1283@var{devicenames} is a list of device nodes to be opened. Default 1284is @code{/dev/fd0}. Multiple devices are only supported on mtools 1285versions newer than 3.9.11. 1286 1287 1288@subsection Connecting to floppyd 1289 1290 In order to use floppyd, add the flag @code{remote} to the device 1291description in your @file{~/.mtoolsrc} file. If the flag @code{remote} 1292is given, the @code{file} parameter of the device description is taken 1293to be a remote address. It's format is the following: 1294@var{hostname}@code{:}@var{displaynumber}[@code{/}[@var{baseport}][@code{/}@var{drive}]]. When 1295using 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 1298multiple drives associated with a single display (only mtools versions 1299more recent than 3.9.11) 1300 1301@subsection Examples: 1302 1303 The following starts a floppy daemon giving access to @file{/dev/fd0}, 1304listening on the default port 5703, tied to the default X servers: 1305 1306@example 1307floppyd -d /dev/fd0 1308@end example 1309 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 13125704. We assume that the local host is named @code{hitchhiker}. 1313 1314@example 1315floppyd -d /dev/fd0 1316floppyd -d -x :1 -p 5704 /dev/fd0 1317@end example 1318 1319 If you want to start floppyd by @code{inetd} instead of running it as a 1320daemon, insert the following lines into @file{/etc/services}: 1321@example 1322# floppy daemon 1323floppyd-0 5703/tcp # floppy daemon for X server :0 1324floppyd-1 5704/tcp # floppy daemon for X server :1 1325@end example 1326 1327 And insert the following into @file{/etc/inetd.conf} (assuming that you 1328have defined a user named floppy in your @file{/etc/passwd}): 1329 1330@example 1331# floppy daemon 1332floppyd-0 stream tcp wait floppy /usr/sbin/floppyd floppyd /dev/fd0 1333floppyd-1 stream tcp wait floppy /usr/sbin/floppyd floppyd -x :1 /dev/fd0 1334@end example 1335 1336 Note that you need to supply the X display names for the second 1337floppyd. This is because the port is opened by inetd.conf, and hence 1338floppyd cannot know its number to interfere the display number. 1339 1340 1341On the client side, insert the following into your @file{~/.mtoolsrc} 1342to define a drive letter accessing floppy drive in your X terminal: 1343@example 1344drive x: file="$DISPLAY" remote 1345@end example 1346 1347If your X terminal has more than one drive, you may access the 1348additional drives as follows: 1349@example 1350drive y: file="$DISPLAY//1" remote 1351drive z: file="$DISPLAY//2" remote 1352@end example 1353 1354@node floppyd_installtest, mattrib, floppyd, Commands 1355@section Floppyd_installtest 1356@pindex floppyd_installtest 1357@cindex X terminal 1358@cindex remote floppy access 1359 1360@code{Floppyd_installtest} is used to check for the presence of a running 1361floppyd daemon. This is usefull, if you have a small frontend script to 1362mtools, which decides whether to use floppyd or not. 1363 1364@code{floppyd_installtest} [@code{-f}] Connect-String 1365 1366If the @code{-f} option is specified, @code{floppyd_installtest} does a 1367full X-Cookie authentication and complains if this does not work. 1368 1369The connect-String has the format described in the floppyd-section: 1370@var{hostname}@code{:}@var{displaynumber}[@code{/}@var{baseport}] 1371 1372@node mattrib, mbadblocks, floppyd_installtest, Commands 1373@section Mattrib 1374@pindex mattrib 1375@cindex Changing file attributes 1376@cindex Hidden files 1377@cindex Read-only files (changing the attribute) 1378@cindex System files 1379@cindex Archive bit 1380 1381@code{Mattrib} is used to change MS-DOS file attribute flags. It has the 1382following syntax: 1383 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{} ] 1386 1387@code{Mattrib} adds attribute flags to an MS-DOS file (with the 1388`@code{+}' operator) or remove attribute flags (with the `@code{-}' 1389operator). 1390 1391@code{Mattrib} supports the following attribute bits: 1392 1393@table @code 1394@item a 1395Archive bit. Used by some backup programs to indicate a new file. 1396@item r 1397Read-only bit. Used to indicate a read-only file. Files with this bit 1398set cannot be erased by @code{DEL} nor modified. 1399@item s 1400System bit. Used by MS-DOS to indicate a operating system file. 1401@item h 1402Hidden bit. Used to make files hidden from @code{DIR}. 1403@end table 1404 1405@code{Mattrib} supports the following command line flags: 1406@table @code 1407@item / 1408Recursive. Recursively list the attributes of the files in the subdirectories. 1409@item X 1410Concise. Prints the attributes whithout any whitespace padding. If 1411neither the "/" option is given, nor the @var{msdosfile} contains a 1412wildcard, and there is only one Msdos file parameter on the command 1413line, only the attribute is printed, and not the filename. This option 1414is convenient for scripts 1415@item p 1416Replay mode. Outputs a series of mformat commands that will reproduce 1417the current situation, starting from a situation as left by untarring 1418the Dos filesystem. Commands are only output for attribute settings 1419that differ from the default (archive bit set for files, unset for 1420directories). This option is intended to be used in addition to 1421tar. The @code{readonly} attribute is not taken into account, as tar can 1422set that one itself. 1423@end table 1424 1425@node mbadblocks, mcat, mattrib, Commands 1426@section Mbadblocks 1427 1428The @code{mbadblocks} command is used to scan an MS-DOS floppy and mark 1429its unused bad blocks as bad. It uses the following syntax: 1430 1431@code{mbadblocks} @var{drive}@code{:} 1432@pindex mbadblocks 1433@cindex Marking blocks as bad 1434@cindex Bad blocks 1435@cindex Read errors 1436 1437@code{Mbadblocks} scans an MS-DOS floppy for bad blocks. All unused bad 1438blocks are marked as such in the FAT. This is intended to be used right 1439after @code{mformat}. It is not intended to salvage bad disks. 1440@subsection Bugs 1441@code{Mbadblocks} should (but doesn't yet :-( ) also try to salvage bad 1442blocks which are in use by reading them repeatedly, and then mark them 1443bad. 1444 1445@node mcat, mcd, mbadblocks, Commands 1446@section Mcat 1447 1448The @code{mcat} command is used to copy an entire disk image from or 1449to the floppy device. It uses the following syntax: 1450 1451@code{mcat} [@code{-w}] @var{drive}@code{:} 1452@pindex mcat 1453@cindex Copying an entire disk image 1454@cindex Disk image 1455@cindex Floppyd cat 1456 1457@code{Mcat} performs the same task as the unix @code{cat} command. It 1458is included into the mtools package, since @code{cat} cannot access 1459remote floppy devices offered by the mtools floppy daemon. 1460Now it is possible to create boot floppies remotely. 1461 1462The default operation is reading. The output is written to stdout. 1463 1464If the @code{-w} option is specified, mcat reads a disk-image from 1465stdin and writes it to the given device. 1466@strong{Use this carefully!} Because of the lowlevel nature of this 1467command, it will happily destroy any data written before on the 1468disk without warning! 1469 1470@node mcd, mclasserase, mcat, Commands 1471@section Mcd 1472@pindex mcd 1473@cindex Directory (changing) 1474@cindex Working directory 1475@cindex Current working directory (changing the) 1476@cindex Default directory (changing the) 1477@cindex Mcwd file 1478 1479The @code{mcd} command is used to change the mtools working directory 1480on the MS-DOS disk. It uses the following syntax: 1481 1482@example 1483@code{mcd} [@var{msdosdirectory}] 1484@end example 1485 1486Without arguments, @code{mcd} reports the current device and working 1487directory. Otherwise, @code{mcd} changes the current device and current 1488working directory relative to an MS-DOS filesystem. 1489 1490The environmental variable @code{MCWD} may be used to locate the file 1491where the device and current working directory information is stored. 1492The default is @file{$HOME/.mcwd}. Information in this file is ignored 1493if the file is more than 6 hours old. 1494 1495@code{Mcd} returns 0 on success or 1 on failure. 1496 1497Unlike MS-DOS versions of @code{CD}, @code{mcd} can be used to change to 1498another device. It may be wise to remove old @file{.mcwd} files at logout. 1499 1500@node mclasserase, mcopy, mcd, Commands 1501@section Mclasserase 1502@pindex mclasserase 1503@cindex Memory Card 1504@cindex Physically erase 1505 1506The @code{mclasserase} command is used to wipe memory cards by 1507overwriting it three times: first with @code{0xff}, then with 1508@code{0x00}, then with @code{0xff} again. The command uses the following 1509syntax: 1510 1511@example 1512@code{mclasserase} [@code{-d}] @var{msdosdrive} 1513@end example 1514 1515Dos drive is optional, if none is specified, use @code{A:}. If more than 1516one drive are specified, all but the last are ignored. 1517 1518@code{Mclasserase} accepts the following command line options: 1519 1520@table @code 1521@item d 1522Stop after each erase cycle, for testing purposes 1523@item p 1524Not yet implemented 1525@end table 1526 1527 1528@code{Mclasserase} returns 0 on success or -1 on failure. 1529 1530 1531@node mcopy, mdel, mclasserase, Commands 1532@section Mcopy 1533@pindex mcopy 1534@cindex Reading MS-DOS files 1535@cindex Writing MS-DOS files 1536@cindex Copying MS-DOS files 1537@cindex Concatenating MS-DOS files 1538@cindex Text files 1539@cindex CR/LF conversions 1540 1541The @code{mcopy} command is used to copy MS-DOS files to and from 1542Unix. It uses the following syntax: 1543 1544@example 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} 1548@end example 1549 1550 1551 1552@code{Mcopy} copies the specified file to the named file, or copies 1553multiple files to the named directory. The source and target can be 1554either MS-DOS or Unix files. 1555 1556The use of a drive letter designation on the MS-DOS files, 'a:' for 1557example, determines the direction of the transfer. A missing drive 1558designation implies a Unix file whose path starts in the current 1559directory. If a source drive letter is specified with no attached file 1560name (e.g. @code{mcopy a: .}), all files are copied from that drive. 1561 1562If only a single, MS-DOS source parameter is provided (e.g. "mcopy 1563a:foo.exe"), an implied destination of the current directory 1564(`@code{.}') is assumed. 1565 1566A filename of `@code{-}' means standard input or standard output, depending 1567on its position on the command line. 1568 1569@code{Mcopy} accepts the following command line options: 1570 1571@table @code 1572@item t 1573Text file transfer. Mcopy translates incoming carriage return/line 1574feeds to line feeds when copying from Dos to Unix, and vice-versa when 1575copying from Unix to Dos. 1576@item b 1577Batch mode. Optimized for huge recursive copies, but less secure if a 1578crash happens during the copy. 1579@item s 1580Recursive copy. Also copies directories and their contents 1581@item p 1582Preserves the attributes of the copied files 1583@item Q 1584When mcopying multiple files, quits as soon as one copy fails (for 1585example due to lacking storage space on the target disk) 1586@item a 1587Text (Ascii) file transfer. @code{Mcopy} translates incoming carriage 1588return/line feeds to line feeds. 1589@item T 1590Text (Ascii) file transfer with charset conversion. Differs from 1591@code{-a} in the @code{Mcopy} also translates incoming PC-8 characters 1592to ISO-8859-1 equivalents as far as possible. When reading DOS files, 1593untranslatable characters are replaced by '@code{#}'; when writing DOS files, 1594untranslatable characters are replaced by '@code{.}'. 1595@item n 1596No confirmation when overwriting Unix files. @code{Mcopy} doesn't warn 1597the user when overwriting an existing Unix file. If the target file already exists, 1598and the @code{-n} option is not in effect, @code{mcopy} asks whether to 1599overwrite the file or to rename the new file (@ref{name clashes}) for 1600details). In order to switch off confirmation for DOS files, use @code{-o}. 1601@item m 1602Preserve the file modification time. 1603@item v 1604Verbose. Displays the name of each file as it is copied. 1605@end table 1606 1607@subsection Bugs 1608Unlike MS-DOS, the '+' operator (append) from MS-DOS is not 1609supported. However, you may use @code{mtype} to produce the same effect: 1610@example 1611mtype a:file1 a:file2 a:file3 >unixfile 1612mtype a:file1 a:file2 a:file3 | mcopy - a:msdosfile 1613@end example 1614 1615@node mdel, mdeltree, mcopy, Commands 1616@section Mdel 1617@pindex mdel 1618@cindex removing MS-DOS files 1619@cindex erasing MS-DOS files 1620@cindex deleting MS-DOS files 1621 1622The @code{mdel} command is used to delete an MS-DOS file. Its syntax 1623is: 1624 1625@display 1626@code{mdel} [@code{-v}] @var{msdosfile} [ @var{msdosfiles} @dots{} ] 1627@end display 1628 1629@code{Mdel} deletes files on an MS-DOS filesystem. 1630 1631@code{Mdel} asks for verification prior to removing a read-only file. 1632 1633@node mdeltree, mdir, mdel, Commands 1634@section Mdeltree 1635@pindex mdeltree 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 1640 1641The @code{mdeltree} command is used to delete an MS-DOS file. Its syntax 1642is: 1643 1644@display 1645@code{mdeltree} [@code{-v}] @var{msdosdirectory} [@var{msdosdirectories}@dots{}] 1646@end display 1647 1648@code{Mdeltree} removes a directory and all the files and subdirectories 1649it contains from an MS-DOS filesystem. An error occurs if the directory 1650to be removed does not exist. 1651 1652@node mdir, mdu, mdeltree, Commands 1653@section Mdir 1654@pindex mdir 1655@cindex Read-only files (listing them) 1656@cindex Listing a directory 1657@cindex Directory listing 1658 1659The @code{mdir} command is used to display an MS-DOS directory. Its 1660syntax is: 1661 1662@code{mdir} [@code{-/}] [@code{-f}] [@code{-w}] [@code{-a}] [@code{-b}] @var{msdosfile} [ @var{msdosfiles}@dots{}] 1663 1664@code{Mdir} 1665displays the contents of MS-DOS directories, or the entries for some 1666MS-DOS files. 1667 1668@code{Mdir} supports the following command line options: 1669 1670@table @code 1671@item / 1672Recursive output, just like Dos' @code{-s} option 1673@item w 1674Wide output. With this option, @code{mdir} prints the filenames across 1675the page without displaying the file size or creation date. 1676@item a 1677Also list hidden files. 1678@item f 1679Fast. Do not try to find out free space. On larger disks, finding out 1680the amount of free space takes up some non trivial amount of time, as 1681the whole FAT must be read in and scanned. The @code{-f} flag bypasses 1682this step. This flag is not needed on FAT32 filesystems, which store 1683the size explicitely. 1684@item b 1685Concise listing. Lists each directory name or filename, one per line 1686(including the filename extension). This switch displays no heading 1687information and no summary. Only a newline separated list of pathnames 1688is displayed. 1689@end table 1690 1691An error occurs if a component of the path is not a directory. 1692 1693@node mdu, mformat, mdir, Commands 1694@section Mdu 1695@pindex mdu 1696@cindex Space occupied by directories and files 1697@cindex du 1698@cindex Listing space occupied by directories and files 1699@cindex Occupation of space by directories and files 1700 1701@code{Mdu} is used to list the space occupied by a directory, its 1702subdirectories and its files. It is similar to the @code{du} command on 1703Unix. The unit used are clusters. Use the minfo command to find out 1704the cluster size. 1705 1706@code{mdu} [@code{-a}] [ @var{msdosfiles} @dots{} ] 1707 1708 1709@table @code 1710@item a 1711All files. List also the space occupied for individual files. 1712@item s 1713Only list the total space, don't give details for each subdirectory. 1714@end table 1715 1716 1717 1718@node mformat, mkmanifest, mdu, Commands 1719@section Mformat 1720@pindex mformat 1721@cindex Initializing disks 1722@cindex Formatting disks 1723@cindex Filesystem creation 1724 1725The @code{mformat} command is used to add an MS-DOS filesystem to a 1726low-level formatted diskette. Its syntax is: 1727 1728@display 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}] 1741 @var{drive:} 1742@end display 1743 1744@code{Mformat} adds a minimal MS-DOS filesystem (boot sector, FAT, and 1745root directory) to a diskette that has already been formatted by a Unix 1746low-level format. 1747 1748 1749The following options are supported: (The S, 2, 1 and M options may not 1750exist if this copy of mtools has been compiled without the USE_2M 1751option) 1752 1753The following options are the same as for Dos's format command: 1754 1755@comment xMANoptions 1756 1757@table @code 1758@item v 1759Specifies the volume label. A volume label identifies the disk and can 1760be a maximum of 11 characters. If you omit the -v switch, mlabel will 1761assign no label to the disk. 1762@item f 1763Specifies the size of the DOS filesystem to format. Only a certain 1764number of predefined sizes are supported by this flag; for others use 1765the -h/-t/-s flags. The following sizes are supported: 1766@table @asis 1767@item 160 1768160K, single-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD) 1769@item 180 1770160K, single-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD) 1771@item 320 1772320K, double-sided, 8 sectors per track, 40 cylinders (for 5 1/4 DD) 1773@item 360 1774360K, double-sided, 9 sectors per track, 40 cylinders (for 5 1/4 DD) 1775@item 720 1776720K, double-sided, 9 sectors per track, 80 cylinders (for 3 1/2 DD) 1777@item 1200 17781200K, double-sided, 15 sectors per track, 80 cylinders (for 5 1/4 HD) 1779@item 1440 17801440K, double-sided, 18 sectors per track, 80 cylinders (for 3 1/2 HD) 1781@item 2880 17822880K, double-sided, 36 sectors per track, 80 cylinders (for 3 1/2 ED) 1783@end table 1784 1785@item t 1786Specifies the number of tracks on the disk. 1787@item h 1788The number of heads (sides). 1789@item n 1790Specifies the number of sectors per track. If the 2m option is given, 1791number of 512-byte sector equivalents on generic tracks (i.e. not head 0 1792track 0). If the 2m option is not given, number of physical sectors per 1793track (which may be bigger than 512 bytes). 1794 1795@item 1 1796Formats a single side (equivalent to -h 1) 1797 1798@item 4 1799Formats a 360K double-sided disk (equivalent to -f 360). When used 1800together with -the 1 switch, this switch formats a 180K disk 1801 1802@item 8 1803Formats a disk with 8 sectors per track. 1804 1805@end table 1806 1807MSDOS format's @code{q}, @code{u} and @code{b} options are not 1808supported, and @code{s} has a different meaning. 1809 1810The following options are specific to mtools: 1811 1812@table @code 1813 1814@item F 1815Format the partition as FAT32. 1816 1817@item S 1818The sizecode. The size of the sector is 2 ^ (sizecode + 7). 1819@item X 1820formats the disk as an XDF disk. @xref{XDF}, for more details. The disk 1821has first to be low-level formatted using the xdfcopy utility included 1822in the fdutils package. XDF disks are used for instance for OS/2 install 1823disks. 1824@item 2 18252m format. The parameter to this option describes the number of 1826sectors on track 0, head 0. This option is recommended for sectors 1827bigger than normal. 1828@item 3 1829don't use a 2m format, even if the current geometry of the disk is a 2m 1830geometry. 1831@item 0 1832Data transfer rate on track 0 1833@item A 1834Data transfer rate on tracks other than 0 1835@item M 1836software sector size. This parameter describes the sector size in bytes used 1837by the MS-DOS filesystem. By default it is the physical sector size. 1838@item N 1839Uses the requested serial number, instead of generating one 1840automatically 1841@item a 1842If this option is given, an Atari style serial number is generated. 1843Ataris store their serial number in the OEM label. 1844@item C 1845creates the disk image file to install the MS-DOS filesystem on 1846it. Obviously, this is useless on physical devices such as floppies 1847and hard disk partitions, but is interesting for image files. 1848@item H 1849number of hidden sectors. This parameter is useful for formatting hard 1850disk partition, which are not aligned on track boundaries (i.e. first 1851head of first track doesn't belong to the partition, but contains a 1852partition table). In that case the number of hidden sectors is in 1853general the number of sectors per cylinder. This is untested. 1854@item I 1855Sets the fsVersion id when formatting a FAT32 drive. In order to find 1856this out, run minfo on an existing FAT32 drive, and mail me about it, so 1857I can include the correct value in future versions of mtools. 1858@item c 1859Sets the size of a cluster (in sectors). If this cluster size would 1860generate a FAT that too big for its number of bits, mtools automatically 1861increases the cluster size, until the FAT is small enough. 1862@item d 1863Sets the number of FAT copies. Default is 2. This setting can also be 1864specified using the @code{MTOOLS_NFATS} environment variable. 1865@item r 1866Sets the size of the root directory (in sectors). Only applicable to 12 1867and 16 bit FATs. This setting can also be specified using the 1868@code{MTOOLS_DIR_LEN} environment variable. 1869@item L 1870Sets the length of the FAT. 1871@item B 1872Use the bootsector stored in the given file or device, instead of using 1873its own. Only the geometry fields are updated to match the target disks 1874parameters. 1875@item k 1876Keep the existing boot sector as much as possible. Only the geometry 1877fields and other similar filesystem data are updated to match the target 1878disks parameters. 1879 1880@item m 1881Use a non-standard media descriptor byte for this disk. The media 1882descriptor is stored at position 21 of the boot sector, and as first 1883byte in each FAT copy. Using this option may confuse DOS or older mtools 1884version, and may make the disk unreadable. Only use if you know what you 1885are doing. 1886 1887@end table 1888 1889To 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 1891default. 1892 1893@code{Mformat} returns 0 on success or 1 on failure. 1894 1895It doesn't record bad block information to the Fat, use 1896@code{mbadblocks} for that. 1897 1898@node mkmanifest, minfo, mformat, Commands 1899@section Mkmanifest 1900@pindex mkmanifest 1901@cindex packing list 1902 1903The @code{mkmanifest} command is used to create a shell script (packing 1904list) to restore Unix filenames. Its syntax is: 1905 1906@code{mkmanifest} [ @var{files} ] 1907 1908@code{Mkmanifest} creates a shell script that aids in the restoration of 1909Unix filenames that got clobbered by the MS-DOS filename restrictions. 1910MS-DOS filenames are restricted to 8 character names, 3 character 1911extensions, upper case only, no device names, and no illegal characters. 1912 1913 1914The mkmanifest program is compatible with the methods used in 1915@code{pcomm, arc,} and @code{mtools} to change perfectly good Unix 1916filenames to fit the MS-DOS restrictions. This command is only useful if 1917the target system which will read the diskette cannot handle vfat long 1918names. 1919 1920@subsection Example 1921You want to copy the following Unix files to a MS-DOS diskette (using the 1922@code{mcopy} command). 1923 1924@example 1925 very_long_name 1926 2.many.dots 1927 illegal: 1928 good.c 1929 prn.dev 1930 Capital 1931@end example 1932 1933@code{Mcopy} 1934converts the names to: 1935 1936@example 1937 very_lon 1938 2xmany.dot 1939 illegalx 1940 good.c 1941 xprn.dev 1942 capital 1943@end example 1944 1945The command: 1946@example 1947mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital >manifest 1948@end example 1949would produce the following: 1950@example 1951 mv very_lon very_long_name 1952 mv 2xmany.dot 2.many.dots 1953 mv illegalx illegal: 1954 mv xprn.dev prn.dev 1955 mv capital Capital 1956@end example 1957 1958Notice that "good.c" did not require any conversion, so it did not 1959appear in the output. 1960 1961Suppose I've copied these files from the diskette to another Unix 1962system, and I now want the files back to their original names. If the 1963file "manifest" (the output captured above) was sent along with those 1964files, it could be used to convert the filenames. 1965 1966@subsection Bugs 1967 1968The 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. 1970 1971 1972@node minfo, mlabel, mkmanifest, Commands 1973@section Minfo 1974@pindex minfo 1975@cindex mformat parameters 1976@cindex getting parameters of a Dos fs 1977 1978The @code{minfo} command prints the parameters of a Dos filesystem, such 1979as number of sectors, heads and cylinders. It also prints an mformat 1980command line which can be used to create a similar Dos filesystem on 1981another media. However, this doesn't work with 2m or Xdf media, and 1982with Dos 1.0 filesystems 1983@display 1984@code{minfo} @var{drive}: 1985@end display 1986 1987Mlabel supports the following option: 1988@table @code 1989@item v 1990Prints a hexdump of the bootsector, in addition to the other information 1991@end table 1992 1993 1994@node mlabel, mmd, minfo, Commands 1995@section Mlabel 1996@pindex mlabel 1997@cindex Labeling a disk 1998@cindex Disk label 1999 2000The @code{mlabel} command adds a volume label to a disk. Its syntax is: 2001@display 2002@code{mlabel} [@code{-vcsn}] [@code{-N} @var{serial}] @var{drive}:[@var{new_label}] 2003@end display 2004 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. 2008To delete an existing volume label, press return at the prompt. 2009 2010Reasonable care is taken to create a valid MS-DOS volume label. If an 2011invalid label is specified, @code{mlabel} changes the label (and 2012displays the new label if the verbose mode is set). @code{Mlabel} 2013returns 0 on success or 1 on failure. 2014 2015Mlabel supports the following options: 2016@table @code 2017@item c 2018Clears an existing label, without prompting the user 2019@item s 2020Shows the existing label, without prompting the user. 2021@item n 2022Assigns a new (random) serial number to the disk 2023@item N @var{serial} 2024Sets the supplied serial number. The serial number should be supplied as 2025an 8 digit hexadecimal number, without spaces 2026@end table 2027 2028 2029@node mmd, mmount, mlabel, Commands 2030@section Mmd 2031@pindex mmd 2032@cindex Making a directory 2033@cindex Creating a directory 2034@cindex Directory creation 2035@cindex Subdirectory creation 2036 2037The @code{mmd} command is used to make an MS-DOS subdirectory. Its 2038syntax is: 2039 2040@code{mmd} [@code{-D} @var{clash_option}] @var{msdosdirectory} [ 2041@var{msdosdirectories}@dots{} ] 2042 2043@code{Mmd} makes a new directory on an MS-DOS filesystem. An error occurs 2044if the directory already exists. 2045 2046 2047@node mmount, mmove, mmd, Commands 2048@section Mmount 2049@pindex mmount 2050@cindex Linux enhancements (mmount) 2051@cindex Mounting a disk 2052@cindex High capacity formats, mounting 2053 2054The @code{mmount} command is used to mount an MS-DOS disk. It is only 2055available on Linux, as it is only useful if the OS kernel allows to 2056configure the disk geometry. Its syntax is: 2057 2058@code{mmount} @var{msdosdrive} [@var{mountargs}] 2059 2060@code{Mmount} 2061reads the boot sector of an MS-DOS disk, configures the drive geometry, 2062and finally mounts it passing 2063@code{mountargs} to @code{mount. } 2064If no mount arguments are specified, the name of the device is 2065used. If the disk is write protected, it is automatically mounted read 2066only. 2067 2068 2069@node mmove, mpartition, mmount, Commands 2070@section Mmove 2071@pindex mmove 2072@cindex Moving files (mmove) 2073@cindex Renaming files (mmove) 2074 2075The @code{mmove} command is used to moves or renames an existing MS-DOS 2076file or subdirectory. 2077@display 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} 2080@end display 2081@code{Mmove} moves or renames an existing MS-DOS file or 2082subdirectory. Unlike the MS-DOS version of @code{MOVE}, @code{mmove} is 2083able to move subdirectories. Files or directories can only be moved 2084within one filesystem. Data cannot be moved from Dos to Unix or 2085vice-versa. If you omit the drive letter from the target file or 2086directory, the same letter as for the source is assumed. If you omit 2087the drive letter from all parameters, drive a: is assumed by default. 2088 2089@node mpartition, mrd, mmove, Commands 2090@section Mpartition 2091@pindex mpartition 2092@cindex partitions (creating) 2093@cindex Zip disks (partitioning them) 2094@cindex Jaz disks (partitioning them) 2095 2096The @code{mpartition} command is used to create MS-DOS filesystems as 2097partitions. This is intended to be used on non-Linux systems, 2098i.e. systems where fdisk and easy access to Scsi devices are not 2099available. This command only works on drives whose partition variable 2100is set. 2101 2102@display 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}] 2111 2112@end display 2113 2114Mpartition supports the following operations: 2115 2116@table @code 2117@item p 2118Prints a command line to recreate the partition for the drive. Nothing 2119is printed if the partition for the drive is not defined, or an 2120inconsistency has been detected. If verbose (@code{-v}) is also set, 2121prints the current partition table. 2122@item r 2123Removes the partition described by @var{drive}. 2124@item I 2125Initializes the partition table, and removes all partitions. 2126@item c 2127Creates the partition described by @var{drive}. 2128@item a 2129"Activates" the partition, i.e. makes it bootable. Only one partition 2130can be bootable at a time. 2131@item d 2132"Desactivates" the partition, i.e. makes it unbootable. 2133@end table 2134 2135If no operation is given, the current settings are printed. 2136 2137For partition creations, the following options are available: 2138@table @code 2139@item s @var{sectors} 2140The number of sectors per track of the partition (which is also the 2141number of sectors per track for the whole drive). 2142@item h @var{heads} 2143The number of heads of the partition (which is also the number of heads 2144for the whole drive). By default, the geometry information (number of 2145sectors and heads) is figured out from neighbouring partition table 2146entries, or guessed from the size. 2147@item t @var{cylinders} 2148The number of cylinders of the partition (not the number of cylinders of 2149the whole drive. 2150@item b @var{begin} 2151The starting offset of the partition, expressed in sectors. If begin is 2152not given, mpartition lets the partition begin at the start of the disk 2153(partition number 1), or immediately after the end of the previous 2154partition. 2155@item l @var{length} 2156The size (length) of the partition, expressed in sectors. If end is not 2157given, mpartition figures out the size from the number of sectors, heads 2158and cylinders. If these are not given either, it gives the partition 2159the biggest possible size, considering disk size and start of the next 2160partition. 2161@end table 2162 2163The following option is available for all operation which modify the 2164partition table: 2165@table @code 2166@item f 2167Usually, before writing back any changes to the partition, mpartition 2168performs certain consistenct checks, such as checking for overlaps and 2169proper alignment of the partitions. If any of these checks fails, the 2170partition table is not changes. The @code{-f} allows you to override 2171these safeguards. 2172@end table 2173 2174The following options are available for all operations: 2175@table @code 2176@item v 2177Together with @code{-p} prints the partition table as it is now (no 2178change operation), or as it is after it is modified. 2179@item vv 2180If the verbosity flag is given twice, mpartition will print out a 2181hexdump of the partition table when reading it from and writing it to 2182the device. 2183@end table 2184 2185The following option is available for partition table initialization: 2186@table @code 2187@item B @var{bootSector} 2188Reads the template master boot record from file @var{bootSector}. 2189@end table 2190 2191 2192@node mrd, mren, mpartition, Commands 2193@section Mrd 2194@pindex mrd 2195@cindex Removing a directory 2196@cindex Erasing a directory 2197@cindex Deleting a directory 2198@cindex Directory removing 2199@cindex Subdirectory removing 2200 2201The @code{mrd} command is used to remove an MS-DOS subdirectory. Its 2202syntax is: 2203 2204@display 2205@code{mrd} [@code{-v}] @var{msdosdirectory} [ @var{msdosdirectories}@dots{} ] 2206@end display 2207 2208@code{Mrd} removes a directory from an MS-DOS filesystem. An error occurs 2209if the directory does not exist or is not empty. 2210 2211@node mren, mshowfat, mrd, Commands 2212@section Mren 2213@pindex mren 2214@cindex Renaming files (mren) 2215@cindex Moving files (mren) 2216 2217The @code{mren} command is used to rename or move an existing MS-DOS 2218file or subdirectory. Its syntax is: 2219 2220@display 2221@code{mren} [@code{-voOsSrRA}] @var{sourcefile} @var{targetfile} 2222@end display 2223 2224@code{Mren} 2225renames an existing file on an MS-DOS filesystem. 2226 2227In verbose mode, @code{Mren} displays the new filename if the name 2228supplied is invalid. 2229 2230If the first syntax is used (only one sourcefile), and if the target 2231name doesn't contain any slashes or colons, the file (or subdirectory) 2232is 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 2234MS-DOS version of @code{REN}, @code{mren} can be used to rename 2235directories. 2236 2237@node mshowfat, mtoolstest, mren, Commands 2238@section Mshowfat 2239@pindex mshowfat 2240@cindex Clusters of a file 2241@cindex Fat 2242 2243The @code{mshowfat} command is used to display the FAT entries for a 2244file. Syntax: 2245 2246@display 2247@code{$ mshowfat files} 2248@end display 2249 2250@node mtoolstest, mtype, mshowfat, Commands 2251@section Mtoolstest 2252@pindex mtoolstest 2253@cindex Testing configuration file for correctness 2254@cindex Checking configuration file 2255@cindex Verifying configuration file 2256 2257The @code{mtoolstest} command is used to tests the mtools configuration 2258files. To invoke it, just type @code{mtoolstest} without any arguments. 2259@code{Mtoolstest} reads the mtools configuration files, and prints the 2260cumulative configuration to @code{stdout}. The output can be used as a 2261configuration file itself (although you might want to remove redundant 2262clauses). You may use this program to convert old-style configuration 2263files into new style configuration files. 2264 2265@node mtype, mzip, mtoolstest, Commands 2266@section Mtype 2267 2268The @code{mtype} command is used to display contents of an MS-DOS 2269file. Its syntax is: 2270 2271@display 2272@code{mtype} [@code{-ts}] @var{msdosfile} [ @var{msdosfiles}@dots{} ] 2273@end display 2274 2275@code{Mtype} displays the specified MS-DOS file on the screen. 2276 2277In addition to the standard options, @code{Mtype} allows the following 2278command line options: 2279 2280@table @code 2281@item t 2282Text file viewing. @code{Mtype} translates incoming carriage 2283return/line feeds to line feeds. 2284@item s 2285@code{Mtype} strips the high bit from the data. 2286@end table 2287 2288The @code{mcd} command may be used to establish the device and the 2289current working directory (relative to MS-DOS), otherwise the default is 2290@code{A:/}. 2291 2292@code{Mtype} returns 0 on success, 1 on utter failure, or 2 on partial 2293failure. 2294 2295Unlike the MS-DOS version of @code{TYPE}, @code{mtype} allows multiple 2296arguments. 2297 2298 2299@node mzip, , mtype, Commands 2300@section Mzip 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 2305@pindex mzip 2306@cindex ZipTools disk 2307@cindex Tools disk (Zip and Jaz drives) 2308@cindex APlaceForYourStuff 2309@cindex password protected Zip disks 2310 2311The @code{mzip} command is used to issue ZIP disk specific commands on 2312Linux, Solaris or HPUX. Its syntax is: 2313 2314@display 2315@code{mzip} [@code{-epqrwx}] 2316@end display 2317 2318@code{Mzip} allows the following 2319command line options: 2320 2321@table @code 2322@item e 2323Ejects the disk. 2324@item f 2325Force eject even if the disk is mounted (must be given in addition to 2326@code{-e}). 2327@item r 2328Write protect the disk. 2329@item w 2330Remove write protection. 2331@item p 2332Password write protect. 2333@item x 2334Password protect 2335@item u 2336Temporarily unprotect the disk until it is ejected. The disk becomes 2337writable, and reverts back to its old state when ejected. 2338@item q 2339Queries the status 2340@end table 2341 2342To 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 2344unlock the disk. If you have forgotten the password, you can get rid of 2345it by low-level formatting the disk (using your SCSI adaptor's BIOS 2346setup). 2347 2348The ZipTools disk shipped with the drive is also password protected. On 2349Dos or on a Mac, this password is automatically removed once the 2350ZipTools have been installed. From various articles posted to Usenet, I 2351learned 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 2354password, 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 2356this yet when I bought my own Zip drive. Thus I ended up reformatting 2357my tools disk, and hence I haven't had the opportunity to test the 2358password yet. If anybody still has their tools disk with the original 2359password, could you try it out? Thanks in advance}. The tools disk is 2360formatted in a special way so as to be usable both in a PC and in a Mac. 2361On 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 2363taken up by the Mac filesystem. 2364 2365 2366@subsection Bugs 2367 2368This command is a big kludge. A proper implementation would take a 2369rework of significant parts of mtools, but unfortunately I don't have 2370the time for this right now. The main downside of this implementation is 2371that it is inefficient on some architectures (several successive calls 2372to mtools, which defeats mtools' caching). 2373 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 2380 2381To compile mtools, first invoke @code{./configure} before 2382@code{make}. In addition to the standard @code{autoconfigure} flags, 2383there are two architecture specific flags available. 2384 2385@table @code 2386@item ./configure --enable-xdf 2387@itemx ./configure --disable-xdf 2388Enables support for XDF disks. This is on by default. @xref{XDF}, 2389for details. 2390@item ./configure --enable-vold 2391@itemx ./configure --disable-vold 2392Enables support for vold on Solaris. When used in conjunction with vold, 2393mtools should use different device nodes than for direct access. 2394 2395@item ./configure --enable-new-vold 2396@itemx ./configure --disable-new-vold 2397Enables new support for vold on Solaris. This is supposed to work more 2398smoothly than the old support. 2399 2400@item ./configure --enable-floppyd 2401@itemx ./configure --disable-floppyd 2402Enables support for floppyd. By default, floppyd support is enabled as 2403long as the necessary X includes and libraries are available. 2404@end table 2405 2406@node Porting mtools, Command Index, Compiling mtools, Top 2407@chapter Porting mtools to architectures which are not supported yet 2408@cindex Porting 2409@cindex Compiled-in defaults 2410 2411 This chapter is only interesting for those who want to port mtools to 2412an architecture which is not yet supported. For most common systems, 2413default drives are already defined. If you want to add default drives 2414for a still unsupported system, run config.guess, to see which 2415identification autoconf uses for that system. This identification is 2416of the form cpu-vendor-os (for example sparc-sun-sunos). The cpu and 2417the os parts are passed to the compiler as preprocessor flags. 2418 The OS part is passed to the compiler in three forms. 2419@enumerate 2420@item 2421The complete os name, with dots replaced by underscores. sco3.2v2 would 2422yield sco3_2v2 2423@item 2424The base os name. Sco3.2v2 would yield Sco 2425@item 2426The base os name plus its major version. Sco3.2v2 would yield Sco3 2427@end enumerate 2428 2429 All three versions are passed, if they are different. 2430 2431 To define the devices, use the entries for the systems that are already 2432present as templates. In general, they have the following form: 2433 2434@example 2435#if (defined (my_cpu) && defined(my_os)) 2436#define predefined_devices 2437struct device devices[] = @{ 2438 @{ "/dev/first_drive", 'drive_letter', drive_description@}, 2439 @dots{} 2440 @{ "/dev/last_drive", 'drive_letter', drive_description@} 2441@} 2442#define INIT_NOOP 2443#endif 2444@end example 2445 2446 "/dev/first_drive" is the name of the device or image file 2447representing the drive. Drive_letter is a letter ranging from a to z 2448giving access to the drive. Drive_description describes the type of the 2449drive: 2450@table @code 2451@item ED312 2452extra density (2.88M) 3 1/2 disk 2453@item HD312 2454high density 3 1/2 disk 2455@item DD312 2456double density 3 1/2 disk 2457@item HD514 2458high density 5 1/4 disk 2459@item DD514 2460double density 5 1/4 disk 2461@item DDsmall 24628 sector double density 5 1/4 disk 2463@item SS514 2464single sided double density 5 1/4 disk 2465@item SSsmall 2466single sided 8 sector double density 5 1/4 disk 2467@item GENFD 2468generic floppy drive (12 bit FAT) 2469@item GENHD 2470generic hard disk (16 bit FAT) 2471@item GEN 2472generic device (all parameters match) 2473@item ZIPJAZ(flags) 2474generic 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) 2477generic ZIP drive using raw SCSI access. This uses partition 4. 2478@code{Flags} are any special flags to be passed to open. 2479@item REMOTE 2480the remote drive used for floppyd. Unlike the other items, this macro 2481also includes the file name ($DISPLAY) and the drive letter (X) 2482@end table 2483 2484 Entries may be described in more detail: 2485@example 2486 fat_bits,open_flags,cylinders,heads,sectors,DEF_ARG 2487@end example 2488 or, if you need to describe an offset (filesystem doesn't start at 2489beginning of filesystem) 2490@example 2491 fat_bits, open_flags, cylinders, heads, sectors, offset, DEF_ARG0 2492@end example 2493 2494@table @code 2495@item fat_bits 2496is either 12, 16 or 0. 0 means that the device accepts both types of 2497FAT. 2498@item open_flags 2499may include flags such as O_NDELAY, or O_RDONLY, which might be 2500necessary to open the device. 0 means no special flags are needed. 2501@item cylinders,heads,sectors 2502describe the geometry of the disk. If cylinders is 0, the heads and sectors 2503parameters are ignored, and the drive accepts any geometry. 2504@item offset 2505is used if the DOS filesystem doesn't begin at the start of the device 2506or image file. This is mostly useful for Atari Ram disks (which contain 2507their device driver at the beginning of the file) or for DOS emulator 2508images (which may represent a partitioned device. 2509@end table 2510 2511 Definition of defaults in the devices file should only be done if these 2512same devices are found on a large number of hosts of this type. In that 2513case, could you also let me know about your new definitions, so that I 2514can include them into the next release. For purely local file, I 2515recommend that you use the @code{/usr/local/etc/mtools.conf} and 2516@code{~/.mtoolsrc} configuration files. 2517 2518 However, the devices files also allows to supply geometry setting 2519routines. These are necessary if you want to access high capacity 2520disks. 2521 2522 Two routines should be supplied: 2523 2524@enumerate 2525@item 2526Reading the current parameters 2527@example 2528static inline int get_parameters(int fd, struct generic_floppy_struct *floppy) 2529@end example 2530 2531 This probes the current configured geometry, and return it in 2532the structure generic_floppy_struct (which must also be declared). 2533 Fd is an open file descriptor for the device, and buf is an already 2534filled in stat structure, which may be useful. 2535 This routine should return 1 if the probing fails, and 0 otherwise. 2536 2537@item 2538Setting new parameters 2539@example 2540static inline int set_parameters(int fd, struct generic_floppy_struct *floppy) 2541 struct stat *buf) 2542@end example 2543 This configures the geometry contained in floppy on the file descriptor 2544fd. Buf is the result of a stat call (already filled in). This should 2545return 1 if the new geometry cannot be configured, and 0 otherwise. 2546@end enumerate 2547 2548 A certain number of preprocessor macros should also be supplied: 2549 2550@table @code 2551@item TRACKS(floppy) 2552refers to the track field in the floppy structure 2553@item HEADS(floppy) 2554refers to the heads field in the floppy structure 2555@item SECTORS(floppy) 2556refers to the sectors per track field in the floppy structure 2557@item SECTORS_PER_DISK(floppy) 2558refers to the sectors per disk field in the floppy structure (if 2559applicable, otherwise leave undefined) 2560 2561@item BLOCK_MAJOR 2562major number of the floppy device, when viewed as a block device 2563 2564@item CHAR_MAJOR 2565major 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 2567doesn't have raw devices) 2568@end table 2569 2570 For the truly high capacity formats (XDF, 2m, etc), there is no clean 2571and documented interface yet. 2572 2573@comment MANskip 1 2574 2575@node Command Index, Variable Index, Porting mtools, Top 2576@unnumbered Command Index 2577@printindex pg 2578 2579@node Variable Index, Concept Index, Command Index, Top 2580@unnumbered Variable index 2581@printindex vr 2582 2583@node Concept Index, , Variable Index, Top 2584@unnumbered Concept index 2585@printindex cp 2586 2587@comment MANend-skip 1 2588@comment MANend-skip 5 2589@bye 2590