1@node unshar Invocation 2@section Invoking unshar 3@pindex unshar 4@cindex unpack a shar archive 5@ignore 6# -*- buffer-read-only: t -*- vi: set ro: 7# 8# DO NOT EDIT THIS FILE (invoke-unshar.texi) 9# 10# It has been AutoGen-ed 11# From the definitions unshar-opts.def 12# and the template file agtexi-cmd.tpl 13@end ignore 14Unshar scans the input files (typically email messages) looking for 15the start of a shell archive. If no files are given, then standard 16input is processed instead. It then passes each archive discovered 17through an invocation of the shell program to unpack it. 18 19This section was generated by @strong{AutoGen}, 20using the @code{agtexi-cmd} template and the option descriptions for the @code{unshar} program. 21This software is released under the GNU General Public License, version 3 or later. 22 23@menu 24* unshar usage:: unshar help/usage (@option{--help}) 25* unshar directory:: directory option (-d) 26* unshar overwrite:: overwrite option (-c) 27* unshar force:: force option (-f) 28* unshar split-at:: split-at option (-E) 29* unshar exit-0:: exit-0 option (-e) 30* unshar debug:: debug option (-D) 31* unshar config:: presetting/configuring unshar 32* unshar exit status:: exit status 33* unshar Authors:: Authors 34* unshar Bugs:: Bugs 35* unshar See Also:: See Also 36@end menu 37 38@node unshar usage 39@subsection unshar help/usage (@option{--help}) 40@cindex unshar help 41 42This is the automatically generated usage text for unshar. 43 44The text printed is the same whether selected with the @code{help} option 45(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 46the usage text by passing it through a pager program. 47@code{more-help} is disabled on platforms without a working 48@code{fork(2)} function. The @code{PAGER} environment variable is 49used to select the program, defaulting to @file{more}. Both will exit 50with a status code of 0. 51 52@exampleindent 0 53@example 54unshar (GNU sharutils) - unpack a shar archive 55Usage: unshar [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [<file>...] 56 57 -d, --directory=DIR unpack into the directory DIR 58 -c, --overwrite overwrite any pre-existing files 59 -f, --force an alias for the 'overwrite' option 60 -E, --split-at=SPLIT-PAT split input on SPLIT-PAT lines 61 -e, --exit-0 split input on "exit 0" lines 62 - prohibits the option 'split-at' 63 -D, --debug debug the shell code 64 -v, --version[=MODE] output version information and exit 65 -h, --help display extended usage information and exit 66 -!, --more-help extended usage information passed thru pager 67 -R, --save-opts[=FILE] save the option state to the config file FILE 68 -r, --load-opts=FILE load options from the config file FILE 69 - disabled as '--no-load-opts' 70 - may appear multiple times 71 72Options are specified by doubled hyphens and their name or by a single 73hyphen and the flag character. 74 75If no arguments are provided, input arguments are read from stdin, 76one per line; blank and '#'-prefixed lines are comments. 77'stdin' may not be a terminal (tty). 78 79The following option preset mechanisms are supported: 80 - reading file $HOME/.sharrc 81 82'unshar' scans the input files (typically email messages) looking for the 83start of a shell archive. If no files are given, then standard input is 84processed instead. It then passes each archive discovered through an 85invocation of the shell program to unpack it. 86 87Please send bug reports to: <bug-gnu-utils@@gnu.org> 88@end example 89@exampleindent 4 90 91@node unshar directory 92@subsection directory option (-d) 93@cindex unshar-directory 94 95This is the ``unpack into the directory @file{dir}'' option. 96This option takes a string argument @file{dir}. 97The input file names are relative to the current directory 98when the program was started. This option tells @command{unshar} 99to insert a @code{cd <dir>} commad at the start of the 100@command{shar} text written to the shell. 101@node unshar overwrite 102@subsection overwrite option (-c) 103@cindex unshar-overwrite 104 105This is the ``overwrite any pre-existing files'' option. 106This option is passed through as an option to the shar file. Many 107shell archive scripts accept a @option{-c} argument to indicate that 108existing files should be overwritten. 109@node unshar force 110@subsection force option (-f) 111@cindex unshar-force 112 113This is an alias for the @code{overwrite} option, 114@pxref{unshar overwrite, the overwrite option documentation}. 115 116@node unshar split-at 117@subsection split-at option (-E) 118@cindex unshar-split-at 119 120This is the ``split input on @var{split-mark} lines'' option. 121This option takes a string argument @file{split-mark}. 122With this option, @command{unshar} isolates each different shell archive 123from the others which have been placed in the same file, unpacking each 124in turn, from the beginning of the file to the end. Its proper 125operation relies on the fact that many shar files are terminated by a 126readily identifiable string at the start of the last line. 127 128For example, noticing that most `.signatures' have a double hyphen 129("--") on a line right before them, one can then sometimes use 130@code{--split-at=--}. The signature will then be skipped, along with 131the headers of the following message. 132@node unshar exit-0 133@subsection exit-0 option (-e) 134@cindex unshar-exit-0 135 136This is the ``split input on "exit 0" lines'' option. 137 138@noindent 139This option has some usage constraints. It: 140@itemize @bullet 141@item 142must not appear in combination with any of the following options: 143split-at. 144@end itemize 145 146Most shell archives end with a line consisting of simply "exit 0". 147This option is equivalent to (and conflicts with) 148@code{--split-at="exit 0"}. 149@node unshar debug 150@subsection debug option (-D) 151@cindex unshar-debug 152 153This is the ``debug the shell code'' option. 154"set -x" will be emitted into the code the shell interprets. 155 156 157@node unshar config 158@subsection presetting/configuring unshar 159 160Any option that is not marked as @i{not presettable} may be preset by 161loading values from configuration ("rc" or "ini") files. 162 163 164@noindent 165@code{libopts} will search in @file{$HOME} for configuration (option) data. 166The environment variable @code{HOME, } is expanded and replaced when 167the program runs 168If this is a plain file, it is simply processed. 169If it is a directory, then a file named @file{.sharrc} is searched for within that directory. 170 171Configuration files may be in a wide variety of formats. 172The basic format is an option name followed by a value (argument) on the 173same line. Values may be separated from the option name with a colon, 174equal sign or simply white space. Values may be continued across multiple 175lines by escaping the newline with a backslash. 176 177Multiple programs may also share the same initialization file. 178Common options are collected at the top, followed by program specific 179segments. The segments are separated by lines like: 180@example 181[UNSHAR] 182@end example 183@noindent 184or by 185@example 186<?program unshar> 187@end example 188@noindent 189Do not mix these styles within one configuration file. 190 191Compound values and carefully constructed string values may also be 192specified using XML syntax: 193@example 194<option-name> 195 <sub-opt>...<...>...</sub-opt> 196</option-name> 197@end example 198@noindent 199yielding an @code{option-name.sub-opt} string value of 200@example 201"...<...>..." 202@end example 203@code{AutoOpts} does not track suboptions. You simply note that it is a 204hierarchicly valued option. @code{AutoOpts} does provide a means for searching 205the associated name/value pair list (see: optionFindValue). 206 207The command line options relating to configuration and/or usage help are: 208 209@subsubheading version (-v) 210 211Print the program version to standard out, optionally with licensing 212information, then exit 0. The optional argument specifies how much licensing 213detail to provide. The default is to print the license name with the version. The licensing infomation may be selected with an option argument. 214Only the first letter of the argument is examined: 215 216@table @samp 217@item version 218Only print the version. 219@item copyright 220Name the copyright usage licensing terms. This is the default. 221@item verbose 222Print the full copyright usage licensing terms. 223@end table 224 225@node unshar exit status 226@subsection unshar exit status 227 228One of the following exit values will be returned: 229@table @samp 230@item 0 (EXIT_SUCCESS) 231Successful program execution. 232@item 1 (EXIT_FAILURE) 233There was an error in command usage. 234@item 2 (EXIT_POPEN_PROBLEM) 235cannot spawn or write to a shell process 236@item 3 (EXIT_CANNOT_CREATE) 237cannot create output file 238@item 4 (EXIT_BAD_DIRECTORY) 239the working directory structure is invalid 240@item 5 (EXIT_NOMEM) 241memory allocation failure 242@item 6 (EXIT_INVALID) 243invalid input, does not contain a shar file 244@item 66 (EX_NOINPUT) 245A specified configuration file could not be loaded. 246@item 70 (EX_SOFTWARE) 247libopts had an internal operational error. Please report 248it to autogen-users@@lists.sourceforge.net. Thank you. 249@end table 250@node unshar Authors 251@subsection unshar Authors 252The @file{shar} and @file{unshar} programs is the collective work of 253many authors. Many people contributed by reporting problems, 254suggesting various improvements or submitting actual code. A list of 255these people is in the @file{THANKS} file in the sharutils distribution. 256@node unshar Bugs 257@subsection unshar Bugs 258Please put @samp{sharutils} in the subject line for emailed bug 259reports. It helps to spot the message. 260@node unshar See Also 261@subsection unshar See Also 262shar(1) 263