path: root/system/franny/franny.1

.\" Man page generated from reStructuredText.
.
.TH FRANNY 1 "2016-11-09" "1.1.3" "SlackBuilds.org"
.SH NAME
franny \- Atari 8-bit disk image editor
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" RST source for franny(1) man page. Convert with:
.
.\" rst2man.py franny.rst > franny.1
.
.\" rst2man.py comes from the SBo development/docutils package.
.
.SH SYNOPSIS
.sp
franny [\fI\-options\fP] [\fIfile.atr\fP]
.sp
franny\-extract.sh [\fIfile.atr\fP] [\fItarget_directory\fP]
.sp
franny\-insert.sh [\fIfile.atr\fP] [\fIsource_directory\fP]
.SH DESCRIPTION
.sp
Franny is an ATR and XFD disk image editor. It supports AtariDOS II and
SpartaDOS 2 and 3 disk formats. Single, enhanced, double, and custom
formats are supported, though writing to AtariDOS images is limited to
the first 720 sectors.
.sp
There are also two scripts:
.INDENT 0.0
.TP
.B franny\-extract.sh
dump all files from ATR or XFD to specified directory (works like atr2unix)
.TP
.B franny\-insert.sh
insert all files from specified directory to ATR (works like unix2atr)
.UNINDENT
.SH OPTIONS
.sp
All options that take an argument require a space between the option
and its argument, \fIexcept\fP the \-L option, which doesn\(aqt allow a space.
.sp
Generally, uppercase options can be thought of as commands, which edit
the given disk image, and lowercase options can be thought of as options
to the uppercase commands.
.INDENT 0.0
.TP
.B \-A
Add file to image. Paths must be given by using \-i and \-o. Writing past
sector 720 on an AtariDOS image is not supported.
.TP
.B \-C
Create new image. Will not be bootable. Use \-d, \-f, \-m, \-s, \-t, \-T options
to control the image type. Default is 256 bytes per sector, 720 sectors,
SpartaDOS filesystem, ATR image, normal (non\-sio2ide) image type.
.UNINDENT
.INDENT 0.0
.TP
.B \-d [s|d]
Sector size for \-C [single|double]; default: double. Single is 128 bytes/sector, double
is 256.
.TP
.B \-f [a|s]
File system type for \-C [AtariDOS II|Sparta 2.0]; default: Sparta 2.0.
.UNINDENT
.INDENT 0.0
.TP
.B \-F
Format image. Ignores any \-d, \-f, \-m, \-s, \-t, \-T options.
.TP
.B \-h
Show help and exit.
.TP
.BI \-i \ filename
Input filename (source file for \-A and \-S). When using the \-S option,
the filename is treated case\-insensitively, unless it contains a
directory path.
.TP
.B \-I
Image summary. Shows disk label, filesystem type, density, total
sectors, free sectors, image type (standard or sio2ide) and image
media (ATR for ATR images, RAW for XFD images).
.TP
.BI \-l \ format
List format used by \-L. Default is \fB"A F.E S B D T"\fP\&. The format specifiers
are:
.sp
\fBA\fP: Attributes (R for locked files, D for directories, H for hidden files)
.sp
\fBB\fP: Size in bytes
.sp
\fBD\fP: Date. For AtariDOS images, this is always "00\-00\-2000".
.sp
\fBE\fP: Filename extension
.sp
\fBF\fP: Filename (minus the extension)
.sp
\fBS\fP: Size in sectors
.sp
\fBT\fP: Time. For AtariDOS images, this is always "00:00:00".
.sp
Any other character represents itself. The list above is case\-insensitive.
.sp
For example, this gives a more AtariDOS\-like display:
.INDENT 7.0
.INDENT 3.5
franny \-L \-l "fe s" file.atr
.UNINDENT
.UNINDENT
.TP
.BI \-L\fB mask
List directory. Mask is optional; default: *.* (all files). NOTE
that NO SPACE is allowed before the mask, unlike all the other franny
options! Also, the mask is case\-sensitive (e.g. \-L*.SYS, not \-L*.sys).
Files using the DOS 2.5 extra sectors on enhanced density disks will
display, but without the < > around them like DOS 2.5 does.
.UNINDENT
.INDENT 0.0
.TP
.B \-m [a|r]
Media type for \-C (atr|raw); default: atr. Raw images are also known as XFD images.
.UNINDENT
.INDENT 0.0
.TP
.BI \-M \ dirname
Create directory. Only works for SpartaDOS images.
.TP
.BI \-N \ name
Set volume name. Only works for SpartaDOS images.
.TP
.BI \-o \ filename
Output filename (destination file for \-A and \-S). When using the \-A option,
the filename is treated case\-insensitively, unless it contains a directory path.
.UNINDENT
.INDENT 0.0
.TP
.B \-O [a|r]
New media type (BROKEN). This option is apparently supposed to convert
between ATR and XFD, but it doesn\(aqt appear to actually do anything.
.UNINDENT
.INDENT 0.0
.TP
.BI \-R \ dirname
Remove dir. Only works for SpartaDOS images.
.TP
.BI \-s \ sectors
Total sectors for \-C. For standard single or double density, use 720. For 1050 enhanced
density (aka \(aqmedium\(aq), use 1040.
.TP
.B \-S
Save (extract) filename from image. Paths must be given with \-i and \-o.
.UNINDENT
.INDENT 0.0
.TP
.B \-t [s|m|d|f|F]
Image templates for \-C [single|medium|double|full/Full(65535 sectors, 128/256 bytes each)].
Used for \-C option. \(aqs\(aq is equivalent to "\-s 720 \-d s", etc.
.TP
.B \-T [d|s]
change image type (default|sio2ide). Only applies to ATR images, not RAW/XFD.
.UNINDENT
.INDENT 0.0
.TP
.BI \-U \ Filename
Unlink (remove) file. filename is case\-sensitive.
.TP
.B \-v
Show version and exit.
.TP
.BI \-V \ sector
view (dump) sector in hex and ASCII. Output is OK for ATR images but
badly formatted for raw/XFD.
.UNINDENT
.SH EXIT STATUS
.sp
franny returns 0 for success and non\-zero for failure. On failure,
a diagnostic message is printed to standard error.
.SH DIAGNOSTICS
.sp
franny: You can specify only one command.
.INDENT 0.0
.INDENT 3.5
Only one of the \-A \-C \-I \-L \-M \-N \-O \-R \-S \-T \-U \-V options may be given.
.UNINDENT
.UNINDENT
.sp
franny: Cannot open image \(aq[\fIimage\fP]\(aq
.INDENT 0.0
.INDENT 3.5
This means the image is invalid. Either it\(aqs not actually an Atari
disk image, or it\(aqs a boot disk that doesn\(aqt contain a filesystem,
or it\(aqs a truncated image (see NOTES), or you don\(aqt have permission
to read the file.
.UNINDENT
.UNINDENT
.sp
franny: Specified file is not regular file.
.INDENT 0.0
.INDENT 3.5
Means the image file or the file given to the \-i / \-o options doesn\(aqt
exist, or is something other than a regular file or a symlink to a
regular file (e.g. a directory or a device node).
.UNINDENT
.UNINDENT
.sp
franny: Command failed.
.INDENT 0.0
.INDENT 3.5
Catch\-all error message. Can be caused by:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
attempting to access a nonexistant file in the image
.IP \(bu 2
a \(aqdisk full\(aq condition (trying to copy too much data into the image)
.IP \(bu 2
trying to create/delete a subdirectory on an AtariDOS image (currently not supported)
.IP \(bu 2
trying to delete or overwrite a locked file in the image (unfortunately franny has no way to unlock files)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
franny: Cannot change directory.
.INDENT 0.0
.INDENT 3.5
For SpartaDOS images, the given subdirectory doesn\(aqt exist within the image. Remember to use >
as a path separator, and quote any arguments containing > to avoid the shell
interpreting it as a redirection. Also, directory names are case\-sensitive.
.sp
For AtariDOS images, any attempt to copy files to/from a subdirectory
will give this error, as subdirs aren\(aqt supported in AtariDOS images.
.UNINDENT
.UNINDENT
.SH NOTES
.sp
franny is intended for use only with disk images containing
AtariDOS/MyDOS\-compatible or SpartaDOS 2/3 filesystems. Attempting to
edit non\-filesystem\-bearing images (such as boot disks) will fail and/or
have unpredictable results.
.sp
Most emulators support truncated or \(aqshort\(aq disk images, where only the
sectors actually used are stored in the file. franny is unable to operate
properly with truncated images, even if the missing part of the image
contains no filesystem data (sectors containing all zeroes). This type
of image can be turned back into a full image with a dd command such as
.INDENT 0.0
.INDENT 3.5
dd if=truncated.atr of=fixed.atr bs=92176 count=1 conv=sync
.UNINDENT
.UNINDENT
.sp
92176 is for a single\-density image. Replace with 184336 for double density
or 133120 for 1050 enhanced density. For ATR images, this is \fB(number_of_sectors * bytes_per_sector) + 16\fP\&. For XFD (raw) images, don\(aqt add the 16.
.sp
The \-I option will mis\-identify most non\-filesystem boot or data disks as
containing a Sparta 2 filesystem. The other options will (usually?) fail
with \(aqCannot open image\(aq for non\-fs disks (see DIAGNOSTICS).
.sp
Filenames within the image can be entered in lowercase with the \-i or \-o
options, but they\(aqre always converted to uppercase (and truncated to 8.3
format, if they\(aqre not already). If the filename contains a directory
path, only the base filename gets converted, NOT the directory name(s).
Also, this ONLY applies to \-i and \-o. The other options that take Atari
filenames require them to match exactly (e.g. \-U autorun.sys will fail,
use \-U AUTORUN.SYS instead).
.sp
There is no way to delete or overwrite a locked file within the image, as
franny has no Unlock option. There\(aqs also no Lock option.
.sp
Also missing is a Rename option. To rename a file, do something like this:
.INDENT 0.0
.INDENT 3.5
franny \-S \-i sxhand.sys \-o sxhand.sys image.atr
.sp
franny \-U SXHAND.SYS image.atr
.sp
franny \-A \-i sxhand.sys \-o autorun.sys image.atr
.UNINDENT
.UNINDENT
.sp
The above renames SXHAND.SYS to AUTORUN.SYS. Note that the \-U option
required the filename in uppercase.
.sp
The \-O option doesn\(aqt work. You can convert an ATR image to a raw one
with dd:
.INDENT 0.0
.INDENT 3.5
dd if=disk.atr of=disk.xfd bs=16 skip=1
.UNINDENT
.UNINDENT
.SH BUGS
.sp
Some things are not implemented yet. Main disability is write support for
enhanced density in AtariDOS II disk format. Second problem is mydos\(aqs
subdirectories. An extra tool to develop is a gui.
.sp
The \-O (new media type) option doesn\(aqt work.
.sp
The franny\-insert.sh script will fail, if any of the files/directories
contain spaces or other shell metacharacters such as > or |.
.sp
Report bugs to \fI\%ten.egrofecruos.stsil@leved\-8irata\fP\&.
.SH COPYRIGHT
.sp
See the file /usr/doc/franny\-1.1.3/copying for license information.
.SH AUTHORS
.sp
Rafael \(aqBob_er\(aq Ciepiela <\fI\%ten.egrofecruos.sresu@re_bob\fP> \- Coder and designer of the franny program itself.
.sp
This man page written for the SlackBuilds.org project
by B. Watson, and is licensed under the WTFPL.
.\" Generated by docutils manpage writer.
.