libburnia/libisoburn
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added info and man page for xorriso-dd-target

Browse Source
This commit is contained in:
Thomas Schmitt 2019-12-02 10:59:14 +01:00
parent a6ab055153
commit 23bce9c669
5 changed files with 1682 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

491
xorriso-dd-target/xorriso-dd-target.1 Normal file
View File

@ -0,0 +1,491 @@
.\" Hey, EMACS: -*- nroff -*-
.\"
.\" IMPORTANT NOTE:
.\"
.\" The original of this file is kept in xorriso/xorriso-tcltk.texi
.\" This here was generated by program xorriso/make_xorriso_1
.\"
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH XORRISO-DD-TARGET 1 "Version 1.5.3, Dec 2, 2019"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh disable hyphenation
.\" .hy enable hyphenation
.\" .ad l left justify
.\" .ad b justify to both left and right margins
.\" .nf disable filling
.\" .fi enable filling
.\" .br insert line break
.\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.nh
.SH NAME
xorriso\-dd\-target \- Device evaluator and disk image copier for GNU/Linux
.SH SYNOPSIS
.B xorriso-dd-target
[ options ] [ device_names ]
.br
.SH DESCRIPTION
.PP
\fBxorriso\-dd\-target\fR
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.
.br
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.
.br
.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.
.br
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.
.br
\fBSuperuser power\fR is needed for filesystem type identification, for
possible unmounting, and for possible image writing. Option \fB\-with_sudo\fR
offers a way to gain this power only for those tasks and to run the program
elsewise with a normal user's power.
.br
If a particular disk image file is intended as eventual copy source, then
its path should be given by option \-image_file, so that its size can be used
as decision criterion.
.PP
Following are use case descriptions with examples:
.br
- List plain device names
.br
- List all devices with reasoning
.br
- Evaluate particular given devices
.br
- Detect intended device by plugging
.br
- Write image to an advised device
.br
- Show commands for writing to a not advised device
.br
.SS
\fBList plain device names:\fR
.br
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.
.br
Example:
.br
$ xorriso\-dd\-target \-with_sudo
.br
Testing sudo to possibly get password prompting done now:
.br
[sudo] password for thomas:
.br
sudo /bin/lsblk seems ok.
sde
.SS
\fBList all devices with reasoning:\fR
.br
For the more curious user, there is option \fB\-list_all\fR which prints
the evaluation of each disk\-like device that is listed by program lsblk.
Optical drives and floppy disks are excluded, though.
.br
Each device is shown by one line of the form
.br
name : advice : reasoning : info
.br
\fBname\fR is the device name without "/dev/" prefix.
.br
\fBadvice\fR 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.
.br
\fBreasoning\fR 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.
.br
\fBinfo\fR is composed from VENDOR and MODEL as told by lsblk.
.br
Example:
.br
$ xorriso\-dd\-target \-with_sudo \-list_all
.br
...
.br
sda : NO : not_usb\- has_vfat+ has_ext4\- : ATA Samsung SSD 850
.br
sdb : NO : not_usb\- has_swap\- has_ext4\- : ATA WDC WD20EFRX\-68A
.br
sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
.br
sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2\- : SanDisk Cruzer
.SS
\fBEvaluate particular given devices:\fR
.br
If \fBdevice names\fR are given instead of option \-list_all, then only
these devices are inspected. Their result gets listed without the ": info"
part, unless option \fB\-with_vendor_model\fR is given.
.br
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.
.br
If one of the given device names gets not advised, the exit value is 1.
.br
It makes few sense to give device names which are not listed by \-list_all.
.br
Examples:
.br
$ xorriso\-dd\-target \-with_sudo sdc
.br
...
.br
sdc : YES : usb+ has_iso9660+ has_vfat+
.br
$ xorriso\-dd\-target sdc
.br
sdc : NO : usb+ no_fs_while_not_su\-
.SS
\fBDetect intended device by plugging:\fR
.br
Option \fB\-plug_test\fR triggers an interactive method to unambiguously
determine the intended target device candidate. It consists of 2 or 3 steps.
.br
\fBStep 1\fR 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.
.br
\fBStep 2\fR 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.
.br
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.
.br
\fBStep 3\fR 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.
.br
Example:
.br
$ xorriso\-dd\-target \-with_sudo \-plug_test
.br
...
.br
Caused by option \-plug_test: Attempt to find the desired device
by watching it appear after being plugged in.
.br
Step 1:
.br
Please make sure that the desired target device is plugged _out_ now.
Press the Enter key when ready.
.br
.br
Found and noted as _not_ desired: sda sdb sdc
.br
Step 2:
.br
Please plug in the desired target device and then press the Enter key.
.br
.br
Waiting up to 10 seconds for a new device to be listed ...
.br
Found and noted as desired device: sdd
.br
.br
sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2\- : SanDisk Cruzer
.SS
\fBWrite image to an advised device:\fR
.br
Only if option \fB\-DO_WRITE\fR 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.
.br
Option \fB\-dummy\fR prevents this kind of real action and rather shows the
planned umount and dd commands on stdout.
.br
Example:
.br
$ xorriso\-dd\-target \-with_sudo \-plug_test \-DO_WRITE \\
.br
> \-image_file debian\-live\-10.0.0\-amd64\-xfce.iso
.br
... sudo messages and above plug test steps 1 and 2 ...
.br
.br
sde : YES : usb+ has_iso9660+ has_vfat+
.br
Step 3:
.br
Last chance to abort. Press Enter to start REAL WRITING.
.br
.br
Looking for mount points of sde:
.br
/dev/sde1 on /mnt/iso type iso9660 (ro,relatime)
.br
/dev/sde2 on /mnt/fat type vfat (rw,...,errors=remount\-ro)
.br
Unmounted: /dev/sde1
.br
Unmounted: /dev/sde2
.br
Performing:
.br
sudo /bin/dd if='debian\-live\-10.0.0\-amd64\-xfce.iso' bs=1M of=/dev/sde ; sync
.br
... dd messages ...
.SS
\fBShow commands for writing to a not advised device:\fR
.br
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.
.br
The outmost complicity to potentially unwise actions is offered by
option \fB\-dummy_force\fR. 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.
.br
Example:
.br
$ xorriso\-dd\-target \-with_sudo \-dummy_force sdd \\
.br
> \-image_file debian\-live\-10.0.0\-amd64\-xfce.iso
.br
...
.br
sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2\-
.br
.br
Overriding any advice because of \-dummy_force
.br
Looking for mount points of sdd:
.br
/dev/sdd1 on /mnt/iso type iso9660 (ro,relatime)
.br
/dev/sdd2 on /mnt/fat type vfat (rw,...,errors=remount\-ro)
.br
/dev/sdd3 on /mnt/ext type ext2 (rw,relatime)
.br
AGAINST THE ADVICE BY THIS PROGRAM, a daring user could do:
.br
sudo /bin/umount /dev/sdd1
.br
sudo /bin/umount /dev/sdd2
.br
sudo /bin/umount /dev/sdd3
.br
sudo /bin/dd if='debian\-live\-10.0.0\-amd64\-xfce.iso' bs=1M of=/dev/sdd ; sync
.br
BE SMART. BE CAUTIOUS. BEWARE.
.SS
\fBAlphabetical List of positive and negative reasons:\fR
.br
As stated with use case "List all devices", \fBreasons\fR are words with
either suffix '+' for an inviting device property or '\-' for a prohibitive
property.
.br
Normally a single '\-' reason disqualifies the device from being advisable.
.br
.PP
\fBhas_XYZ\-\fR
.br
A filesystem of type XYZ is detected on base device or partition and is
spoiling the impression of a device with disposable content.
.br
\fBhas_iso9660+\fR
.br
An ISO 9660 filesystem is detected.
.br
\fBhas_vfat+\fR
.br
A FAT (MS\-DOS\-like) filesystem is detected.
.br
\fBlook_for_iso++\fR
.br
Option \-look_for_iso is given and an ISO 9660 filesystem is detected.
This reason overrides any "has_XYZ\-" reason.
.br
\fBlooks_like_cd_drive\-\fR
.br
A given device name looks like the name of an optical drive: sr[0\-9]*.
Use program \fBxorrecord\fR for this kind of devices.
.br
\fBlooks_like_disk_partition\-\fR
.br
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".
.br
\fBlsblk_no_size\-\fR
.br
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.
.br
\fBmmcblk+\fR
.br
The device name looks like a directly connected memory card.
.br
\fBname_with_slash\-\fR
.br
A given device name contains '/' characters.
.br
\fBno_bus_info\-\fR
.br
The device is not a memory card and lsblk reports nothing about the way how
it is connected to the computer.
.br
\fBno_fs_while_not_su\-\fR
.br
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.
.br
\fBno_iso9660\-\fR
.br
Option \-look_for_iso is given but no ISO 9660 filesystem is detected.
.br
\fBnot_usb\-\fR
.br
The device is not a memory card and lsblk reports that it is connected by
something other than USB.
.br
\fBsize_too_large\-\fR
.br
Option \-max_size is given with a size smaller than the size of the device.
.br
\fBsize_too_small\-\fR
.br
Option \-min_size or \-image_file is given with size or file size larger than
the size of the device.
.br
\fBusb+\fR
.br
The device is reported by lsblk to be connected via USB.
.br
.SS
.br
.SH OPTIONS
.br
.PP
.TP
\fB\-plug_test\fR
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.
.br
This overrides device names and option \-list_all.
The found device is then shown with advice, vendor, and model.
.br
Option \-DO_WRITE is obeyed if given.
In this case a final Enter key is demanded before writing begins.
.TP
\fB\-list_all\fR
Print list of all found devices with advice, vendor and model. One per line.
Ignore any device names. Ignore \-DO_WRITE.
.TP
\fB\-with_vendor_model\fR
Print vendor and model with each submitted device name.
.TP
\fB\-max_size\fR n[M|G|T]
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.
.br
Be generous to avoid problems with GB < GiB.
.TP
\fB\-min_size\fR n[M|G|T]
Set the lower byte size limit for advisable devices. After processing like
with \-max_size, one million gets added to the size limit.
.TP
\fB\-look_for_iso\fR
Demand presence of an ISO 9660 filesystem. If so, then any further filesystem
type is acceptable on that device.
.br
If this option is missing, only ISO 9660 and VFAT filesystems are accepted.
.TP
\fB\-with_sudo\fR
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.
.br
If \-DO_WRITE \-with_sudo is given, then the programs umount and dd will be run
by sudo, too.
.TP
\fB\-image_file\fR PATH
Set the path of the image file which shall be written to a device. Its size
will be set as \-min_size.
.TP
\fB\-DO_WRITE\fR
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.
.br
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.
.TP
\fB\-dummy\fR
Report the \-DO_WRITE actions but do not perform them.
.TP
\fB\-dummy_force\fR
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.
.TP
\fB\-help\fR
Print the help text to stdout and then end the program.
.SH EXAMPLES
Examples are given in the above description of use cases.
.SH FILES
For now, no files are defined for configuration.
.SH SEE ALSO
.BR lsblk(8),
.BR umount(8),
.BR dd(1),
.BR xorrecord(1)
.SH BUGS
To report bugs, request help, or suggest enhancements for
\fBxorriso\-dd\-target\fR,
please send electronic mail to the public list <bug\-xorriso@gnu.org>.
If more privacy is desired, mail to <scdbackup@gmx.net>.
.br
Please describe what you expect the program to do, the program arguments
which you used, the messages of \fBxorrisodd\-target\fR, and the
undesirable outcome of your program run.
.br
Expect to get asked more questions before solutions can be proposed.
.SH AUTHOR
Thomas Schmitt <scdbackup@gmx.net>
.br
for libburnia\-project.org
.SH COPYRIGHT
Copyright (c) 2019 Thomas Schmitt
.br
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\-idd\-target
then you are entitled to modify this text under that same license.
.SH CREDITS
\fBxorriso\-dd\-target\fR is developed in cooperation with Nio Wiklund alias
sudodus.

518
xorriso-dd-target/xorriso-dd-target.info Normal file
View File

@ -0,0 +1,518 @@
This is xorriso-dd-target.info, produced by makeinfo version 5.2 from
xorriso-dd-target.texi.
xorriso-tcltk - Device evaluator and disk image copier for GNU/Linux
Copyright (C) 2019 Thomas Schmitt
Permission is granted to distribute this text freely.
INFO-DIR-SECTION Archiving
START-INFO-DIR-ENTRY
* Xorriso-dd-target: (xorriso-dd-target). Device evaluator and disk image copier for GNU/Linux
END-INFO-DIR-ENTRY

File: xorriso-dd-target.info, Node: Top, Next: Overview, Up: (dir)
xorriso-dd-target 1.5.3
***********************
xorriso-dd-target - Device evaluator and disk image copier for GNU/Linux
* 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

File: xorriso-dd-target.info, Node: Overview, Next: Options, Prev: Top, Up: Top
1 Overview
**********
'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.
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.
*Superuser power* is needed for filesystem type identification, for
possible unmounting, and for possible image writing. Option
*-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 eventual copy source,
then its path should be given by option -image_file, so that its size
can be used as decision criterion.
Following are use case descriptions with examples:
* 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

File: xorriso-dd-target.info, Node: Simplenames, Next: Listall, Prev: Overview, Up: Overview
2 List plain 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

File: xorriso-dd-target.info, Node: Listall, Next: Givendevices, Prev: Simplenames, Up: Overview
3 List all devices with reasoning
*********************************
For the more curious user, there is option *-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
*name* is the device name without "/dev/" prefix.
*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.
*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.
*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

File: xorriso-dd-target.info, Node: Givendevices, Next: Plugtest, Prev: Listall, Up: Overview
4 Evaluate particular given devices
***********************************
If *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 *-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-

File: xorriso-dd-target.info, Node: Plugtest, Next: Dowrite, Prev: Givendevices, Up: Overview
5 Detect intended device by plugging
************************************
Option *-plug_test* triggers an interactive method to unambiguously
determine the intended target device candidate. It consists of 2 or 3
steps.
*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.
*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.
*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

File: xorriso-dd-target.info, Node: Dowrite, Next: Unwise, Prev: Plugtest, Up: Overview
6 Write image to an advised device
**********************************
Only if option *-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 *-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 ...

File: xorriso-dd-target.info, Node: Unwise, Next: Reasons, Prev: Dowrite, Up: Overview
7 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 *-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.

File: xorriso-dd-target.info, Node: Reasons, Next: Options, Prev: Unwise, Up: Overview
8 Alphabetical list of positive and negative reasons
****************************************************
As stated with use case "List all devices", *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.
8.1 Reasons
===========
*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.
*has_iso9660+*
An ISO 9660 filesystem is detected.
*has_vfat+*
A FAT (MS-DOS-like) filesystem is detected.
*look_for_iso++*
Option -look_for_iso is given and an ISO 9660 filesystem is detected.
This reason overrides any "has_XYZ-" reason.
*looks_like_cd_drive-*
A given device name looks like the name of an optical drive: sr[0-9]*.
Use program *xorrecord* for this kind of devices.
*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".
*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.
*mmcblk+*
The device name looks like a directly connected memory card.
*name_with_slash-*
A given device name contains '/' characters.
*no_bus_info-*
The device is not a memory card and lsblk reports nothing about the way
how it is connected to the computer.
*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.
*no_iso9660-*
Option -look_for_iso is given but no ISO 9660 filesystem is detected.
*not_usb-*
The device is not a memory card and lsblk reports that it is connected
by something other than USB.
*size_too_large-*
Option -max_size is given with a size smaller than the size of the
device.
*size_too_small-*
Option -min_size or -image_file is given with size or file size larger
than the size of the device.
*usb+*
The device is reported by lsblk to be connected via USB.

File: xorriso-dd-target.info, Node: Options, Next: Examples, Prev: Overview, Up: Top
9 Options
*********
-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.
-list_all
Print list of all found devices with advice, vendor and model. One
per line. Ignore any device names. Ignore -DO_WRITE.
-with_vendor_model
Print vendor and model with each submitted device name.
-max_size n[M|G|T]
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.
-min_size n[M|G|T]
Set the lower byte size limit for advisable devices. After
processing like with -max_size, one million gets added to the size
limit.
-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.
-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.
-image_file PATH
Set the path of the image file which shall be written to a device.
Its size will be set as -min_size.
-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.
-dummy
Report the -DO_WRITE actions but do not perform them.
-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.
-help
Print the help text to stdout and then end the program.

File: xorriso-dd-target.info, Node: Examples, Next: Files, Prev: Options, Up: Top
10 Examples
***********
Examples are given in the above description of use cases.

File: xorriso-dd-target.info, Node: Files, Next: Seealso, Prev: Examples, Up: Top
11 Files
********
For now, no files are defined for configuration.

File: xorriso-dd-target.info, Node: Seealso, Next: Bugreport, Prev: Files, Up: Top
12 See also
***********
lsblk(8), sudo(8), umount(8), dd(1), xorrecord(1)

File: xorriso-dd-target.info, Node: Bugreport, Next: Legal, Prev: Seealso, Up: Top
13 Reporting bugs
*****************
To report bugs, request help, or suggest enhancements for
'xorriso-dd-target', please send electronic mail to the public list
<bug-xorriso@gnu.org>. If more privacy is desired, mail to
<scdbackup@gmx.net>.
Please describe what you expect the program to do, the program
arguments which you used, the messages of 'xorrisodd-target', and the
undesirable outcome of your program run.
Expect to get asked more questions before solutions can be proposed.

File: xorriso-dd-target.info, Node: Legal, Next: CommandIdx, Prev: Bugreport, Up: Top
14 Author, Copyright, Credits
*****************************
14.1 Author
===========
Thomas Schmitt <scdbackup@gmx.net>
for libburnia-project.org
14.2 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-idd-target then you are entitled to modify this text under that
same license.
14.3 Credits
============
'xorriso-dd-target' is developed in cooperation with Nio Wiklund alias
sudodus.

File: xorriso-dd-target.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
15 Alphabetic Options List
**************************
[index]
* Menu:
* -DO_WRITE write image file to device: Options. (line 44)
* -dummy report but do not perform: Options. (line 51)
* -dummy_force show raw copy commands: Options. (line 53)
* -help print help text to stdout: Options. (line 57)
* -image_file set path of disk image file: Options. (line 41)
* -list_all print list of disk devices: Options. (line 15)
* -look_for_iso demand presence of ISO 9660: Options. (line 29)
* -max_size set size limit for device: Options. (line 20)
* -min_size set size limit for device: Options. (line 25)
* -plug_test detect target device plugging: Options. (line 7)
* -with_sudo run lsblk, umount, dd by sudo: Options. (line 34)
* -with_vendor_model add drive info to advice: Options. (line 18)

File: xorriso-dd-target.info, Node: ConceptIdx, Next: Top, Prev: CommandIdx, Up: Top
16 Alphabetic List of Concepts and Objects
******************************************
[index]
* Menu:
* Bugs, reporting: Bugreport. (line 6)
* Device size, set limit, -max_size: Options. (line 20)
* Device size, set limit, -min_size: Options. (line 25)
* Disk devices, print list, -list_all: Options. (line 15)
* disk image file, set path, -image_file: Options. (line 41)
* disk image file, write to device, -DO_WRITE: Options. (line 44)
* Drive info, add to advice, -with_vendor_model: Options. (line 18)
* help text, print to stdout, -help: Options. (line 57)
* ISO 9660, demand presence on target, -look_for_iso: Options. (line 29)
* lsblk, umount, dd, run by sudo, -with_sudo: Options. (line 34)
* only report, do not perform, -dummy: Options. (line 51)
* Problems, reporting: Bugreport. (line 6)
* raw copy commands, show, -dummy_force: Options. (line 53)
* Reasons, list of: Reasons. (line 6)
* Target device, detect by plugging, -plug_test: Options. (line 7)
* Use case, detect intended device by plugging: Plugtest. (line 6)
* Use case, evaluate particular given devices: Givendevices. (line 6)
* Use case, list advisable device names: Simplenames. (line 6)
* Use case, list all devices with reasoning: Listall. (line 6)
* Use case, show commands for writing to a not advised device: Unwise.
(line 6)
* Use case, write image to an advised device: Dowrite. (line 6)
* xorriso-dd-target, options: Options. (line 6)

Tag Table:
Node: Top425
Node: Overview992
Node: Simplenames2784
Node: Listall3395
Node: Givendevices4805
Node: Plugtest5607
Node: Dowrite7355
Node: Unwise8464
Node: Reasons9822
Node: Options12120
Node: Examples14722
Node: Files14895
Node: Seealso15053
Node: Bugreport15219
Node: Legal15805
Node: CommandIdx16510
Node: ConceptIdx17557

End Tag Table

664
xorriso-dd-target/xorriso-dd-target.texi Normal file
View File

@ -0,0 +1,664 @@
\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-tcltk.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-tcltk - 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 eventual 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-idd-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

2
xorriso/make_docs.sh
View File

@ -8,10 +8,12 @@
( cd xorriso ; makeinfo ./xorrisofs.texi )
( cd xorriso ; makeinfo ./xorrecord.texi )
( cd xorriso ; makeinfo ./xorriso-tcltk.texi )
( cd xorriso-dd-target ; makeinfo ./xorriso-dd-target.texi )
xorriso/make_xorriso_1 -auto
xorriso/make_xorriso_1 -auto -xorrisofs
xorriso/make_xorriso_1 -auto -xorrecord
xorriso/make_xorriso_1 -auto -xorriso-tcltk
xorriso/make_xorriso_1 -auto -xorriso-dd-target

9
xorriso/make_xorriso_1.c
View File

@ -7,10 +7,11 @@
or from xorriso/xorrisofs.texi to xorriso/xorrisofs.1,
or from xorriso/xorrecord.texi to xorriso/xorrecord.1.
or from xorriso/xorriso-tcltk.texi to xorriso/xorriso-tcltk.1.
or from xorriso/xorriso-dd-target.texi to xorriso/xorriso-dd-target.1.
The conversion rules are described at the beginning of xorriso/xorriso.texi
Copyright 2010 - 2011 Thomas Schmitt, <scdbackup@gmx.net>
Copyright 2010 - 2019 Thomas Schmitt, <scdbackup@gmx.net>
Provided under GPL version 2 or later.
*/
@ -190,7 +191,7 @@ int Mx1_rewrap(struct Mx1 *m, char **read_pt, char **write_pt,
strcpy(wpt, front);
wpt+= strlen(front);
if(l > 0)
strncpy(wpt, content, l);
memcpy(wpt, content, l);
wpt+= l;
strcpy(wpt, back);
wpt+= strlen(back);
@ -477,6 +478,7 @@ usage:;
fprintf(stderr, " -xorrisofs process xorriso/xorrisofs.texi\n");
fprintf(stderr, " -xorrecord process xorriso/xorrecord.texi\n");
fprintf(stderr, " -xorriso-tcltk process xorriso/-xorriso-tcltk.texi\n");
fprintf(stderr, " -xorriso-dd-target process xorriso/-xorriso-dd-target.texi\n");
exit(2);
}
for(i= 1; i < argc; i++) {
@ -493,6 +495,9 @@ usage:;
} else if(strcmp(argv[i], "-xorriso-tcltk") == 0) {
strcpy(name_in, "xorriso/xorriso-tcltk.texi");
strcpy(name_out, "xorriso/xorriso-tcltk.1");
} else if(strcmp(argv[i], "-xorriso-dd-target") == 0) {
strcpy(name_in, "xorriso-dd-target/xorriso-dd-target.texi");
strcpy(name_out, "xorriso-dd-target/xorriso-dd-target.1");
} else {
fprintf(stderr, "%s : unknown option %s\n", argv[0], argv[i]);
goto usage;