"Fossies" - the Fresh Open Source Software Archive

Member "libisoburn-1.5.4/README" (30 Jan 2021, 14879 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": 1.5.0_vs_1.5.2.

    1 ------------------------------------------------------------------------------
    2                          http:libburnia-project.org
    3 ------------------------------------------------------------------------------
    4 libisoburn and xorriso. By Vreixo Formoso <metalpain2002@yahoo.es> 
    5                        and Thomas Schmitt <scdbackup@gmx.net>
    6 Integrated sub project of libburnia-project.org.
    7 http://files.libburnia-project.org/releases/libisoburn-1.5.4.tar.gz
    8 Copyright (C) 2006-2009 Vreixo Formoso,
    9 Copyright (C) 2006-2021 Thomas Schmitt.
   10 Provided under GPL version 2 or later.
   11 ------------------------------------------------------------------------------
   12 
   13 libisoburn is a frontend for libraries libburn and libisofs which enables
   14 creation and expansion of ISO-9660 filesystems on all CD/DVD/BD media supported
   15 by libburn. This includes media like DVD+RW, which do not support multi-session
   16 management on media level and even plain disk files or block devices.
   17 
   18 The price for that is thorough specialization on data files in ISO-9660
   19 filesystem images. So libisoburn is not suitable for audio (CD-DA) or any
   20 other CD layout which does not entirely consist of ISO-9660 sessions.
   21 
   22 xorriso is an application of libisoburn, libisofs, and libburn, which reads
   23 commands from program arguments, files, stdin, or readline.
   24 Its features are also available via a C language API of libisoburn.
   25 
   26 Currently they are fully supported on Linux with kernels >= 2.4,
   27 on FreeBSD with ATAPI/CAM support enabled in the kernel, see atapicam(4),
   28 on OpenSolaris (tested with kernel 5.11),
   29 on NetBSD (tested with 6.1.2 and 6.1.3).
   30 On other X/Open compliant systems libburn will only offer POSIX i/o with disk
   31 file objects, but no direct MMC operation on CD/DVD/BD drives.
   32 
   33 By using this software you agree to the disclaimer at the end of this text:
   34 "... without even the implied warranty ..."
   35 
   36 
   37                    Compilation, First Glimpse, Installation
   38 
   39 Dynamic library and compile time header requirements for libisoburn-1.5.4 :
   40 - libburn.so.4  , version libburn-1.5.4 or higher
   41 - libisofs.so.6 , version libisofs-1.5.4 or higher
   42 libisoburn and xorriso will not start with libraries which are older than their
   43 include headers seen at compile time.
   44 
   45 Obtain libisoburn-1.5.4.tar.gz, take it to a directory of your choice
   46 and do:
   47 
   48     tar xzf libisoburn-1.5.4.tar.gz
   49     cd libisoburn-1.5.4
   50 
   51 Within that directory execute:
   52 
   53     ./configure --prefix=/usr
   54     make
   55 
   56 Then become superuser and execute
   57     make install
   58 which will make available libisoburn.so.1 and the program xorriso.
   59 
   60 On GNU/Linux it will try to run program ldconfig with the library installation
   61 directory as only argument. Failure to do so will not abort installation.
   62 One may disable ldconfig by ./configure option --disable-ldconfig-at-install .
   63 
   64 
   65 By use of a version script, the libisoburn.so library exposes no other function
   66 names but those of the API definitions in <libisoburn/libisoburn.h> and
   67 <libisoburn/xorriso.h>.
   68 If -Wl,--version-script=... makes problems with the local compiler, then
   69 disable this encapsulation feature by
   70     ./configure --disable-versioned-libs
   71     make clean ; make
   72 
   73 The ./configure script of libisoburn can check via pkg-config whether suitable
   74 libburn and libisoburn are installed. Regrettably this test failed on several
   75 systems due to local pkg-config problems. So it is disabled by default and may
   76 be enabled by:
   77    ./configure --enable-pkg-check-modules
   78 In this case, ./configure fails if no suitable installations are found.
   79 
   80 
   81                               xorriso
   82 
   83 libisoburn comes with a command line and dialog application named xorriso,
   84 which offers a substantial part of libisoburn features to shell scripts and
   85 users. Its file xorriso/README_gnu_xorriso describes the tarball of the
   86 derived package GNU xorriso as first preference for a statically linked
   87 xorriso installation.
   88 The libisoburn installation described above produces a dynamically linked
   89 xorriso binary depending on libburn.so, libisofs.so, libisoburn.so.
   90 
   91 After installation documentation is available via
   92     man xorriso
   93     man xorrisofs
   94     man xorrecord
   95 
   96 Several alias links point to the xorriso binary:
   97     xorrisofs  starts xorriso with -as mkisofs emulation already enabled
   98     xorrecord  starts xorriso with -as cdrecord emulation already enabled
   99     osirrox    starts with -osirrox image-to-disk copying already enabled
  100 
  101 By default libisoburn will depend on libreadline if the library and its
  102 development header files are present at compile time. If not, then it will
  103 try to depend on libedit and its header file.
  104 Both conditional dependencies can be avoided by running
  105     ./configure --prefix=/usr --disable-libreadline
  106     make clean ; make
  107 Never omit the "make clean" command after switching enabling of libreadline.
  108 Note that depending on libreadline-6 will cause libisoburn's license to
  109 become "GPL version 3 or later".
  110 If you want to explictely allow only the use of libedit, then do
  111     ./configure --prefix=/usr --disable-libreadline --enable-libedit
  112 
  113 Other deliberate dependency reduction options of ./configure are:
  114     --disable-libacl   avoid use of ACL functions like acl_to_text()
  115     --disable-xattr    avoid use of xattr functions like listxattr() on Linux
  116                        or extattr_list_file() on FreeBSD
  117     --disable-zlib     avoid use of zlib functions like compress2()
  118     --disable-libjte   avoid use of libjte for -jigdo command
  119 
  120 xorriso allows to use external processes as file content filters. This is
  121 a potential security risk which may be avoided by ./configure option
  122     --disable-external-filters
  123 By default the filter feature is disabled if effective user id and real
  124 user id differ. This ban can be lifted by
  125     --enable-external-filters-setuid
  126 
  127 In some situations Linux may deliver a better write performance to DVD drives 
  128 if 64 KB rather than 32 KB are transmitted in each write operation.
  129 64k can be made default at configure time by:
  130     --enable-dvd-obs-64k
  131 
  132 
  133           libisoburn, libisofs, and libburn C language API
  134 
  135 For the lower API concepts and calls see
  136     ./libisoburn/libisoburn.h
  137 as well as
  138     /usr/include/libisofs/libisofs.h
  139     /usr/include/libburn/libburn.h
  140 
  141 
  142                       xorriso C language API
  143 
  144 Actually the dynamically linked xorriso binary is only a small start program
  145 for the xorriso API that is implemented inside libisoburn.
  146 There are API calls for command readers and interpreters, and there are
  147 API calls for each single command of xorriso.
  148 
  149 Interested programmers should have a look into the API definition at
  150   xorriso/xorriso.h
  151 and the start program
  152   xorriso/xorriso_main.c
  153 
  154 The header file  xorriso.h  gets installed suitable for
  155   #include <libisoburn/xorriso.h>
  156 
  157 So after installation of a binary libisoburn package you may find it e.g. as
  158   /usr/include/libisoburn/xorriso.h
  159 
  160 
  161              xorriso under control of a (GUI) frontend process
  162 
  163 The dialog mode allows frontend programs to connect via pipes to the standard
  164 input and output of xorriso. Several commands of xorriso help with receiving
  165 and parsing of reply messages.
  166 
  167 As a proof of concept, there is the Tcl/Tk script xorriso-tcltk which can
  168 be launched by this shell command:
  169 
  170     xorriso-tcltk
  171 
  172 Or in the xorriso build directory, without installation of xorriso:
  173 
  174     xorriso/xorriso -launch_frontend frontend/xorriso-tcltk --stdio --
  175 
  176 In the running GUI, click with the rightmost mouse button on any GUI element
  177 to get its particular help text. The "Help" button at the upper right corner
  178 gives a short introduction and instructions for some common use cases.
  179 See also file frontend/README-tcltk.
  180 See its Tcl code for getting an idea how this gets achieved.
  181 
  182 The script is part of the tarball and gets installed by make install. If a
  183 xorriso distro package does not install it, you may get it directly from
  184   https://dev.lovelyhq.com/libburnia/libisoburn/blob/master/frontend/xorriso-tcltk
  185 
  186 Further there is the C program frontend/frontend_pipes_xorriso.c which
  187 forks a xorriso process and shows similar communication gestures as
  188 xorriso-tcltk.
  189 In particular it connects to xorriso via two pipes, sends commands, waits
  190 for all replies of a command, picks info out of the xorriso message sieve,
  191 and parses reply message lines into words.
  192 
  193 The bash script frontend/sh_on_named_pipes.sh forks a xorriso process
  194 connected to two pipes. It then runs a dialog loop, sends commands to xorriso,
  195 and displays the replies.
  196 
  197 The sh script frontend/xorriso_broker.sh is intended to execute xorriso
  198 commands on a permanently running xorriso process.
  199 It gets an id_string by which it looks for named pipes with a running xorriso
  200 process. If no such pipe is found, then it starts a xorriso connected to
  201 newly created pipes.
  202 After this is done, the optionally given xorriso arguments are written into
  203 the stdin pipe from where xorriso will read and execute them. The script will
  204 end but the xorriso process will go on and wait for more commands.
  205 
  206 
  207                        Drives and Disk File Objects 
  208 
  209 The user of libisoburn applications needs operating system dependent
  210 permissions for the CD/DVD/BD drives which shall be used.
  211 On Linux, FreeBSD, NetBSD this means -rw-permissions, even if only reading is
  212 intended. On Solaris one needs privileges "basic,sys_devices" and r-permission,
  213 even if writing is intended.
  214 
  215 A list of rw-accessible drives can be obtained by
  216     xorriso -devices
  217 or by xorriso API call
  218     Xorriso_option_devices()
  219 or by libburn API call
  220     burn_drive_scan()
  221 
  222 A possible source of problems are hald or other automounters. 
  223 If you can spot a process "hald-addon-storage" with the address of
  224 your desired drive, then consider to kill it.
  225 A similar process "udisks-daemon: polling ..." can be seen on newer Linuxes.
  226 
  227 On Debian GNU/Linux 6.0.2 amd64 there is
  228   /lib/udev/rules.d/80-udisks.rules
  229 where one can remove all CD drives ("sr*") from the list of automountable
  230 devices:
  231   KERNEL=="sd*|hd*|mmcblk*|mspblk*", ENV{UDISKS_PRESENTATION_NOPOLICY}="0"
  232   # KERNEL=="sd*|hd*|sr*|mmcblk*|mspblk*", ENV{UDISKS_PRESENTATION_NOPOLICY}="0"
  233 Copying the recognition criterion from
  234   /etc/udev/rules.d/70-persistent-cd.rules
  235 one can prevent automounting a single drive, too. E.g.:
  236   SUBSYSTEM=="block", ENV{ID_CDROM}=="?*", ENV{ID_PATH}=="pci-0000:00:11.0-scsi-2:0:0:0", ENV{UDISKS_PRESENTATION_NOPOLICY}:="1"
  237 
  238 If you cannot get rid of the automounter, try whether it helps to always load
  239 the drive tray manually before starting a write run of xorriso. Wait until the
  240 drive light is off and the mounted media appears.
  241 Then try to unmount the mounted media before a write run.
  242 
  243 
  244 Besides true optical drives, libisoburn can also address disk files as input or
  245 output drives. The addresses of the disk files have to be preceded by "stdio:".
  246 Like:
  247     "stdio:/tmp/pseudo_drive"
  248 
  249 Note: xorriso by default prefixes "stdio:" to addresses outside the /dev tree
  250       if they do not lead to an optical drive device file.
  251 
  252 
  253                          xorriso-dd-target
  254 
  255 libisoburn comes with a script named
  256   xorriso-dd-target/xorriso-dd-target
  257 which uses the util-linux program lsblk to find suitable hard-disk-like
  258 target devices for copying hard-disk bootable ISO images onto them. Such images
  259 are offered by GNU/Linux distributions for installing their system.
  260 
  261 xorriso-dd-target gets installed only if ./configure detects to run on a
  262 GNU/Linux system. It refuses to start on non-Linux kernels or if program lsblk
  263 is not found in /usr/sbin, /sbin, /usr/bin, /bin.
  264 
  265 For introduction, examples, and details see in the build directory
  266   man xorriso-dd-target/xorriso-dd-target.1
  267   info xorriso-dd-target/xorriso-dd-target.info
  268 
  269 
  270                               Testing
  271 
  272 For automated and manual tests of xorriso's functionality see file
  273   releng/README.
  274 
  275 
  276               Result comparison with self produced ISO images
  277 
  278 We are quite sure that libisofs produces accurate representations of the disk
  279 files. This opinion is founded on a lot of test burns and checks by a little
  280 test program which compares files from the mounted image with the orignals
  281 on disk. It uses the normal POSIX filesystem calls, i.e. no libburnia stuff.
  282 
  283 This program is not installed systemwide but stays in the installation
  284 directory of the libisoburn tarball as  test/compare_file . Usually it is
  285 run as -exec payload of a find command. It demands at least three arguments:
  286 The path of the file to compare, the prefix1 to be cut off from path
  287 and the prefix2 which gets prepended afterwards to obtain the path of the
  288 second file to compare.
  289 As further argument there can be -no_ctime which suppresses the comparison
  290 of ctime date stamps.
  291 The exit value is 0 if no difference was detected, non-0 else.
  292 
  293 Example: After
  294    xorriso ... -pathspecs on -add /=/original/dir --
  295    mount /media/dvd
  296    cd test
  297 compare tree /media/dvd with tree /original/dir :
  298    find /original/dir -exec ./compare_file '{}' /original/dir /media/dvd ';' \
  299    | less
  300 and vice versa:
  301    find /media/dvd -exec ./compare_file '{}' /media/dvd /original/dir ';' \
  302    | less
  303 
  304 
  305 ------------------------------------------------------------------------------
  306 
  307     This program is free software; you can redistribute it and/or modify
  308     it under the terms of the GNU General Public License version 2 or later
  309     as published by the Free Software Foundation.
  310 
  311     This program is distributed in the hope that it will be useful,
  312     but WITHOUT ANY WARRANTY; without even the implied warranty of
  313     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  314     GNU General Public License for more details.
  315 
  316     You should have received a copy of the GNU General Public License
  317     along with this program; if not, write to the Free Software
  318     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  319 
  320 ------------------------------------------------------------------------------
  321 Based on and sub project of:
  322 libburnia-project.org
  323 By Mario Danic           <mario.danic@gmail.com>,
  324    Vreixo Formoso        <metalpain2002@yahoo.es>
  325    Thomas Schmitt        <scdbackup@gmx.net>
  326 Copyright (C) 2006-2019 Mario Danic, Vreixo Formoso, Thomas Schmitt.
  327 
  328 We will not raise any legal protest to dynamic linking of our libraries
  329 with applications that are not under GPL, as long as they fulfill
  330 the condition of offering the library source code used, whether
  331 altered or unaltered, under the GPLv2+, along with the application.
  332 Nevertheless, the safest legal position is not to link libburn with
  333 non-GPL compatible programs.
  334 
  335 libburnia-project.org is inspired by and in other components still containing
  336 parts of old
  337 Libburn. By Derek Foreman <derek@signalmarketing.com> and
  338             Ben Jansens <xor@orodu.net>
  339 Copyright (C) 2002-2006  Derek Foreman and Ben Jansens
  340 libisoburn does not stem from their code.
  341 
  342 The libisoburn release contains xorriso-dd-target
  343 Copyright (C) 2019      Nio Wiklund alias sudodus, Thomas Schmitt
  344