"Fossies" - the Fresh Open Source Software Archive

Member "libisoburn-1.5.4/xorriso/README_gnu_xorriso" (30 Jan 2021, 23721 Bytes) of package /linux/misc/libisoburn-1.5.4.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README_gnu_xorriso": 1.5.0_vs_1.5.2.

    1 ------------------------------------------------------------------------------
    2       Contribution of libburnia-project.org to the GNU Operating System
    3 ------------------------------------------------------------------------------
    4 GNU xorriso. By Thomas Schmitt <scdbackup@gmx.net>
    5 Derived from and supported by libburnia-project.org, published via:
    6 http://www.gnu.org/software/xorriso/xorriso_eng.html
    7 http://www.gnu.org/software/xorriso/xorriso-1.5.4.tar.gz
    8 Provided under GPL version 3 or later. No warranty.
    9 ------------------------------------------------------------------------------
   12 xorriso is a program which copies file objects from POSIX compliant
   13 filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows
   14 session-wise manipulation of such filesystems. It can load the management
   15 information of existing ISO images and it writes the session results to
   16 optical media or to filesystem objects.
   17 Vice versa xorriso is able to restore file objects from ISO 9660 filesystems.
   19 A special property of xorriso is that it needs neither an external ISO 9660
   20 formatter program nor an external burn program for CD or DVD but rather
   21 incorporates the libraries of libburnia-project.org .
   23 Currently it is fully supported on GNU/Linux with kernels >= 2.4,
   24 on FreeBSD with ATAPI/CAM support enabled in the kernel, see atapicam(4),
   25 on OpenSolaris (tested with kernel 5.11),
   26 on NetBSD (tested with 6.1.2 and 6.1.3).
   27 On other X/Open compliant systems there will only be POSIX i/o with disk
   28 file objects, but no direct MMC operation on CD/DVD/BD drives.
   30 By using this software you agree to the disclaimer at the end of this text:
   31 "... without even the implied warranty ..."
   34                    Compilation, First Glimpse, Installation
   36 The most simple way to get xorriso from source code is the GNU xorriso tarball.
   38 Prerequisites:
   39 The tarball contains everything that is needed except the following system
   40 components:
   41    libc, libpthread
   42    plus on Solaris: libvolmgt
   43    plus on FreeBSD: libiconv, libcam, IDE and SATA drives need atapicam
   44 Optional at compile time are:
   45    libreadline and the readline-dev headers, or libedit and its header,
   46    make dialog mode more convenient.
   47    zlib and zlib-devel allow zisofs compression.
   48    on GNU/Linux: libacl and libacl-devel allow getting and setting ACLs.
   49 If they were present at compile time, then the optional libraries have to
   50 be present at runtime, too.
   52 Obtain xorriso-1.5.4.tar.gz, take it to a directory of your choice and do:
   54     tar xzf xorriso-1.5.4.tar.gz
   55     cd xorriso-1.5.4
   57 Within that directory execute:
   59     ./configure --prefix=/usr
   60     make
   62 This will produce a binary named
   63     ./xorriso/xorriso
   65 If you want xorriso to report a "Build timestamp" with its option -version :
   66     make buildstamped
   68 You may strip the binary to reduce it in size
   69     strip ./xorriso/xorriso
   71 You may copy or move it to a directory where it can be found by the shell,
   72 or you may execute xorriso at the place where it was built,
   73 or you may execute as superuser:
   74     make install
   76 For general concepts, options and usage examples see
   77     info xorriso
   78     info xorrisofs
   79     info xorrecord
   80 or
   81     man 1 xorriso
   82     man 1 xorrisofs 
   83     man 1 xorrecord 
   85 You may get a first glimpse by e.g.
   86     info ./xorriso/xorriso.info
   87     man ./xorriso/xorriso.1
   89 The installation creates several alias links pointing to the xorriso binary:
   90     xorrisofs  starts xorriso with -as mkisofs emulation already enabled
   91     xorrecord  starts xorriso with -as cdrecord emulation already enabled
   92     osirrox    starts with -osirrox image-to-disk copying already enabled
   95 By default xorriso will depend on libreadline if the library and its
   96 development header files are present at compile time. If not, then it will
   97 try to depend on libedit and its header file.
   98 Both conditional dependencies can be avoided by running
   99     ./configure --prefix=/usr --disable-libreadline
  100     make clean ; make
  101 Never omit the "make clean" command after switching enabling of libreadline.
  102 If you want to explicitly allow only the use of libedit, then do
  103     ./configure --prefix=/usr --disable-libreadline --enable-libedit
  105 Other deliberate dependency reduction options of ./configure are:
  106     --disable-libacl   avoid use of ACL functions like acl_to_text()
  107     --disable-xattr    avoid use of xattr functions like listxattr() on Linux
  108                        or extattr_list_file() on FreeBSD
  109     --disable-zlib     avoid use of zlib functions like compress2() 
  110                        this also avoids the use of libjte and option -jigdo.
  112 xorriso brings own system adapters which allow burning optical media on
  113 GNU/Linux, FreeBSD, Solaris, NetBSD.
  114 Alternatively it can use libcdio-0.83 or later for sending commands to
  115 optical drives:
  116     --enable-libcdio
  118 xorriso allows to use external processes as file content filters. This is
  119 a potential security risk which may be avoided by ./configure option
  120     --disable-external-filters
  122 By default the filter feature is disabled if effective user id and real
  123 user id differ. This ban can be lifted by
  124     --enable-external-filters-setuid
  126 Sometimes xorriso will yield better write performance on GNU/Linux if 64 KB are
  127 transmitted in each write operation rather than 32 KB. See option -dvd_obs .
  128 64k can be made default at configure time by:
  129     --enable-dvd-obs-64k
  131 For xorriso -as cdrecord emulation only:
  132 In some situations GNU/Linux may deliver a better write performance to drives
  133 if the track input is read with O_DIRECT (see man 2 open). The included libburn
  134 and the cdrecord emulation of xorriso can be told to use this peculiar read
  135 mode by:
  136     --enable-track-src-odirect
  138 Linux only:
  139 libburn tries to avoid a collision with udev's drive examination by waiting
  140 0.1 seconds before opening the device file for a longer time, after udev
  141 might have been alarmed by drive scanning activities.
  142 The waiting time can be set at ./configure time with microsecond granularity.
  143 E.g. 2 seconds:
  144   CFLAGS="$CFLAGS -DLibburn_udev_wait_useC=2000000"
  145   ./configure ...options...
  146 Waiting can be disabled by zero waiting time:
  147   CFLAGS="$CFLAGS -DLibburn_udev_wait_useC=0"
  148 Alternatively, libburn can try to be nice by opening the device file,
  149 closing it immediately, waiting, and only then opening it for real:
  150   CFLAGS="$CFLAGS -DLibburn_udev_extra_open_cyclE -DLibburn_udev_wait_useC=500000"
  153              xorriso under control of a (GUI) frontend process
  155 The dialog mode allows frontend programs to connect via pipes to the standard
  156 input and output of xorriso. Several commands of xorriso help with receiving
  157 and parsing of reply messages.
  159 As a proof of concept, there is the Tcl/Tk script xorriso-tcltk which can
  160 be launched by this shell command:
  162     xorriso-tcltk
  164 Or in the xorriso build directory, without installation of xorriso:
  166     xorriso/xorriso -launch_frontend frontend/xorriso-tcltk --stdio --
  168 In the running GUI, click with the rightmost mouse button on any GUI element
  169 to get its particular help text. The "Help" button at the upper right corner
  170 gives a short introduction and instructions for some common use cases.
  171 See also file frontend/README-tcltk.
  172 See its Tcl code for getting an idea how this gets achieved.
  174 The script is part of the tarball and gets installed by make install. If a 
  175 xorriso distro package does not install it, you may get it directly from
  176   https://dev.lovelyhq.com/libburnia/libisoburn/blob/master/frontend/xorriso-tcltk
  178 Further there is the C program frontend/frontend_pipes_xorriso.c which
  179 forks a xorriso process and shows the same communication gestures as 
  180 xorriso-tcltk.
  181 In particular it connects to xorriso via two pipes, sends commands, waits 
  182 for all replies of a command, picks info out of the xorriso message sieve, 
  183 and parses reply message lines into words.
  185 The bash script frontend/sh_on_named_pipes.sh forks a xorriso process 
  186 connected to two pipes. It then runs a dialog loop, sends commands to xorriso,
  187 and displays the replies.
  189 The sh script frontend/xorriso_broker.sh is intended to execute xorriso
  190 commands on a permanently running xorriso process.
  191 It gets an id_string by which it looks for named pipes with a running xorriso 
  192 process. If no such pipe is found, then it starts a xorriso connected to 
  193 newly created pipes.
  194 After this is done, the optionally given xorriso arguments are written into
  195 the stdin pipe from where xorriso will read and execute them. The script will
  196 end but the xorriso process will go on and wait for more commands.
  199                        Drives and Disk File Objects 
  201 The user of libisoburn applications needs rw-permission for the CD/DVD/BD
  202 drives which shall be used, even if only reading is intended.
  203 A list of rw-accessible drives can be obtained by
  205     xorriso -devices
  207 CD devices which offer not enough permission are invisible to normal users.
  208 The superuser should be able to see any usable drive and then set the
  209 permissions as needed.
  210 On Linux, FreeBSD, and NetBSD, rw-permissions are needed.
  211 On Solaris, the privilege "sys_devices" and r-permission are needed.
  213 The output of  xorriso -devices  might look like
  215 0  -dev '/dev/sr0' rwrw-- :  'TSSTcorp' 'CDDVDW SH-S203B' 
  216 1  -dev '/dev/hda' rwrw-- :  'HL-DT-ST' 'DVD-ROM GDR8162B' 
  218 On Linux, full and insecure enabling of both for everybody would look like
  219     chmod a+rw /dev/sr0 /dev/hda
  220 This is equivalent to the traditional setup chmod a+x,u+s cdrecord.
  222 On FreeBSD, device permissions are to be set in /etc/devfs.rules.
  223 On Solaris, pfexec privileges may be restricted to "basic,sys_devices".
  224 On NetBSD, rw-permission may be granted by chmod a+rw /dev/rcd?d.
  225 See below "System Dependent Drive Permission Examples".
  227 I strongly discourage to run xorriso with setuid root or via sudo !
  228 It is not checked for the necessary degree of hacker safety.
  229 Better consider to grant the necessary permissions to group "floppy"
  230 and to add users to it.
  233 A possible source of problems are hald or other automounters. 
  234 If you can spot a process "hald-addon-storage" with the address of
  235 your desired drive, then consider to kill it.
  236 A similar process "udisks-daemon: polling ..." can be seen on newer Linuxes.
  238 On Debian GNU/Linux 6.0.2 amd64 there is
  239   /lib/udev/rules.d/80-udisks.rules 
  240 where one can remove all CD drives ("sr*") from the list of automountable 
  241 devices:
  242   KERNEL=="sd*|hd*|mmcblk*|mspblk*", ENV{UDISKS_PRESENTATION_NOPOLICY}="0"
  243   # KERNEL=="sd*|hd*|sr*|mmcblk*|mspblk*", ENV{UDISKS_PRESENTATION_NOPOLICY}="0"
  244 Copying the recognition criterion from
  245   /etc/udev/rules.d/70-persistent-cd.rules
  246 one can prevent automounting a single drive, too:
  247   SUBSYSTEM=="block", ENV{ID_CDROM}=="?*", ENV{ID_PATH}=="pci-0000:00:11.0-scsi-2:0:0:0", ENV{UDISKS_PRESENTATION_NOPOLICY}:="1"
  249 If you cannot get rid of the automounter, try whether it helps to always load 
  250 the drive tray manually before starting a write run of xorriso. Wait until the 
  251 drive light is off and the mounted media appears.
  252 Then try to unmount the mounted media before a write run.
  255 Besides true optical drives, xorriso can also address disk files as input or
  256 output drives. By default paths to files under /dev are accepted only if the
  257 device represents a real optical drive. Other device files may be addressed
  258 by prepending "stdio:" to the path.
  259 Like:
  260     xorriso -dev stdio:/dev/sdb ...more arguments...
  261 This rule may be changed by xorriso option -drive_class.
  262 Prefix "mmc:" causes a path to be accepted only if it is a real optical drive
  263 which is accessible by generic SCSI/MMC commands.
  266                          xorriso-dd-target
  268 GNU xorriso comes with a script named 
  269   xorriso-dd-target/xorriso-dd-target
  270 which uses the util-linux program lsblk to find suitable hard-disk-like
  271 target devices for copying hard-disk bootable ISO images onto them. Such images
  272 are offered by GNU/Linux distributions for installing their system.
  274 xorriso-dd-target gets installed only if ./configure detects to run on a
  275 GNU/Linux system. It refuses to start on non-Linux kernels or if program lsblk
  276 is not found in /usr/sbin, /sbin, /usr/bin, /bin.
  278 For introduction, examples, and details see in the build directory
  279   man xorriso-dd-target/xorriso-dd-target.1
  280   info xorriso-dd-target/xorriso-dd-target.info
  283                               Testing
  285 For automated and manual tests of xorriso's functionality see file
  286   releng/README
  289               Result comparison with self produced ISO images
  291 We are quite sure that libisofs produces accurate representations of the disk
  292 files. This opinion is founded on a lot of test burns and checks by a little
  293 test program which compares files from the mounted image with the orignals
  294 on disk. It uses the normal POSIX filesystem calls, i.e. no libburnia stuff.
  296 This program is not installed systemwide but stays in the installation
  297 directory of the xorriso tarball as  test/compare_file . Usually it is
  298 run as -exec payload of a find command. It demands at least three arguments:
  299 The path of the first file to compare, the prefix1 to be cut off from path
  300 and the prefix2 which gets prepended afterwards to obtain the path of the
  301 second file to compare.
  302 As further argument there can be -no_ctime which suppresses the comparison
  303 of ctime date stamps.
  304 The exit value is 0 if no difference was detected, non-0 else.
  306 Example: After
  307    xorriso ... -pathspecs on -add /=/original/dir -- -commit_eject all
  308    mount /media/dvd
  309    cd test
  310 compare tree /media/dvd with tree /original/dir :
  311    find /original/dir -exec ./compare_file '{}' /original/dir /media/dvd ';' \
  312    | less
  313 and vice versa:
  314    find /media/dvd -exec ./compare_file '{}' /media/dvd /original/dir ';' \
  315    | less
  318                              File Formats
  320                              Sector Maps
  322 Sector maps describe the valid and invalid blocks on a media or a disk copy of
  323 a media. xorriso creates and reads these file with its option -check_media.
  325 The file begins with 32 bytes of cleartext of which the last one is a
  326 newline character. The first 25 say "xorriso sector bitmap v2 ", the
  327 remaining six characters give the size of the info text as decimal number.
  328 This number of bytes follows the first 32 and will not be interpreted
  329 by xorriso. They are rather to inform a human reader about the media type
  330 and its track layout.
  331 After the info text there are two 4 byte signed integers, most significant
  332 byte first. The first one, N, gives the number of bits in the following bitmap
  333 and the second number S gives the number of 2 KiB blocks governed by a single
  334 bit in the map. Then come the bits in form of 8-bit bytes.
  335 Data block M is covered by bit B=M/S in the map, bit number B is stored in
  336 byte B/8 as bit B%8. A valid readable data block has its bit set to 1.
  338                              Checksum Tags
  340 Checksum tags are data blocks inside an ISO 9660 image which do not belong to
  341 any file but rather tell the MD5 of a certain range of data blocks.
  343 The superblock checksum tag is written after the ECMA-119 volume descriptors.
  344 The tree checksum tag is written after the ECMA-119 directory entries.
  345 The session checksum tag is written after all payload including the checksum
  346 array. (Then follows padding.)
  348 The tags are single lines of printable text, padded by 0 bytes. They have
  349 the following format:
  351  Tag_id pos=# range_start=# range_size=# [session_start|next=#] md5=# self=#\n
  353 Parameters md5= and self= are 32 digit hex, the others are decimal numbers.
  355 Tag_id distinguishes the following tag types
  356   "libisofs_rlsb32_checksum_tag_v1"     Relocated 64 kB superblock tag
  357   "libisofs_sb_checksum_tag_v1"         Superblock tag
  358   "libisofs_tree_checksum_tag_v1"       Directory tree tag
  359   "libisofs_checksum_tag_v1"            Session end tag
  361 A relocated superblock may appear at LBA 0 of an image which was produced for
  362 being stored in a disk file or on overwritable media (e.g. DVD+RW, BD-RE).
  363 xorriso records the first session at LBA 32. A follow-up session
  364 begins at the next block address which is divisible by 32 and higher than the
  365 address of the previous session's end tag. Normally no session starts after the
  366 address given by relocated superblock parameter session_start=.
  367 Session oriented media like CD-R[W], DVD-R, DVD+R, BD-R will have no relocated
  368 superblock but rather bear a table-of-content on media level.
  370 A tag is valid if pos= tells its own block address and self= tells its own MD5
  371 up to the last hex digit of md5=. range_start= tells the first block that is
  372 covered by md5=, range_size= tells the number of blocks covered by md5=.
  373 Relocated superblocks tell the block address of their session by session_start=.
  374 Superblock and tree tag tell the block address of the next tag by next=.
  375 The newline character at the end is mandatory.
  378                              libisoburn
  380 xorriso is based on libisofs which does ISO 9660 filesystem aspects and on
  381 libburn which does the input and output aspects. Parts of this foundation
  382 are accessed via libisoburn, which is closely related to xorriso.
  384 libisoburn provides several services:
  385 - Encapsulation of coordination between libisofs and libburn.
  386 - Emulation of ISO 9660 multi-session on overwritable media
  387   or random access files.
  388 - Implementation of the xorriso API.
  390 The sourcecode of all three libraries is included in the GNU xorriso tarball.
  391 It is compiled with xorriso and linked statically.
  392 But you may as well get and install releases of libburn and libisofs, in order
  393 to be able to install a release of libisoburn which produces libisoburn.so.1
  394 and a matching dynamically linked xorriso binary.
  395 This binary is very lean but depends on properly installed libraries of
  396 suitable revision.
  398 Dynamic library and compile time header requirements for libisoburn-1.5.4 :
  399 - libburn.so.4  , version libburn-1.5.4 or higher
  400 - libisofs.so.6 , version libisofs-1.5.4 or higher
  401 libisoburn and xorriso will not start with libraries which are older than their
  402 headers seen at compile time. So compile in the oldest possible installation
  403 setup unless you have reason to enforce a newer bug fix level.
  405 GNU xorriso has less runtime dependencies and can be moved more freely.
  408                   System Dependent Drive Permission Examples
  410 Accessing the optical drives requires privileges which usually are granted
  411 only to the superuser. GNU/Linux, FreeBSD, Solaris, and NetBSD offer quite
  412 different approaches for avoiding the need for unrestricted privileges.
  414 First check whether some friendly system setting already allows you to
  415 access the drives as normal user:
  416   xorriso -devices
  417 Those drives of which you see address and type strings are already usable.
  419 If there remain drives invisible which the superuser can see by the same
  420 command, then the following examples might help:
  422 ---------------
  423 On all systems:
  424 ---------------
  425 Add the authorized users of CD drives to group "floppy" in /etc/group.
  426 If missing: create this group.
  427 Changes to /etc/group often only affect new login sessions. So log out and in
  428 before making the first tests.
  430 -------------
  431 On GNU/Linux:
  432 -------------
  433 Allow rw-access to the drives
  434   chgrp floppy /dev/sr0 /dev/sr1
  435   chmod g+rw   /dev/sr0 /dev/sr1
  436 It might be necessary to perform chgrp and chmod after each reboot or to
  437 edit distro dependent device configuration files for permanent settings.
  439 -----------
  440 On FreeBSD:
  441 -----------
  442 Edit /etc/devfs.rules and make sure to have these lines
  443   [localrules=10]
  444   add path 'acd*' mode 0664 group floppy
  445   add path 'cd*' mode 0664 group floppy
  446   add path 'pass*' mode 0664 group floppy
  447   add path 'xpt*' mode 0664 group floppy
  448   [localrules=5]
  449   add path 'pass*' mode 0664 group floppy
  450   add path 'cd*' mode 0664 group floppy
  451   add path 'xpt*' mode 0664 group floppy
  452   add path 'acd*' mode 0664 group floppy
  454 Edit /etc/rc.conf and add the following line if missing
  455   devfs_system_ruleset="localrules"
  457 This gets into effect by reboot or by command
  458   /etc/rc.d/devfs start
  460 -----------
  461 On Solaris:
  462 -----------
  463 Run xorriso by
  464   pfexec xorriso ...arguments...
  466 The following settings will make pfexec keep original UID and EUID and prevent
  467 most superuser powers. Be aware that you still can manipulate all device files
  468 if you have the file permissions for that.
  469 Full root privileges for xorriso can then be acquired only by command su.
  471 Edit /etc/security/exec_attr and add this line to the other "Media Backup"
  472 lines:
  473   Media Backup:solaris:cmd:::/usr/local/bin/xorriso:privs=basic,sys_devices
  474 Edit /etc/user_attr and add profile "Media Backup" to the user's line:
  475   thomas::::profiles=Media Backup,Primary Administrator;roles=root
  476 See also man privileges, man exec_attr, man user_attr.
  478 Then allow the group r-access to the drives
  479   pfexec chgrp floppy /dev/rdsk/c3t0d0s2 /dev/rdsk/c4t0d0s2
  480   pfexec chmod g+r    /dev/rdsk/c3t0d0s2 /dev/rdsk/c4t0d0s2
  481 The last two commands have to be executed after each boot. I do not know
  482 the relevant device configuration files yet.
  484 ----------
  485 On NetBSD: 
  486 ----------
  487 Allow rw-access to the drives
  488   chgrp floppy /dev/rcd[01]d
  489   chmod g+rw   /dev/rcd[01]d
  491 ------------------------------------------------------------------------------
  493     This program is free software; you can redistribute it and/or modify
  494     it under the terms of the GNU General Public License version 3 or later
  495     as published by the Free Software Foundation.
  497     This program is distributed in the hope that it will be useful,
  498     but WITHOUT ANY WARRANTY; without even the implied warranty of
  500     GNU General Public License for more details.
  502     You should have received a copy of the GNU General Public License
  503     along with this program; if not, write to the Free Software
  504     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  506 ------------------------------------------------------------------------------
  508     GNU xorriso is feature-wise equivalent to the dynamic compilation of
  509     libburnia libraries and libburnia program xorriso.
  510     It restricts itself to a technical form where the legal commitments of the
  511     libburnia project and the legal intentions of FSF match completely.
  513     Libburnia project is committed to provide support for this copy in the same
  514     way as for its own software releases. It is further committed to keep its
  515     own licenses open for obtaining future copies under GPLv2+.
  517 ------------------------------------------------------------------------------
  518 libburnia program xorriso is based on and sub project of:
  519 libburnia-project.org
  520 By Mario Danic           <mario.danic@gmail.com>,  libburn, libisofs
  521    Vreixo Formoso        <metalpain2002@yahoo.es>, libisofs, libisoburn
  522    Thomas Schmitt        <scdbackup@gmx.net>,      libburn, libisofs,
  523                                                    libisoburn, xorriso
  524 Copyright (C) 2006-2021 Mario Danic, Vreixo Formoso, Thomas Schmitt.
  526 libburnia-project.org is inspired by and in libburn still containing parts
  527 of old
  528 Libburn. By Derek Foreman <derek@signalmarketing.com> and
  529             Ben Jansens <xor@orodu.net>
  530 Copyright (C) 2002-2006  Derek Foreman and Ben Jansens
  532 GNU xorriso contains libjte out of source package jigit >= 1.17
  533 Copyright (C) 2000-2007 Free Software Foundation, Inc.
  534               2004-2011 Steve McIntyre
  535               2010-2011 George Danchev, Thomas Schmitt
  537 GNU xorriso contains xorriso-dd-target
  538 Copyright (C) 2019-2021 Nio Wiklund alias sudodus, Thomas Schmitt
  540 ------------------------------------------------------------------------------
  542 This text itself is
  543 Copyright (c) 2007 - 2021 Thomas Schmitt <scdbackup@gmx.net>
  544 and is freely distributable.
  545 It shall only be modified in sync with the technical properties of xorriso.
  546 If you make use of the license to derive modified versions of xorriso
  547 then you are entitled to modify this text under that same license.