Skip to content

Commit 26d5d13

Browse files
committed
Update README: add info about adfls.
Also, some minor changes/corrections.
1 parent 5974e53 commit 26d5d13

File tree

1 file changed

+32
-27
lines changed

1 file changed

+32
-27
lines changed

README.md

Lines changed: 32 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,14 @@ It should be possible to build on (or cross-compile for) other systems.
2323

2424

2525
## Features
26-
The main purpose of the library is to allow read and write Amiga-formatted
27-
devices and files being byte-level copies of such devices, called disk images
28-
or dumps. In case of classic Amiga systems, such files are most often
26+
The main purpose of the library is to allow reading and writing Amiga-formatted
27+
devices and files being block-level copies of such devices, called disk images
28+
(or dumps). In case of classic Amiga systems, such files are most often
2929
[ADFs](https://en.wikipedia.org/wiki/Amiga_Disk_File) or HDFs ("Hard Disk
3030
Files") containing
3131
[OFS](https://en.wikipedia.org/wiki/Amiga_Old_File_System) or
32-
[FFS](https://en.wikipedia.org/wiki/Amiga_Fast_File_System) (there are also
33-
other Amiga filesystems, for instance
32+
[FFS](https://en.wikipedia.org/wiki/Amiga_Fast_File_System) (however,
33+
there are also other filesystems used on Amigas, for instance
3434
[PFS](https://en.wikipedia.org/wiki/Professional_File_System)).
3535

3636
ADFlib allows accessing the aforementioned devices on 3 levels:
@@ -250,21 +250,25 @@ so ones without an RDSK block and the typical hard disk structure.
250250
Only devices with a single volume on the whole device, so only floppy disks
251251
(ADF) or unpartitioned hard disk file (HDF) devices can be formatted.
252252

253+
### adfls
254+
Show contents of an ADF volume.
255+
253256
### adfinfo
254-
A low-level utility / diagnostic tool, showing metadata about an ADF device,
257+
A low-level utility / diagnostic tool, showing metadata of an ADF device,
255258
volume or a file/directory inside the Amiga filesystem. In particular, it shows
256-
contents of Amiga filesystem metadata blocks, so it can help understand structure
257-
of Amiga filesystems (for anyone curious...).
259+
contents of metadata blocks of Amiga filesystems, so it can help to understand
260+
the internal structure of Amiga filesystems (for anyone curious...).
258261

259262
### adfbitmap
260263
A low-level utility / diagnostic tool for block allocation bitmap of ADF volumes.
261-
It can display the bitmap or rebuild it (in fact, enforce rebuilding it, even if
262-
the volume's flag says that the bitmap is valid).
264+
It can be used to display the allocation bitmap (and its status) or to rebuild it
265+
(in fact, enforce rebuilding it, even if the volume's flag says that the bitmap
266+
is valid).
263267

264268
### adfsalvage
265-
An utility allowing to list deleted entries (files, directories) on a volume
266-
and, if possible, undelete them (in the future possibly also extract them
267-
to local filesystem).
269+
A utility allowing to list deleted entries (files, directories) on a volume
270+
and, if possible, recover (undelete) them (in the future, possibly also extract
271+
them to a local filesystem).
268272

269273
## Credits:
270274
- main design and code : Laurent Clévy
@@ -291,11 +295,11 @@ See INSTALL.
291295
- `src/linux/` : Linux native device driver
292296
- `src/generic/` : Native device driver template ("dummy" device)
293297
- `doc/` : The library developer's documentation, man pages for utilities
294-
- `doc/FAQ/` : The Amiga Filesystem explained
295-
- `examples/` : Utilities: `unadf`, `adfimgcreate`, `adfformat`,
298+
- `doc/FAQ/` : The Amiga Filesystem explained (by Laurent Clévy)
299+
- `examples/` : Utilities: `unadf`, `adfls`, `adfimgcreate`, `adfformat`,
296300
`adfinfo`, `adfbitmap`, `adfsalvage`
297301
- `packaging/` : Packaging configurations (so far - deb only)
298-
- `tests/data/Boot/` : Bootblocks that might by used to put on floppy disks
302+
- `tests/data/Boot/` : Bootblocks that might be put on floppy disks
299303
- `tests/regs` : Regression tests
300304
- `tests/unit` : Unit and functional tests
301305
- `tests/examples` : Tests of command-line utilities
@@ -350,7 +354,7 @@ Until the time of writing this, I haven't encountered any existing disk image
350354
enabled is one of the test floppies for the ADFlib: `testffs.adf`).
351355

352356
While dircache support is implemented in the ADFlib (at least, to certain
353-
extent), so far, there are very few tests of dircache, only on simple dump
357+
extent), so far, there are very few tests of dircache, only on a simple dump
354358
image created for testing (no real cases). Assume that, as such, this feature
355359
is practically **not tested**.
356360
While volumes with dircache can be used rather safely in read-only mode - be
@@ -363,12 +367,12 @@ used. The main goal (so far) is portability, so the functions used are standard
363367
ones (ie. `stdio` for dump files). This, however, can limit device sizes in
364368
some cases.
365369

366-
This can be improved in the future (esp. if signals that it is needed appears),
370+
This can be improved in the future (esp. if signals that it is needed appear),
367371
but it may have to be implemented specifically for each target OS.
368372

369373
#### Dump file size limit
370-
The library uses `stdio` for accessing dump files. This implies use of
371-
`long` type as offset in files. On 32-bit systems this might be a 32-bit
374+
The library uses `stdio` for accessing dump files. This implies the use of
375+
`long` type as offset in files. On 32-bit systems, this might be a 32-bit
372376
(signed) value. This limits the max. size of dump files to 2GiB. 64-bit systems
373377
_should_ support bigger dumps (but this was not tested! If anyone uses bigger
374378
dumps - feedback welcomed).
@@ -409,20 +413,21 @@ See `doc/` (man pages).
409413
### Misc.
410414

411415
#### Using native devices with command-line programs
412-
In the version 0.10.0, the only programs that has enabled support for native
413-
devices are `adfinfo` and `unadf` (both are using the ADF devices in read-only
414-
mode).
416+
In the version 0.10.0, only a few programs have the support for native
417+
devices enabled: `adfls`, `adfinfo` and `unadf` (all are using the ADF devices
418+
in read-only mode).
415419

416420
So far, native devices are supported on 2 operating systems: Windows and Linux.
417421
Native devices are distinguished from regular dump files by special naming
418-
convensions, which, depending on the operating system, are as follows:
422+
conventions, which, depending on the operating system, are as follows:
419423
- on Linux - any file specified as `/dev/....` (so any Linux device file) is
420424
opened as a native device
421425
- on Windows - device name specified as `|Hx`, where '`x`' is the numerical id
422426
of the physical disk (equivalent of Windows pathname: `\\.\PhysicalDiskX`).
423-
is opened as a native device. Note that "`|`" is a special character for system
424-
pipe (sending data to another process), so the device name must be given within
425-
"" (double quotes).
427+
is opened as a native device. Note that "`|`" is a special character normally
428+
interpreted by as system pipe (sending standard output of a program to another
429+
program). Because of this, the device name must be given within "" (double
430+
quotes).
426431

427432

428433
## Contributing

0 commit comments

Comments
 (0)