\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorriso-dd-target.info
@settitle GNU xorriso-dd-target 1.5.3
@c %**end of header
@c
@c man-ignore-lines begin
@dircategory Archiving
@direntry
* Xorriso-dd-target: (xorriso-dd-target). Device evaluator and disk image copier for GNU/Linux
@end direntry
@c man-ignore-lines end
@c
@c Notes about embedded man page:
@c This texinfo code contains the necessary info to produce a man page
@c which resembles much the version of xorriso.1 from which this code
@c was originally derived in march 2010.
@c One can produce the man page by applying the following rules:
@c   The first line gets discarded.
@c   Line start "@c man " will become "", the remainder is put out unaltered.
@c   Lines "@*" will be converted to ".br"
@c   "@c man-ignore-lines N"  will discard N following lines.
@c   "@c man-ignore-lines begin" discards all following lines
@c   up to "@c man-ignore-lines end".
@c   Line blocks of "@menu" "@end menu" will be discarded.
@c   "@item word words" becomes "\fBword\fR words".
@c   @b{...}, @command{...}, @dfn{...}, @emph{...}, @strong{...}
@c     get mapped to \fB...\fR .
@c   @abbr{...}, @code{...}, @file{...}, @i{...}, @option{...}, @r{...},
@c     @ref{...}, @samp{...},@var{...}, get mapped to ... .
@c   @ref{...}, @xref{...} get mapped to empty text.
@c   @email{...} gets mapped to <...> .
@c   Mapped {...} content is subject to the rules except {...} mapping.
@c   @minus{} will become "-".
@c   @@ , @{, @} will get stripped of their first @.
@c   Other lines which begin by "@" will be discarded.
@c   In lines not stemming from "@c man", "\" becomes "\\"
@c   "-" which are not preceded by an uneven number of "\" will get
@c     prepended one "\".
@c
@c
@c man .\"                                      Hey, EMACS: -*- nroff -*-
@c man .\"
@c man .\" IMPORTANT NOTE:
@c man .\"
@c man .\"      The original of this file is kept in xorriso/xorriso-dd-target.texi
@c man .\"      This here was generated by program xorriso/make_xorriso_1
@c man .\"
@c man .\"
@c man .\" First parameter, NAME, should be all caps
@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
@c man .\" other parameters are allowed: see man(7), man(1)
@c man .TH XORRISO-DD-TARGET 1 "Version 1.5.3, Dec 2, 2019"
@c man .\" Please adjust this date whenever revising the manpage.
@c man .\"
@c man .\" Some roff macros, for reference:
@c man .\" .nh        disable hyphenation
@c man .\" .hy        enable hyphenation
@c man .\" .ad l      left justify
@c man .\" .ad b      justify to both left and right margins
@c man .\" .nf        disable filling
@c man .\" .fi        enable filling
@c man .\" .br        insert line break
@c man .\" .sp <n>    insert n+1 empty lines
@c man .\" for manpage-specific macros, see man(7)
@c man .nh
@c man-ignore-lines begin
@copying
xorriso-dd-target -  Device evaluator and disk image copier for GNU/Linux

Copyright @copyright{} 2019 Thomas Schmitt

@quotation
Permission is granted to distribute this text freely.
@end quotation
@end copying
@c man-ignore-lines end
@titlepage
@title Manual of GNU xorriso companion xorriso-dd-target 1.5.3
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top xorriso-dd-target 1.5.3
@c man-ignore-lines 1

@c man .SH NAME
xorriso-dd-target -  Device evaluator and disk image copier for GNU/Linux
@end ifnottex
@menu
* Overview::            Overview
* Options::             Options
* Examples::            Examples
* Files::               Files
* Seealso::             See also
* Bugreport::           Reporting bugs
* Legal::               Author, Copyright, Credits
* CommandIdx::          Alphabetic Option List
* ConceptIdx::          Alphabetic List of Concepts and Objects
@end menu
@node Overview, Options, Top, Top
@chapter Overview
@c man .SH SYNOPSIS
@c man .B xorriso-dd-target
@c man [ options ] [ device_names ]
@c man .br
@c man .SH DESCRIPTION
@c man .PP
@command{xorriso-dd-target}
evaluates block devices of the Linux kernel whether they are suitable targets
for a disk image file and optionally copies the image file to one of them.
@*
It is specialized on the device names of the Linux kernel and uses the
capabilities of util-linux program lsblk. Therefore it refuses to run on
non-Linux kernels.
@*
@sp 1
@c man .PP
The main purpose of xorriso-dd-target is to inspect the device files
of disk-like storage media and to judge whether they look like removable
devices with disposable content.
@*
If a single plausible candidate is detected, then the program is willing to 
copy a disk image file onto it. This will overwrite or make inaccessible the 
previous partition table and all previous data content of the target device.
@*
@strong{Superuser power} is needed for filesystem type identification, for
possible unmounting, and for possible image writing. Option @strong{-with_sudo}
offers a way to gain this power only for those tasks and to run the program
elsewise with a normal user's power.
@*
If a particular disk image file is intended as copy source, then
its path should be given by option -image_file, so that its size can be used
as decision criterion.
@sp 1
@c man .PP
Following are use case descriptions with examples:
@c man .br
@c man - List plain device names
@c man .br
@c man - List all devices with reasoning
@c man .br
@c man - Evaluate particular given devices
@c man .br
@c man - Detect intended device by plugging
@c man .br
@c man - Write image to an advised device
@c man .br
@c man - Show commands for writing to a not advised device
@c man .br
@menu
* Simplenames::           List plain device names
* Listall::               List all devices with reasoning
* Givendevices::          Evaluate particular given devices
* Plugtest::              Detect intended device by plugging
* Dowrite::               Write image to an advised device
* Unwise::                Show commands for writing to a not advised device
* Reasons::               Alphabetical list of positive and negative reasons
@end menu
@c man .SS
@node Simplenames, Listall, Overview, Overview
@chapter List plain device names
@c man \fBList plain device names:\fR
@c man .br
@cindex Use case, list advisable device names
The most simple and most boring use case is a program run without device names
and without options -list_all, -plug_test, -DO_WRITE, -dummy_force.
It prints on standard output (stdout) only the names of advisable devices
without "/dev/" prefix. One name per line and without any reasoning text.
@*
Example:
@*
$ xorriso-dd-target -with_sudo
@*
Testing sudo to possibly get password prompting done now:
@*
[sudo] password for thomas: 
@*
sudo /bin/lsblk seems ok.

sde
@c man .SS
@node Listall, Givendevices, Simplenames, Overview
@chapter List all devices with reasoning
@c man \fBList all devices with reasoning:\fR
@c man .br
@cindex Use case, list all devices with reasoning
For the more curious user, there is option @strong{-list_all} which prints
the evaluation of each disk-like device that is listed by program lsblk.
Optical drives and floppy disks are excluded, though.
@*
Each device is shown by one line of the form
@*
  name : advice : reasoning : info
@*
@strong{name} is the device name without "/dev/" prefix.
@*
@strong{advice} is either "YES" or "NO". "YES" indicates that the device
appears to be pluggable disk-like, not used as system disk or sincere data
storage, and - if tested - of sufficient or plausible size.
@*
@strong{reasoning} is a blank separated list of words with either suffix '+'
for an inviting device property or '-' for a prohibitive property. Normally
a single '-' reason disqualifies the device from being advisable. Only if
option -look_for_iso is given, a reason "has_...-" can be overridden by
the presence of an ISO 9660 filesystem on the device.
@*
@strong{info} is composed from VENDOR and MODEL as told by lsblk.
@*
Example:
@*
$ xorriso-dd-target -with_sudo -list_all
@*
 ...
@*
sda : NO  : not_usb- has_vfat+ has_ext4- : ATA Samsung SSD 850 
@*
sdb : NO  : not_usb- has_swap- has_ext4- : ATA WDC WD20EFRX-68A 
@*
sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line 
@*
sdd : NO  : usb+ has_iso9660+ has_vfat+ has_ext2- : SanDisk Cruzer 
@c man .SS
@node Givendevices, Plugtest, Listall, Overview
@chapter Evaluate particular given devices
@c man \fBEvaluate particular given devices:\fR
@c man .br
@cindex Use case, evaluate particular given devices
If @strong{device names} are given instead of option -list_all, then only
these devices are inspected. Their result gets listed without the ": info"
part, unless option @strong{-with_vendor_model} is given.
@*
Device names must not begin by '-' and must be single words. They must
not contain '/'. E.g. 'sdc' is valid, '/dev/sdc' is not valid.
@*
If one of the given device names gets not advised, the exit value is 1.
@*
It makes few sense to give device names which are not listed by -list_all.
@*
Examples:
@*
$ xorriso-dd-target -with_sudo sdc
@*
 ...
@*
sdc : YES : usb+ has_iso9660+ has_vfat+
@*
$ xorriso-dd-target sdc
@*
sdc : NO  : usb+ no_fs_while_not_su-
@c man .SS
@node Plugtest, Dowrite, Givendevices, Overview
@chapter Detect intended device by plugging
@c man \fBDetect intended device by plugging:\fR
@c man .br
@cindex Use case, detect intended device by plugging
Option @strong{-plug_test} triggers an interactive method to unambiguously
determine the intended target device candidate. It consists of 2 or 3 steps.
@*
@strong{Step 1} is to have the intended storage device unplugged and
to confirm this by pressing the Enter key at the program's prompt. The program
will then assess the list of not wanted devices.
@*
@strong{Step 2} is to plug in the intended storage device and to confirm this
by pressing the Enter key a second time. The program will wait up to 10 seconds
for a disk-like storage device which is not in the list of not wanted devices.
The user may wait with key pressing until the device blinking looks like it
is ready.
@*
Only if a single new device is found, the program will go on as if a single
device name was given. Option -list_all and any device names given as arguments
will be ignored.
@*
@strong{Step 3} happens only if options -DO_WRITE or -dummy_force are given.
The program asks for a final press of the Enter key before real or simulated
writing begins.
@*
Example:
@*
$ xorriso-dd-target -with_sudo -plug_test
@*
 ...
@*
Caused by option -plug_test: Attempt to find the desired device
by watching it appear after being plugged in.
@*
Step 1:
@*
Please make sure that the desired target device is plugged _out_ now.
Press the Enter key when ready.
@*
 
@*
Found and noted as _not_ desired:  sda sdb sdc  
@*
Step 2:
@*
Please plug in the desired target device and then press the Enter key.
@*
 
@*
Waiting up to 10 seconds for a new device to be listed ...
@*
Found and noted as desired device:  sdd
@*
 
@*
sdd : NO  : usb+ has_iso9660+ has_vfat+ has_ext2- : SanDisk Cruzer 
@c man .SS
@node Dowrite, Unwise, Plugtest, Overview
@chapter Write image to an advised device
@c man \fBWrite image to an advised device:\fR
@c man .br
@cindex Use case, write image to an advised device
Only if option @strong{-DO_WRITE} is given and -list_all is not, and if exactly
one advisable device is listed, it really gets overwritten by the file content
of the given -image_file. In this case the exit value is zero if writing
succeeded, non-zero else.
@*
Option @strong{-dummy} prevents this kind of real action and rather shows the
planned umount and dd commands on stdout.
@*
Example:
@*
$ xorriso-dd-target -with_sudo -plug_test -DO_WRITE \
@*
    -image_file debian-live-10.0.0-amd64-xfce.iso
@*
 ... sudo messages and above plug test steps 1 and 2 ...
@*
 
@*
sde : YES : usb+ has_iso9660+ has_vfat+ 
@*
Step 3:
@*
Last chance to abort. Press Enter to start REAL WRITING.
@*

@*
Looking for mount points of sde:
@*
  /dev/sde1 on /mnt/iso type iso9660 (ro,relatime)
@*
  /dev/sde2 on /mnt/fat type vfat (rw,...,errors=remount-ro)
@*
Unmounted: /dev/sde1
@*
Unmounted: /dev/sde2
@*
Performing:
@*
  sudo /bin/dd if='debian-live-10.0.0-amd64-xfce.iso' bs=1M of=/dev/sde ; sync
@*
 ... dd messages ...
@c man .SS
@node Unwise, Reasons, Dowrite, Overview
@chapter Show commands for writing to a not advised device
@c man \fBShow commands for writing to a not advised device:\fR
@c man .br
@cindex Use case, show commands for writing to a not advised device
There should be no way to convince xorriso-dd-target of writing to a target
device which it does not deem advisable. Please report any set of arguments
that can be misused for that.
@*
The outmost complicity to potentially unwise actions is offered by
option @strong{-dummy_force}. If given together with a single device name or
with option -plug_test it will act like -dummy -DO_WRITE with this device,
even if it looks not advisable. I.e. it will show the shell commands which the
program does not dare to perform.
@*
Example:
@*
$ xorriso-dd-target -with_sudo -dummy_force sdd \
@*
    -image_file debian-live-10.0.0-amd64-xfce.iso
@*
 ...
@*
sdd : NO  : usb+ has_iso9660+ has_vfat+ has_ext2- 
@*
 
@*
Overriding any advice because of -dummy_force
@*
Looking for mount points of sdd:
@*
  /dev/sdd1 on /mnt/iso type iso9660 (ro,relatime)
@*
  /dev/sdd2 on /mnt/fat type vfat (rw,...,errors=remount-ro)
@*
  /dev/sdd3 on /mnt/ext type ext2 (rw,relatime)
@*
AGAINST THE ADVICE BY THIS PROGRAM, a daring user could do:
@*
  sudo /bin/umount /dev/sdd1
@*
  sudo /bin/umount /dev/sdd2
@*
  sudo /bin/umount /dev/sdd3
@*
  sudo /bin/dd if='debian-live-10.0.0-amd64-xfce.iso' bs=1M of=/dev/sdd ; sync
@*
BE SMART. BE CAUTIOUS. BEWARE.
@c man .SS
@node Reasons, Options, Unwise, Overview
@chapter Alphabetical list of positive and negative reasons
@c man \fBAlphabetical List of positive and negative reasons:\fR
@c man .br
@cindex Reasons, list of
As stated with use case "List all devices", @strong{reasons} are words with
either suffix '+' for an inviting device property or '-' for a prohibitive
property.
@*
Normally a single '-' reason disqualifies the device from being advisable.
@c man .br
@c man .PP
@section Reasons
@strong{has_XYZ-}
@*
A filesystem of type XYZ is detected on base device or partition and is
spoiling the impression of a device with disposable content.
@*
@strong{has_iso9660+}
@*
An ISO 9660 filesystem is detected.
@*
@strong{has_vfat+}
@*
A FAT (MS-DOS-like) filesystem is detected.
@*
@strong{look_for_iso++}
@*
Option -look_for_iso is given and an ISO 9660 filesystem is detected.
This reason overrides any "has_XYZ-" reason.
@*
@strong{looks_like_cd_drive-}
@*
A given device name looks like the name of an optical drive: sr[0-9]*.
Use program @strong{xorrecord} for this kind of devices.
@*
@strong{looks_like_disk_partition-}
@*
A given device name looks like the name of a partition. Expected are names
of base devices, like "sde", not of their partitions, like "sde1".
@*
@strong{lsblk_no_size-}
@*
A size test is given by -max_size, -min_size, or -image_file but the size of
the device cannot be inquired by lsblk. This is supposed to happen only with
given inappropriate device names.
@*
@strong{mmcblk+}
@*
The device name looks like a directly connected memory card.
@*
@strong{name_with_slash-}
@*
A given device name contains '/' characters.
@*
@strong{no_bus_info-}
@*
The device is not a memory card and lsblk reports nothing about the way how
it is connected to the computer.
@*
@strong{no_fs_while_not_su-}
@*
No filesystem is reported by lsblk and the program does not believe to have
run it with superuser powers. There is the risk that lsblk silently failed
to detect existing filesystems.
@*
@strong{no_iso9660-}
@*
Option -look_for_iso is given but no ISO 9660 filesystem is detected.
@*
@strong{not_usb-}
@*
The device is not a memory card and lsblk reports that it is connected by
something other than USB.
@*
@strong{size_too_large-}
@*
Option -max_size is given with a size smaller than the size of the device.
@*
@strong{size_too_small-}
@*
Option -min_size or -image_file is given with size or file size larger than
the size of the device.
@*
@strong{usb+}
@*
The device is reported by lsblk to be connected via USB.
@*
@c man .SS
@node Options, Examples, Overview, Top
@chapter Options
@cindex xorriso-dd-target, options
@c man .br
@c man .SH OPTIONS
@c man .br
@c man .PP
@c man .TP
@table @asis
@item -plug_test
@kindex -plug_test   detect target device plugging
@cindex Target device, detect by plugging, @minus{}plug_test
Find the target device by asking the user to press the Enter key when the
desired target is _not_ plugged in, to then plug it in, and to press Enter
again.
@*
This overrides device names and option -list_all.
The found device is then shown with advice, vendor, and model.
@*
Option -DO_WRITE is obeyed if given.
In this case a final Enter key is demanded before writing begins.
@c man .TP
@item -list_all
@kindex -list_all   print list of disk devices
@cindex Disk devices, print list, -list_all
Print list of all found devices with advice, vendor and model. One per line.
Ignore any device names. Ignore -DO_WRITE.
@c man .TP
@item -with_vendor_model
@kindex -with_vendor_model  add drive info to advice
@cindex Drive info, add to advice, -with_vendor_model
Print vendor and model with each submitted device name.
@c man .TP
@item -max_size n[M|G|T]
@kindex -max_size   set size limit for device
@cindex Device size, set limit, -max_size
Set the upper byte size limit for advisable devices. Plain numbers get rounded
down to full millions. As suffix are recognized: M = million, G = billion,
T = trillion.
@*
Be generous to avoid problems with GB < GiB.
@c man .TP
@item -min_size n[M|G|T]
@kindex -min_size   set size limit for device
@cindex Device size, set limit, -min_size
Set the lower byte size limit for advisable devices. After processing like
with -max_size, one million gets added to the size limit.
@c man .TP
@item -look_for_iso
@kindex -look_for_iso   demand presence of ISO 9660
@cindex ISO 9660, demand presence on target, @minus{}look_for_iso
Demand presence of an ISO 9660 filesystem. If so, then any further filesystem
type is acceptable on that device.
@*
If this option is missing, only ISO 9660 and VFAT filesystems are accepted.
@c man .TP
@item -with_sudo
@kindex -with_sudo   run lsblk, umount, dd by sudo
@cindex lsblk, umount, dd, run by sudo, -with_sudo
Run 'lsblk -o FSTYPE' by sudo. If no filesystems are detected on a device while
the program has no superuser power, then the device is not advised. Option
-with_sudo avoids this refusal without the need to run the whole
program as superuser.
@*
If -DO_WRITE -with_sudo is given, then the programs umount and dd will be run
by sudo, too.
@c man .TP
@item -image_file PATH
@kindex -image_file   set path of disk image file
@cindex disk image file, set path, -image_file
Set the path of the image file which shall be written to a device. Its size
will be set as -min_size.
@c man .TP
@item -DO_WRITE
@kindex -DO_WRITE   write image file to device
@cindex disk image file, write to device, -DO_WRITE
Write the given -image_file to the one advisable device that is found. If more
than one such device is found, then they get listed but no writing happens.
@*
In this case, to get a real write run, consider unplugging unneeded devices,
or using option -plug_test, or a re-run with one of the advised device names
as additional argument.
@c man .TP
@item -dummy
@kindex -dummy   report but do not perform
@cindex only report, do not perform, -dummy
Report the -DO_WRITE actions but do not perform them.
@c man .TP
@item -dummy_force
@kindex -dummy_force   show raw copy commands
@cindex raw copy commands, show, -dummy_force
If a single device name is given, do a run of -dummy -DO_WRITE even against
the advice of this program. This probably shows you ways to shoot your own
foot.
@c man .TP
@item -help
@kindex -help   print help text to stdout
@cindex help text, print to stdout, -help
Print the help text to stdout and then end the program.
@end table
@node Examples, Files, Options, Top
@chapter Examples
@c man .SH EXAMPLES
Examples are given in the above description of use cases.
@node Files, Seealso, Examples, Top 
@chapter Files
@c man .SH FILES
For now, no files are defined for configuration.
@c man .SH SEE ALSO
@c man .BR lsblk(8),
@c man .BR umount(8),
@c man .BR dd(1),
@c man .BR xorrecord(1)
@c man-ignore-lines begin
@node Seealso, Bugreport, Files, Top
@chapter See also
lsblk(8), sudo(8), umount(8), dd(1), xorrecord(1)
@c man-ignore-lines end
@c man .SH BUGS
@node Bugreport, Legal, Seealso, Top
@chapter Reporting bugs
@cindex Bugs, reporting
@cindex Problems, reporting
To report bugs, request help, or suggest enhancements for
@command{xorriso-dd-target}, 
please send electronic mail to the public list @email{bug-xorriso@@gnu.org}.
If more privacy is desired, mail to @email{scdbackup@@gmx.net}.
@*
@sp 1
Please describe what you expect the program to do, the program arguments
which you used, the messages of @command{xorrisodd-target}, and the
undesirable outcome of your program run.
@*
@sp 1
Expect to get asked more questions before solutions can be proposed.
@c man .SH AUTHOR
@node Legal, CommandIdx, Bugreport, Top
@chapter Author, Copyright, Credits
@section Author
Thomas Schmitt <scdbackup@@gmx.net>
@*
for libburnia-project.org
@c man .SH COPYRIGHT
@section Copyright
Copyright (c) 2019 Thomas Schmitt
@*
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of xorriso-dd-target.
If you make use of the license to derive modified versions of xorriso-dd-target
then you are entitled to modify this text under that same license.
@c man .SH CREDITS
@section Credits
@command{xorriso-dd-target} is developed in cooperation with Nio Wiklund alias
sudodus.
@c man-ignore-lines begin

@node CommandIdx, ConceptIdx, Legal, Top
@chapter Alphabetic Options List
@printindex ky

@node ConceptIdx, Top, CommandIdx, Top
@chapter Alphabetic List of Concepts and Objects
@printindex cp

@c man-ignore-lines end
@bye