Documentation


Contents

  1. Description
  2. Requirements
  3. Installation
  4. Usage
    1. Path Length Calculation
    2. Testing for allowed characters
    3. Program messages
  5. Known bugs
  6. Package content
  7. Legal information
  8. Contacts

Description

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:

Requirements

A Python interpreter ver. 2.2.1 or higher. See www.python.org for latest version.

Installation

Unpack archive into desired directory. Add this directory to your PATH environment variable.

Usage

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: 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.

Path length calculation

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.

Testing for allowed characters

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.

Program messages

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.

Known bugs

Calculation of total size is not 100% accurate.

Package content

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

Legal information

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

Contacts

Author:
Róbert Čerňanský
E-mail:
openhs@users.sourceforge.net
Project homepage:
http://canburn.sourceforge.net




canburn homepage ver. 1.0.3, Copyright © 2001 - 2008 Róbert Čerňanský

Get canburn at SourceForge.net. Fast, secure and Free Open Source software downloads Support This Project Made with GNU Emacs Graphics by GIMP

Valid HTML 4.01! Valid CSS!