You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

344 lines
14 KiB

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