diff --git a/xorriso-dd-target/xorriso-dd-target.1 b/xorriso-dd-target/xorriso-dd-target.1 new file mode 100644 index 00000000..abe5cf5d --- /dev/null +++ b/xorriso-dd-target/xorriso-dd-target.1 @@ -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 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 . +If more privacy is desired, mail to . +.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 +.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. diff --git a/xorriso-dd-target/xorriso-dd-target.info b/xorriso-dd-target/xorriso-dd-target.info new file mode 100644 index 00000000..f3147408 --- /dev/null +++ b/xorriso-dd-target/xorriso-dd-target.info @@ -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 +. If more privacy is desired, mail to +. + + 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 +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 diff --git a/xorriso-dd-target/xorriso-dd-target.texi b/xorriso-dd-target/xorriso-dd-target.texi new file mode 100644 index 00000000..3dcc683c --- /dev/null +++ b/xorriso-dd-target/xorriso-dd-target.texi @@ -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 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 +@* +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 diff --git a/xorriso/make_docs.sh b/xorriso/make_docs.sh index 96e749a7..9455297e 100755 --- a/xorriso/make_docs.sh +++ b/xorriso/make_docs.sh @@ -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 diff --git a/xorriso/make_xorriso_1.c b/xorriso/make_xorriso_1.c index ae059817..9c1dfab9 100644 --- a/xorriso/make_xorriso_1.c +++ b/xorriso/make_xorriso_1.c @@ -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, + Copyright 2010 - 2019 Thomas Schmitt, 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;