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 `/etc/de‐
26 fault/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 re‐
66 jected 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 MTOOLS_LOCK_TIMEOUT
94 How long, in seconds, to wait for a locked device to become
95 free. Defaults to 30.
96 Example: Inserting the following line into your configuration file in‐
98 structs mtools to skip the sanity checks:
99 MTOOLS_SKIP_CHECK=1
101 Global variables may also be set via the environment:
105 export MTOOLS_SKIP_CHECK=1
107 Global string variables may be set to any value:
111 MTOOLS_DATE_STRING
113 The format used for printing dates of files. By default, is dd-
114 mm-yyyy.
115 Per drive flags and variables
117 General information
118 Per drive flags and values may be described in a drive section. A drive
119 section starts with drive "driveletter" :
120 Then follow variable-value pairs and flags.
122 This is a sample drive description:
124 drive a:
126 file="/dev/fd0" use_xdf=1
127 Location information
131 For each drive, you need to describe where its data is physically
132 stored (image file, physical device, partition, offset).
133 file The name of the file or device holding the disk image. This is
135 mandatory. The file name should be enclosed in quotes.
136 partition
138 Tells mtools to treat the drive as a partitioned device, and to
139 use the given partition. Only primary partitions are accessible
140 using this method, and they are numbered from 1 to 4. For logi‐
141 cal partitions, use the more general offset variable. The parti‐
142 tion variable is intended for removable media such as Syquest
143 disks, ZIP drives, and magneto-optical disks. Although tradi‐
144 tional DOS sees Syquest disks and magneto-optical disks as `gi‐
145 ant floppy disks' which are unpartitioned, OS/2 and Windows NT
146 treat them like hard disks, i.e. partitioned devices. The parti‐
147 tion flag is also useful DOSEMU hdimages. It is not recommended
148 for hard disks for which direct access to partitions is avail‐
149 able through mounting.
150 offset
152 Describes where in the file the MS-DOS file system starts. This
153 is useful for logical partitions in DOSEMU hdimages, and for
154 ATARI ram disks. By default, this is zero, meaning that the file
155 system starts right at the beginning of the device or file.
156 Disk Geometry Configuration
158 Geometry information describes the physical characteristics about the
159 disk. Its has three purposes:
160 formatting
162 The geometry information is written into the boot sector of the
163 newly made disk. However, you may also describe the geometry in‐
164 formation on the command line. See section mformat, for details.
165 filtering
167 On some Unixes there are device nodes which only support one
168 physical geometry. For instance, you might need a different node
169 to access a disk as high density or as low density. The geometry
170 is compared to the actual geometry stored on the boot sector to
171 make sure that this device node is able to correctly read the
172 disk. If the geometry doesn't match, this drive entry fails, and
173 the next drive entry bearing the same drive letter is tried. See
174 section multiple descriptions, for more details on supplying
175 several descriptions for one drive letter.
176 If no geometry information is supplied in the configuration
178 file, all disks are accepted. On Linux (and on SPARC) there ex‐
179 ist device nodes with configurable geometry (`/dev/fd0',
180 `/dev/fd1' etc), and thus filtering is not needed (and ignored)
181 for disk drives. (Mtools still does do filtering on plain files
182 (disk images) in Linux: this is mainly intended for test pur‐
183 poses, as I don't have access to a Unix which would actually
184 need filtering).
185 If you do not need filtering, but want still a default geometry
187 for mformatting, you may switch off filtering using the mfor‐
188 mat_only flag.
189 If you want filtering, you should supply the filter flag. If
191 you supply a geometry, you must supply one of both flags.
192 initial geometry
194 On devices that support it (usually floppy devices), the geome‐
195 try information is also used to set the initial geometry. This
196 initial geometry is applied while reading the boot sector, which
197 contains the real geometry. If no geometry information is sup‐
198 plied in the configuration file, or if the mformat_only flag is
199 supplied, no initial configuration is done.
200 On Linux, initial geometry is not really needed, as the config‐
202 urable devices are able to auto-detect the disk type accurately
203 enough (for most common formats) to read the boot sector.
204 Wrong geometry information may lead to very bizarre errors. That's why
206 I strongly recommend that you add the mformat_only flag to your drive
207 description, unless you really need filtering or initial geometry.
208 The following geometry related variables are available:
210 cylinders
212 tracks The number of cylinders. (cylinders is the preferred form,
213 tracks is considered obsolete)
214 heads The number of heads (sides).
216 sectors
218 The number of sectors per track.
219 Example: the following drive section describes a 1.44M drive:
221 drive a:
223 file="/dev/fd0H1440"
224 fat_bits=12
225 cylinders=80 heads=2 sectors=18
226 mformat_only
227 The following shorthand geometry descriptions are available:
231 1.44m high density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80
233 heads=2 sectors=18
234 1.2m high density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=80
236 heads=2 sectors=15
237 720k double density 3 1/2 disk. Equivalent to: fat_bits=12 cylin‐
239 ders=80 heads=2 sectors=9
240 360k double density 5 1/4 disk. Equivalent to: fat_bits=12 cylin‐
242 ders=40 heads=2 sectors=9
243 The shorthand format descriptions may be amended. For example, 360k
245 sectors=8 describes a 320k disk and is equivalent to: fat_bits=12
246 cylinders=40 heads=2 sectors=8
247 Open Flags
249 Moreover, the following flags are available:
250 sync All i/o operations are done synchronously
252 nodelay
254 The device or file is opened with the O_NDELAY flag. This is
255 needed on some non-Linux architectures.
256 exclusive
258 The device or file is opened with the O_EXCL flag. On Linux,
259 this ensures exclusive access to the floppy drive. On most other
260 architectures, and for plain files it has no effect at all.
261 General Purpose Drive Variables
263 The following general purpose drive variables are available. Depending
264 to their type, these variables can be set to a string (precmd) or an
265 integer (all others)
266 fat_bits
268 The number of FAT bits. This may be 12 or 16. This is very
269 rarely needed, as it can almost always be deduced from informa‐
270 tion in the boot sector. On the contrary, describing the number
271 of fat bits may actually be harmful if you get it wrong. You
272 should only use it if mtools gets the auto-detected number of
273 fat bits wrong, or if you want to mformat a disk with a weird
274 number of fat bits.
275 codepage
277 Describes the DOS code page used for short filenames. This is a
278 number between 1 and 999. By default, code page 850 is used. The
279 reason for this is because this code page contains most of the
280 characters that are also available in ISO-Latin-1. You may also
281 specify a global code page for all drives by using the global
282 default_codepage parameter (outside of any drive description).
283 This parameters exists starting at version 4.0.0
284 precmd
286 On some variants of Solaris, it is necessary to call 'volcheck
287 -v' before opening a floppy device, in order for the system to
288 notice that there is indeed a disk in the drive.
289 precmd="volcheck -v" in the drive clause establishes the desired
290 behavior.
291 blocksize
293 This parameter represents a default block size to be always used
294 on this device. All I/O is done with multiples of this block
295 size, independently of the sector size registered in the file
296 system's boot sector. This is useful for character devices
297 whose sector size is not 512, such as for example CD-ROM drives
298 on Solaris.
299 Only the file variable is mandatory. The other parameters may be left
301 out. In that case a default value or an auto-detected value is used.
302 General Purpose Drive Flags
304 A flag can either be set to 1 (enabled) or 0 (disabled). If the value
305 is omitted, it is enabled. For example, scsi is equivalent to scsi=1
306 nolock
308 Instruct mtools to not use locking on this drive. This is
309 needed on systems with buggy locking semantics. However, en‐
310 abling this makes operation less safe in cases where several
311 users may access the same drive at the same time.
312 scsi When set to 1, this option tells mtools to use raw SCSI I/O in‐
314 stead of the standard read/write calls to access the device.
315 Currently, this is supported on HP-UX, Solaris and SunOS. This
316 is needed because on some architectures, such as SunOS or So‐
317 laris, PC media can't be accessed using the read and write sys‐
318 tem calls, because the OS expects them to contain a Sun specific
319 "disk label".
320 As raw SCSI access always uses the whole device, you need to
322 specify the "partition" flag in addition
323 On some architectures, such as Solaris, mtools needs root privi‐
325 leges to be able to use the scsi option. Thus mtools should be
326 installed setuid root on Solaris if you want to access Zip/Jaz
327 drives. Thus, if the scsi flag is given, privileged is automat‐
328 ically implied, unless explicitly disabled by privileged=0
329 Mtools uses its root privileges to open the device, and to issue
331 the actual SCSI I/O calls. Moreover, root privileges are only
332 used for drives described in a system-wide configuration file
333 such as `/etc/mtools.conf', and not for those described in
334 `~/.mtoolsrc' or `$MTOOLSRC'.
335 privileged
337 When set to 1, this instructs mtools to use its setuid and set‐
338 gid privileges for opening the given drive. This option is only
339 valid for drives described in the system-wide configuration
340 files (such as `/etc/mtools.conf', not `~/.mtoolsrc' or `$MTOOL‐
341 SRC'). Obviously, this option is also a no op if mtools is not
342 installed setuid or setgid. This option is implied by 'scsi=1',
343 but again only for drives defined in system-wide configuration
344 files. Privileged may also be set explicitly to 0, in order to
345 tell mtools not to use its privileges for a given drive even if
346 scsi=1 is set.
347 Mtools only needs to be installed setuid if you use the privi‐
349 leged or scsi drive variables. If you do not use these options,
350 mtools works perfectly well even when not installed setuid root.
351 vold
353 Instructs mtools to interpret the device name as a vold identi‐
355 fier rather than as a filename. The vold identifier is trans‐
356 lated into a real filename using the media_findname() and me‐
357 dia_oldaliases() functions of the volmgt library. This flag is
358 only available if you configured mtools with the --enable-new-
359 vold option before compilation.
360 swap
362 Consider the media as a word-swapped Atari disk.
364 use_xdf
366 If this is set to a non-zero value, mtools also tries to access
367 this disk as an XDF disk. XDF is a high capacity format used by
368 OS/2. This is off by default. See section XDF, for more details.
369 mformat_only
371 Tells mtools to use the geometry for this drive only for mfor‐
372 matting and not for filtering.
373 filter
375 Tells mtools to use the geometry for this drive both for mfor‐
376 matting and filtering.
377 remote
379 Tells mtools to connect to floppyd (see section floppyd).
380 Supplying multiple descriptions for a drive
382 It is possible to supply multiple descriptions for a drive. In that
383 case, the descriptions are tried in order until one is found that fits.
384 Descriptions may fail for several reasons:
385 1. because the geometry is not appropriate,
387 2. because there is no disk in the drive,
389 3. or because of other problems.
391 Multiple definitions are useful when using physical devices which are
393 only able to support one single disk geometry. Example:
394 drive a: file="/dev/fd0H1440" 1.44m
396 drive a: file="/dev/fd0H720" 720k
397 This instructs mtools to use /dev/fd0H1440 for 1.44m (high density)
401 disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this
402 feature is not really needed, as the /dev/fd0 device is able to handle
403 any geometry.
404 You may also use multiple drive descriptions to access both of your
406 physical drives through one drive letter:
407 drive z: file="/dev/fd0"
409 drive z: file="/dev/fd1"
410 With this description, mdir z: accesses your first physical drive if it
414 contains a disk. If the first drive doesn't contain a disk, mtools
415 checks the second drive.
416 When using multiple configuration files, drive descriptions in the
418 files parsed last override descriptions for the same drive in earlier
419 files. In order to avoid this, use the drive+ or +drive keywords in‐
420 stead of drive. The first adds a description to the end of the list
421 (i.e. it will be tried last), and the first adds it to the start of the
422 list.
423 Location of configuration files and parsing order
425 The configuration files are parsed in the following order:
426 1. compiled-in defaults
428 2. `/etc/mtools.conf'
430 3. `~/.mtoolsrc'.
432 4. `$MTOOLSRC' (file pointed by the MTOOLSRC environmental vari‐
434 able)
435 Options described in the later files override those described in the
437 earlier files. Drives defined in earlier files persist if they are not
438 overridden in the later files. For instance, drives A and B may be de‐
439 fined in `/etc/mtools.conf' and drives C and D may be defined in
440 `~/.mtoolsrc' However, if `~/.mtoolsrc' also defines drive A, this new
441 description would override the description of drive A in
442 `/etc/mtools.conf' instead of adding to it. If you want to add a new
443 description to a drive already described in an earlier file, you need
444 to use either the +drive or drive+ keyword.
445 Backwards compatibility with old configuration file syntax
447 The syntax described herein is new for version mtools-3.0. The old
448 line-oriented syntax is still supported. Each line beginning with a
449 single letter is considered to be a drive description using the old
450 syntax. Old style and new style drive sections may be mixed within the
451 same configuration file, in order to make upgrading easier. Support for
452 the old syntax will be phased out eventually, and in order to discour‐
453 age its use, I purposefully omit its description here.
454
456 mtools
457MTOOLS 16Apr21 mtools(5)