1mtools(5) MTOOLS mtools(5)
2
6 mtools.conf - mtools configuration files
7
11 This manual page describes the configuration files for mtools. They are
12 called `/etc/mtools.conf' and `~/.mtoolsrc'. If the environmental vari‐
13 able MTOOLSRC is set, its contents is used as the filename for a third
14 configuration file. These configuration files describe the following
15 items:
16 * Global configuration flags and variables
18 * Per drive flags and variables
20 Location of the configuration files
22 `/etc/mtools.conf' is the system-wide configuration file, and
23 `~/.mtoolsrc' is the user's private configuration file.
24 On some systems, the system-wide configuration file is called
26 `/etc/default/mtools.conf' instead.
27 General configuration file syntax
29 The configuration files is made up of sections. Each section starts
30 with a keyword identifying the section followed by a colon. Then fol‐
31 low variable assignments and flags. Variable assignments take the fol‐
32 lowing form:
33 name=value
34 Flags are lone keywords without an equal sign and value following them.
36 A section either ends at the end of the file or where the next section
37 begins.
38 Lines starting with a hash (#) are comments. Newline characters are
40 equivalent to whitespace (except where ending a comment). The configu‐
41 ration file is case insensitive, except for item enclosed in quotes
42 (such as filenames).
43 Default values
45 For most platforms, mtools contains reasonable compiled-in defaults for
46 physical floppy drives. Thus, you usually don't need to bother with
47 the configuration file, if all you want to do with mtools is to access
48 your floppy drives. On the other hand, the configuration file is needed
49 if you also want to use mtools to access your hard disk partitions and
50 DOSEMU image files.
51 Global variables
53 Global flags may be set to 1 or to 0.
54 The following global flags are recognized:
56 MTOOLS_SKIP_CHECK
58 If this is set to 1, mtools skips most of its sanity checks.
59 This is needed to read some Atari disks which have been made
60 with the earlier ROMs, and which would not be recognized other‐
61 wise.
62 MTOOLS_FAT_COMPATIBILITY
64 If this is set to 1, mtools skips the fat size checks. Some
65 disks have a bigger FAT than they really need to. These are
66 rejected if this option is not set.
67 MTOOLS_LOWER_CASE
69 If this is set to 1, mtools displays all-upper-case short file‐
70 names as lowercase. This has been done to allow a behavior which
71 is consistent with older versions of mtools which didn't know
72 about the case bits.
73 MTOOLS_NO_VFAT
75 If this is set to 1, mtools won't generate VFAT entries for
76 filenames which are mixed-case, but otherwise legal dos file‐
77 names. This is useful when working with DOS versions which
78 can't grok VFAT long names, such as FreeDOS.
79 MTOOLS_DOTTED_DIR
81 In a wide directory, prints the short name with a dot instead of
82 spaces separating the basename and the extension.
83 MTOOLS_NAME_NUMERIC_TAIL
85 If this is set to one (default), generate numeric tails for all
86 long names (~1). If set to zero, only generate numeric tails if
87 otherwise a clash would have happened.
88 MTOOLS_TWENTY_FOUR_HOUR_CLOCK
90 If 1, uses the European notation for times (twenty four hour
91 clock), else uses the UK/US notation (am/pm)
92 Example: Inserting the following line into your configuration file
94 instructs mtools to skip the sanity checks:
95 MTOOLS_SKIP_CHECK=1
97 Global variables may also be set via the environment:
101 export MTOOLS_SKIP_CHECK=1
103 Global string variables may be set to any value:
107 MTOOLS_DATE_STRING
109 The format used for printing dates of files. By default, is dd-
110 mm-yyyy.
111 Per drive flags and variables
113 General information
114 Per drive flags and values may be described in a drive section. A drive
115 section starts with drive "driveletter" :
116 Then follow variable-value pairs and flags.
118 This is a sample drive description:
120 drive a:
122 file="/dev/fd0" use_xdf=1
123 Location information
127 For each drive, you need to describe where its data is physically
128 stored (image file, physical device, partition, offset).
129 file The name of the file or device holding the disk image. This is
131 mandatory. The file name should be enclosed in quotes.
132 partition
134 Tells mtools to treat the drive as a partitioned device, and to
135 use the given partition. Only primary partitions are accessible
136 using this method, and they are numbered from 1 to 4. For logi‐
137 cal partitions, use the more general offset variable. The parti‐
138 tion variable is intended for removable media such as Syquest
139 disks, ZIP drives, and magneto-optical disks. Although tradi‐
140 tional DOS sees Syquest disks and magneto-optical disks as
141 `giant floppy disks' which are unpartitioned, OS/2 and Windows
142 NT treat them like hard disks, i.e. partitioned devices. The
143 partition flag is also useful DOSEMU hdimages. It is not recom‐
144 mended for hard disks for which direct access to partitions is
145 available through mounting.
146 offset
148 Describes where in the file the MS-DOS file system starts. This
149 is useful for logical partitions in DOSEMU hdimages, and for
150 ATARI ram disks. By default, this is zero, meaning that the file
151 system starts right at the beginning of the device or file.
152 Disk Geometry Configuration
154 Geometry information describes the physical characteristics about the
155 disk. Its has three purposes:
156 formatting
158 The geometry information is written into the boot sector of the
159 newly made disk. However, you may also describe the geometry
160 information on the command line. See section mformat, for
161 details.
162 filtering
164 On some Unixes there are device nodes which only support one
165 physical geometry. For instance, you might need a different node
166 to access a disk as high density or as low density. The geometry
167 is compared to the actual geometry stored on the boot sector to
168 make sure that this device node is able to correctly read the
169 disk. If the geometry doesn't match, this drive entry fails, and
170 the next drive entry bearing the same drive letter is tried. See
171 section multiple descriptions, for more details on supplying
172 several descriptions for one drive letter.
173 If no geometry information is supplied in the configuration
175 file, all disks are accepted. On Linux (and on SPARC) there
176 exist device nodes with configurable geometry (`/dev/fd0',
177 `/dev/fd1' etc), and thus filtering is not needed (and ignored)
178 for disk drives. (Mtools still does do filtering on plain files
179 (disk images) in Linux: this is mainly intended for test pur‐
180 poses, as I don't have access to a Unix which would actually
181 need filtering).
182 If you do not need filtering, but want still a default geometry
184 for mformatting, you may switch off filtering using the mfor‐
185 mat_only flag.
186 If you want filtering, you should supply the filter flag. If
188 you supply a geometry, you must supply one of both flags.
189 initial geometry
191 On devices that support it (usually floppy devices), the geome‐
192 try information is also used to set the initial geometry. This
193 initial geometry is applied while reading the boot sector, which
194 contains the real geometry. If no geometry information is sup‐
195 plied in the configuration file, or if the mformat_only flag is
196 supplied, no initial configuration is done.
197 On Linux, initial geometry is not really needed, as the config‐
199 urable devices are able to auto-detect the disk type accurately
200 enough (for most common formats) to read the boot sector.
201 Wrong geometry information may lead to very bizarre errors. That's why
203 I strongly recommend that you add the mformat_only flag to your drive
204 description, unless you really need filtering or initial geometry.
205 The following geometry related variables are available:
207 cylinders
209 tracks The number of cylinders. (cylinders is the preferred form,
210 tracks is considered obsolete)
211 heads The number of heads (sides).
213 sectors
215 The number of sectors per track.
216 Example: the following drive section describes a 1.44M drive:
218 drive a:
220 file="/dev/fd0H1440"
221 fat_bits=12
222 cylinders=80 heads=2 sectors=18
223 mformat_only
224 The following shorthand geometry descriptions are available:
228 1.44m high density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80
230 heads=2 sectors=18
231 1.2m high density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=80
233 heads=2 sectors=15
234 720k double density 3 1/2 disk. Equivalent to: fat_bits=12 cylin‐
236 ders=80 heads=2 sectors=9
237 360k double density 5 1/4 disk. Equivalent to: fat_bits=12 cylin‐
239 ders=40 heads=2 sectors=9
240 The shorthand format descriptions may be amended. For example, 360k
242 sectors=8 describes a 320k disk and is equivalent to: fat_bits=12
243 cylinders=40 heads=2 sectors=8
244 Open Flags
246 Moreover, the following flags are available:
247 sync All i/o operations are done synchronously
249 nodelay
251 The device or file is opened with the O_NDELAY flag. This is
252 needed on some non-Linux architectures.
253 exclusive
255 The device or file is opened with the O_EXCL flag. On Linux,
256 this ensures exclusive access to the floppy drive. On most other
257 architectures, and for plain files it has no effect at all.
258 General Purpose Drive Variables
260 The following general purpose drive variables are available. Depending
261 to their type, these variables can be set to a string (precmd) or an
262 integer (all others)
263 fat_bits
265 The number of FAT bits. This may be 12 or 16. This is very
266 rarely needed, as it can almost always be deduced from informa‐
267 tion in the boot sector. On the contrary, describing the number
268 of fat bits may actually be harmful if you get it wrong. You
269 should only use it if mtools gets the auto-detected number of
270 fat bits wrong, or if you want to mformat a disk with a weird
271 number of fat bits.
272 codepage
274 Describes the DOS code page used for short filenames. This is a
275 number between 1 and 999. By default, code page 850 is used. The
276 reason for this is because this code page contains most of the
277 characters that are also available in ISO-Latin-1. You may also
278 specify a global code page for all drives by using the global
279 default_codepage parameter (outside of any drive description).
280 This parameters exists starting at version 4.0.0
281 precmd
283 On some variants of Solaris, it is necessary to call 'volcheck
284 -v' before opening a floppy device, in order for the system to
285 notice that there is indeed a disk in the drive.
286 precmd="volcheck -v" in the drive clause establishes the desired
287 behavior.
288 blocksize
290 This parameter represents a default block size to be always used
291 on this device. All I/O is done with multiples of this block
292 size, independently of the sector size registered in the file
293 system's boot sector. This is useful for character devices
294 whose sector size is not 512, such as for example CD-ROM drives
295 on Solaris.
296 Only the file variable is mandatory. The other parameters may be left
298 out. In that case a default value or an auto-detected value is used.
299 General Purpose Drive Flags
301 A flag can either be set to 1 (enabled) or 0 (disabled). If the value
302 is omitted, it is enabled. For example, scsi is equivalent to scsi=1
303 nolock
305 Instruct mtools to not use locking on this drive. This is
306 needed on systems with buggy locking semantics. However,
307 enabling this makes operation less safe in cases where several
308 users may access the same drive at the same time.
309 scsi When set to 1, this option tells mtools to use raw SCSI I/O
311 instead of the standard read/write calls to access the device.
312 Currently, this is supported on HP-UX, Solaris and SunOS. This
313 is needed because on some architectures, such as SunOS or
314 Solaris, PC media can't be accessed using the read and write
315 system calls, because the OS expects them to contain a Sun spe‐
316 cific "disk label".
317 As raw SCSI access always uses the whole device, you need to
319 specify the "partition" flag in addition
320 On some architectures, such as Solaris, mtools needs root privi‐
322 leges to be able to use the scsi option. Thus mtools should be
323 installed setuid root on Solaris if you want to access Zip/Jaz
324 drives. Thus, if the scsi flag is given, privileged is automat‐
325 ically implied, unless explicitly disabled by privileged=0
326 Mtools uses its root privileges to open the device, and to issue
328 the actual SCSI I/O calls. Moreover, root privileges are only
329 used for drives described in a system-wide configuration file
330 such as `/etc/mtools.conf', and not for those described in
331 `~/.mtoolsrc' or `$MTOOLSRC'.
332 privileged
334 When set to 1, this instructs mtools to use its setuid and set‐
335 gid privileges for opening the given drive. This option is only
336 valid for drives described in the system-wide configuration
337 files (such as `/etc/mtools.conf', not `~/.mtoolsrc' or `$MTOOL‐
338 SRC'). Obviously, this option is also a no op if mtools is not
339 installed setuid or setgid. This option is implied by 'scsi=1',
340 but again only for drives defined in system-wide configuration
341 files. Privileged may also be set explicitly to 0, in order to
342 tell mtools not to use its privileges for a given drive even if
343 scsi=1 is set.
344 Mtools only needs to be installed setuid if you use the privi‐
346 leged or scsi drive variables. If you do not use these options,
347 mtools works perfectly well even when not installed setuid root.
348 vold
350 Instructs mtools to interpret the device name as a vold identi‐
352 fier rather than as a filename. The vold identifier is trans‐
353 lated into a real filename using the media_findname() and
354 media_oldaliases() functions of the volmgt library. This flag
355 is only available if you configured mtools with the --enable-
356 new-vold option before compilation.
357 swap
359 Consider the media as a word-swapped Atari disk.
361 use_xdf
363 If this is set to a non-zero value, mtools also tries to access
364 this disk as an XDF disk. XDF is a high capacity format used by
365 OS/2. This is off by default. See section XDF, for more details.
366 mformat_only
368 Tells mtools to use the geometry for this drive only for mfor‐
369 matting and not for filtering.
370 filter
372 Tells mtools to use the geometry for this drive both for mfor‐
373 matting and filtering.
374 remote
376 Tells mtools to connect to floppyd (see section floppyd).
377 Supplying multiple descriptions for a drive
379 It is possible to supply multiple descriptions for a drive. In that
380 case, the descriptions are tried in order until one is found that fits.
381 Descriptions may fail for several reasons:
382 1. because the geometry is not appropriate,
384 2. because there is no disk in the drive,
386 3. or because of other problems.
388 Multiple definitions are useful when using physical devices which are
390 only able to support one single disk geometry. Example:
391 drive a: file="/dev/fd0H1440" 1.44m
393 drive a: file="/dev/fd0H720" 720k
394 This instructs mtools to use /dev/fd0H1440 for 1.44m (high density)
398 disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this
399 feature is not really needed, as the /dev/fd0 device is able to handle
400 any geometry.
401 You may also use multiple drive descriptions to access both of your
403 physical drives through one drive letter:
404 drive z: file="/dev/fd0"
406 drive z: file="/dev/fd1"
407 With this description, mdir z: accesses your first physical drive if it
411 contains a disk. If the first drive doesn't contain a disk, mtools
412 checks the second drive.
413 When using multiple configuration files, drive descriptions in the
415 files parsed last override descriptions for the same drive in earlier
416 files. In order to avoid this, use the drive+ or +drive keywords
417 instead of drive. The first adds a description to the end of the list
418 (i.e. it will be tried last), and the first adds it to the start of the
419 list.
420 Location of configuration files and parsing order
422 The configuration files are parsed in the following order:
423 1. compiled-in defaults
425 2. `/etc/mtools.conf'
427 3. `~/.mtoolsrc'.
429 4. `$MTOOLSRC' (file pointed by the MTOOLSRC environmental vari‐
431 able)
432 Options described in the later files override those described in the
434 earlier files. Drives defined in earlier files persist if they are not
435 overridden in the later files. For instance, drives A and B may be
436 defined in `/etc/mtools.conf' and drives C and D may be defined in
437 `~/.mtoolsrc' However, if `~/.mtoolsrc' also defines drive A, this new
438 description would override the description of drive A in
439 `/etc/mtools.conf' instead of adding to it. If you want to add a new
440 description to a drive already described in an earlier file, you need
441 to use either the +drive or drive+ keyword.
442 Backwards compatibility with old configuration file syntax
444 The syntax described herein is new for version mtools-3.0. The old
445 line-oriented syntax is still supported. Each line beginning with a
446 single letter is considered to be a drive description using the old
447 syntax. Old style and new style drive sections may be mixed within the
448 same configuration file, in order to make upgrading easier. Support for
449 the old syntax will be phased out eventually, and in order to discour‐
450 age its use, I purposefully omit its description here.
451
453 mtools
454MTOOLS 09Jan13 mtools(5)