Documentation
Canburn is console-oriented program for testing filesystem tree to match
restrictions of chosen CD filesystem. It can be used to check files before
burning them to CD. This document describes version 2.01 (build 38) of
canburn.
Features:
- support for:
- ISO 9660 interchange level 1
- ISO 9660 interchange level 2 or 3
- Joliet extension of ISO 9660 filesystem
- raw filesystem (useful to do any of available tests)
- testing:
- length of path
- length of file and directory names
- length of file and directory names without extension
- length of file name extension
- extension occurrence in directory names
- depth level
- illegal characters
- amount size of data
- options for change most values of tested parameters
- follow or ignore links option
A Python interpreter ver. 2.2.1 or higher. See
www.python.org for latest
version.
Unpack archive into desired directory. Add this directory to your
PATH environment variable.
canburn[.py] [<options>] [<path> [<path> [...]]]
Options:
-
--allowed-chars=<chars>
- String containing characters that are allowed in file and directory
names (default is
"abcdefghijklmnopqrstuvwxyz0123456789_"). This option has no
effect for Joliet (-J). See
also
--not-allowed-chars
and --no-chars-test.
- -h, --help
- Displays help information.
- -i, --ignore-sys-err
- Deprecated. This option has no effect now. It is keep only for backward
compatibility.
- -I, --iso9660-level1
- Select ISO9660 (interchange level 1) filesystem. See also
--iso9660-level2 and
--joliet.
- -J, --joliet
- Select Joliet extension of ISO9660 filesystem. This is the default. See
also --iso9660-level1
and --iso9660-level2.
- -K, --iso9660-level2
- Select ISO9660 (interchange level 2 or 3) filesystem. See also
--iso9660-level1 and
--joliet.
- -l, --follow-links
- Symbolic links will be followed. If this option is not present,
symbolic links will be ignored.
- -L, --license
- Display license information.
- --max-depth=<depthlen>
- Maximum depth level of directory structure (default is 8). This option
has no effect for Joliet
(-J). See also
--no-depth-test.
- --max-ext-len=<extlen>
- Maximum length of file name extension (default is 8). This option has
effect only for ISO 9660 level 1
(-I). See also
--max-root-len and
--no-extlen-test.
- --max-name-len=<namelen>
- Maximum length of file or directory name (default value is 30 for ISO
9660 level 2 (-K) and
64 for Joliet (-J)). This
option has no effect with ISO 9660 level 1 filesystem
(-I). See also
--no-namelen-test.
- --max-path-len=<pathlen>
- Maximum length of path (see section Path length
calculation) (default value is 255 for ISO 9660
(-I,
-K) and 240 for
Joliet (-J)). See also
--no-path-test.
- --max-root-len=<rootlen>
- Maximum length of file name without extension (default is 8). This
option has effect only for ISO 9660 level 1
(-I). See also
--max-ext-len and
--no-rootlen-test.
- --no-chars-test
- Do not test valid/invalid characters in file or directory names. See
also --allowed-chars
and
--not-allowed-chars.
- --no-depth-test
- Do not perform test of directory depth level. This option has no effect
for Joliet (-J). See also
--max-depth.
- --no-dirext-test
- Do not perform test of extension occurrence in directory names. This
option has no effect for Joliet
(-J).
- --no-extlen-test
- Do not perform file name extension length test. This option has effect
only for ISO 9660 level 1
(-I). See also
--max-ext-len.
- --no-namelen-test
- Do not perform file or directory name length test. This option has no
effect with ISO 9660 level 1 filesystem
(-I). See also
--max-name-len.
- --no-path-test
- Do not perform test of path length. See also
--max-path-len.
- --no-rootlen-test
- Do not perform file name without extension length test. This option has
effect only for ISO 9660 level 1
(-I). See
also --max-root-len.
- --no-size-test
- Do not perform total data size test. See also
--cd-size and
--sector-size.
-
--not-allowed-chars=<chars>
- String containing characters that are not allowed in file and directory
names (default is [characters from \x00 to \x1f] and
"*/:;?\\"). This option has no effect for ISO 9660
(-I,
-K). See also
--allowed-chars and
--no-chars-test.
- -q, --quiet
- Canburn will print only final results.
- -W, --raw
- Select raw filesystem. This is not any real CD filesystem but it can
realize all tests. For this filesystem must also be specified these
options: one of
--allowed-chars,
--not-allowed-chars
and --max-depth,
--max-ext-len,
--max-name-len,
--max-path-len,
--max-root-len. Except
if appropriate --no-* option is
specified. For example:
--max-depth needn't to be
present if
--no-depth-test is
present.
- -s, --cd-size=<cdsize>
- Total size of CD in bytes (default value is 737280000 (700MiB)). There
are also predefined sizes:
- 180M, 21min - for 193536000 bytes (94500 sectors)
- 550M, 63min - for 580608000 bytes (283500 sectors)
- 650M, 74min - for 681984000 bytes (333000 sectors)
- 700M, 80min - for 737280000 bytes (360000 sectors) (this is the
default)
- 790M, 90min - for 829440000 bytes (405000 sectors)
- 870M, 99min - for 912384000 bytes (445500 sectors)
So you can specify size with any of these predefined values (for ex.
-s 790M or
--cd-size=99min). See also
--no-size-test.
- --sector-size=<secsize>
- Size of sectors on CD in bytes (default value is 2048). See also
--no-size-test.
- -v, --verbose
- Canburn will print more details during processing files.
- -V, --version
- Display version info.
<path> is a path to directory containing
files to check. This directory, is taken as a base (root) and path length
is calculated relative to this directory (so files which are in directory
that <path> point on, have no parent
directory (they are in root)).
Example:
Say that You have a data prepared for burning located at directory
/home/me/filestocd. Then you test this files
with following command:
canburn /home/me/filestocd
Or you can go into that directory with
cd /home/me/filestocd
and then type simply
canburn
Under Windows type canburn.py (or
python canburn.py) instead of
canburn.
For ISO 9660 (any level of interchange) and raw filesystem is length of
path calculated as sum of length of all directory names in path and length
of file name (if any) and number of relevant directories. For Joliet
filesystem is length of path calculated as sum of 2 * length of all
directory names in path and 2 * length of file name (if any) and number of
relevant directories.
It is little difference between testing for allowed characters in ISO9660
filesystem and in Joliet or raw filesystems. In ISO9660 filesystem the
name is first split to root and extension and then tested for allowed
characters. So '.' which separate root and extension is not tested as a
part of name. In Joliet and raw filesystems is tested whole name as
is. So '.' is normal part of name as any other character.
It is three kinds of messages.
Instant messages appear during processing files. These messages are not
printed when --quiet option is
present.
Report messages are printed after processing all files. It gives a brief
summary of testing.
Error and warning messages are printed when some unexpected error
occurs.
Instant messages:
-
*** Path is too long *** - <path>
- Length of <path> is longer than allowed length for selected
filesystem or longer than length specified in option
--max-path-len if it is
present. See section Path length calculation.
- *** File or directory name is too
long *** - <path>/<name>
- File or directory name is longer than allowed length for selected
filesystem or longer than length specified in option
--max-name-len if it is
present.
- *** File or directory is nested too
deep *** - <path>/<name>
- File or directory <name> is nested deeper than allowed depth
level for selected filesystem or deeper than depth level specified on
option --max-depth if it is
present.
- *** File or directory contains
illegal characters *** - <path>/<name>
- File or directory name contains characters that are not allowed for
selected filesystem or contains other characters than characters
specified in
--allowed-chars option
if it is present or contains any of characters specified in option
--not-allowed-chars
if it is present. Understand? ;-)
- *** Directory cannot contain
extension *** - <path>/<name>
- Directory name <name> contains extension. This is not allowed for
ISO 9660 filesystem.
- *** Name (without extension) is too
long *** - <path>/<name>
- File or directory name (without extension) is longer than allowed
length for selected filesystem or longer than length specified in
option --max-root-len if
it is present.
- *** Extension is too long *** -
<path>/<name>
- Extension of file or directory name is longer than allowed length for
selected filesystem or longer than length specified in option
--max-ext-len if it is
present.
- *** Symbolic link *** -
<name>
- File or directory <name> is symbolic link.
Report messages:
- Total size is too big (max. ...).
- Size of all files is bigger than given size of CD (see option
--cd-size).
- Some paths are too long (max. ...).
- One or more paths are too long to burn on CD (see
*** Path is too long ***
message).
- Some file or directory names are too long (max. ...).
- One or more files or directories have a too long name to burn on CD
(see *** File or directory name
is too long *** message).
- Some names contains illegal characters.
- One or more file or directory names contains characters that are not
allowed (see *** File or
directory contains illegal characters *** message).
- Some paths are too deep (max. ...).
- One or more paths are nested too deep (see
*** File or directory is nested
too deep *** message).
- Some names (without extension) are too long (max. ...).
- One or more file or directory name roots are too long (see
*** Name (without extension)
is too long *** message).
- Some extensions are too long (max. ...).
- One or more file or directory name extensions are too long (see
*** Extension is too long
***).
- Some directories contains extensions.
- One or more directories contains name extensions (see
*** Directory cannot contain
extension ***).
- Warning! Some files or directories cannot be accessed.
- file error occurred
during processing files.
- Warning! There are symbolic links and they were
followed|ignored.
- Checked file tree contain symbolic links. They were followed or ignored
which depends on -l
option (see *** Symbolic link
***).
Error messages:
- file error `<name>':
<system error message>
- An error occurred when accessing file <name>.
- invalid option
- You specify an option that is unknown for canburn. See section
Usage or type
canburn -h for list of all options.
- wrong argument
- Some argument of an option is bad. For example if you give a
non-numeric argument when a number is expected.
- more options needed
- Some more options need to be specified. See section
Usage or type
canburn -h for help.
- Warning: option <opt> has no effect for chosen CD
filesystem
- An irrelevant option for chosen filesystem is present.
At the end you also get a final result that tells you whether you can or
not burn tested files to CD.
Calculation of total size is not 100% accurate.
- doc
- - documentation directory
- canburn
- - file for starting canburn
- canburn.py
- - file for starting canburn (for Windows)
- CanburnMain.py
- - main file
- CDFilesystem.py
- - module for CD filesystems
- ChangeLog
- - history of changes
- COPYING
- - GNU General Public License
- NEWS
- - versions descriptions
- README
- - short program documentation
- TODO
- - list of future features
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU
General Public License version 2 as published by the Free Software
Foundation.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA
- Author:
- Róbert Čerňanský
- E-mail:
- openhs@users.sourceforge.net
- Project homepage:
- http://canburn.sourceforge.net