\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/utils.info
@settitle DJGPP Utilities Reference
@c %**end of header

@setchapternewpage odd
@paragraphindent 0

@ifinfo
This is the reference manual for DJGPP V2's miscellaneous utilities

Copyright (c) 1995 DJ Delorie
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{DJGPP Utilities Reference}

@vskip 0pt plus 1filll
Copyright @copyright{} 1995 @email{dj@@delorie.com, DJ Delorie}
@end titlepage

@c -----------------------------------------------------------------------------
@node Top,,,(dir)
@comment node, next, previous, up

This is the reference manual for the miscellaneous utility programs that
come with DJGPP.

@menu

* bin2h::       Convert binary data files to C include files.

* djecho::      Echo long command lines to files.

* djtar::       Extract or list files from (possibly compressed)
		tar archives, with DOS filename conversion.

* dtou::        Convert text files from dos to unix.
* utod::        Convert text files from unix to dos.

* gxx::         Build and link C++ programs

* redir::       Manage I/O Redirection.

* djsplit::     split large files into multiple files.
* djmerge::     Merge multiple files into one file.

* texi2ps::     Convert texinfo files to Postscript.

* update::      conditionally copy one file to another.

@end menu

@c -----------------------------------------------------------------------------
@node bin2h, djecho, , Top
@chapter bin2h

@code{bin2h} allows a developer to embed a binary file into a source
file, by converting the binary data to an array of integer values.

Usage: @code{bin2h} @file{datafile} @var{symbol} @file{headerfile}

The resulting header file has a format like this:

@example
unsigned char symbol[] = @{
  ... data ...
@};
@end example

@c -----------------------------------------------------------------------------
@node djecho, djtar, bin2h, Top
@chapter djecho

This program simply echoes whatever is given to it on the command line.

@smallexample
 @r{Usage:} djecho [-n] [-o @var{file}] [-s] [-a] @var{args}@dots{}
@end smallexample

@table @code

@item -n

Do not emit the trailing newline after printing the text.

@item -o @var{file}

Send output to a @var{file}.

@item -s

Separate @var{args} with a newline, instead of the default blank.  This
is useful for writing several lines of output in a single invocation
(which is faster than several separate commands).

@item -a

Append the output to the file instead of overwriting it.  Useful with
the @samp{-o} option.

@end table

The purpose of this program is to be able to interact directly with
@code{make}'s ability to pass long command lines to programs.  If you
use redirection, you aren't always able to handle long command lines
(especially since echo is normally in @file{command.com}).  With
@code{djecho}, you can, and you can use the @samp{-o} option to redirect
output to a file (and use the file later as a response file) without
using DOS's redirection.

Latest versions of ported @code{make} do not invoke @file{command.com}
for redirection and @code{echo} commands, but @code{djecho} is still
useful for related tasks, e.g. for writing several lines to a file in a
single invocation.  Since @code{djecho} is part of the basic DJGPP
development environment, it is easy to rely on it being present when a
package is built.

@c -----------------------------------------------------------------------------
@node djtar, dtou, djecho, Top
@chapter djtar

Usage: @code{djtar} [@code{-n} @file{changeFile}] [@code{-o} @file{dir}]
[@code{-t}|@code{-x}] [@code{-i}] [@code{-v}] [@code{-p}]
[@code{-.}|@code{-!.}] [@code{-d}|@code{-u}|@code{-b}] @file{tarfile}

@code{djtar} is a program that is designed to ease the problems related
to extracting Unix tar files on a DOS machine.  The long file names and
illegal characters make regular tar programs useless.  What @code{djtar}
does is make some obvious name conversions automatically and give you an
opportunity to provide alternate names for more difficult cases, where
several filenames map to the same name in the restricted 8+3 DOS filename
space.

@code{djtar} can read compressed tar files and decompress them on the
fly.  (This can be also achieved by piping the output of @code{gzip} to
@code{djtar}, but for very large archives you can run out of free disk
space, because DOS implements pipes as temporary disk files.)
@code{djtar} knows about all the compression methods supported by
@code{gzip}, namely, deflation (by @code{gzip}), LZW compression
(by @code{compress}), LZH compression (as with @code{compress -H}
available with some versions of @code{compress}), or Huffman compression
(by @code{pack}).

@code{djtar} can decompress @file{.tar} archive files compressed with
@code{bzip2}, even if several of such @code{bzip2}-compressed
@file{*.tar.bz2} or @file{*.tbz} archive files have been concatenated
into a single file.

@code{djtar} can decompress files compressed with @code{zip} or
@code{pkzip} as well, but only if the @file{.zip} file contains only
files compressed with either the @code{deflation} or @code{stored}
(i.e., uncompressed, like with @samp{pkzip -e0}) methods.

@code{djtar} can also read tar archives (compressed or otherwise) written
on a Unix machine to a diskette as a raw device (i.e., without DOS
filesystem).  To use @code{djtar} with such archives, specify a name
of the drive (like @code{A:}) as a tarfile argument.

When extracting files from compressed archives, @code{djtar} will
validate them with whatever reduntant checks are available with the
compression format, and print diagnostic messages whenever these checks
fail.  The checks and the diagnostics are generally identical to those
performed by @code{gzip}.  Some of the diagnostics are only printed under
the verbose operation switched on by the @samp{-v} switch.  Unless you use
the @samp{-i} switch, @code{djtar} will refuse to create files and
directories beyond the first tar directory entry which fails the checksum
test; this usually means the file is either corrupted or not in a valid
tar format.

An additional bonus of using @code{djtar} is that it can convert
Unix-style text files to DOS-style text files, and vice versa.  By
default, it will write all files exactly as found in the archive, but the
@samp{-u} and @samp{-d} options can change that.

@code{djtar} performs a number of file name conversions in an attempt
to make the files fit into MS-DOS's restricted file names.  Any file
ending in @file{.info-@var{n}}, where @var{n} is a number, becomes
@file{.i@var{n}}.  Any file ending in @file{.tar.gz} becomes
@file{.tgz}.  Any @file{++} string within a file name becomes @file{xx}.
Any leading dots are changed to underscores (but current and parent
directories, @file{./} and @file{../} are left alone).  Any remaining
multiple dots are changed to dashes, unless the part before the dot is
shorter than 3 characters and there are more than 1 dot in the filename,
in which case the dot also becomes an underscore.  As a result, e.g.,
@file{.foo.a.b} becomes @file{_foo.a-b}, and @file{sh.lex.c} becomes
@file{sh_lex.c}.

While @code{djtar} is running, if it cannot successfully perform an
exclusive open of the given file (it will refuse to overwrite an
existing file), it will prompt you for a new name.  You may type in
either a complete path, a replacement file name (no directory part), or
just hit return (the file is skipped).

If @code{djtar} is called as @code{djtart}, it behaves as if it were
called with the @samp{-t} switch; when called as @code{djtarx}, it
behaves like @code{djtar -x}.  Thus you can create 2 links to
@file{djtar.exe} which will save you some typing.

By default, @code{djtar} just lists the contents of the archive(s)
given as its arguments.  If you want to extract files, you must use
the @samp{-x} option.

@strong{Options:}

@table @code

@item -x

By default, @code{djtar} just lists the contents of the archive(s)
given as its arguments.  If you want to extract files, you must use
this option, or call @code{djtar} via a link named @code{djtarx}.

@item -t

This option causes @code{djtar} to only print the contents of the tar
file, without actually creating any files.  All the decompression, CRC
checks etc. are still performed; thus, this option can also be used to
test archive integrity.  This is the default behavior of
@code{djtar}, unless you call it via a link named @code{djtarx}.

@item -v

This option modifies the output format slightly to aid in debugging tar
file problems.  It also causes @code{djtar} to emit more verbose warning
messages and print the compression method for compressed archives.

@item -.

Enable the automatic conversion of dots to underscores and dashes.  This
is the default.

@item -!.

Disable the conversion of dots.  You get the control of file renaming when
names of several files clash.

@item -n @file{changeFile}

This option allows you to specify a list of filename conversions ahead of
time.  Thus, you can use @code{djtart} or @code{djtar -t} to list the
files, figure out the new names with your favorite editor, and supply that
file to @code{djtar}.  This way, you have the fullest possible control on
how the extracted files will be named on your system.

The format of the @file{changeFile} file is like this:

@example
dir/dir/dir/old.name.here  dir/dir/dir/newname.hre
dir/dir/dir/old2.name.here  dir/dir/dir/newname2.hre
@end example

The directories must be complete, not relative.  The "old" directories
must match the complete path in the tar file, and the "new" directories
indicate where the file goes on the DOS disk.

@item -d

Convert all text files to DOS text format on output.  This won't usually
affect binary files, but as @code{djtar} detects the file type by looking
at its first 512 bytes, a small possibility of a binary file rendered
useless by this conversion still exists, so you're advised to only use
this option with archives of text files.

By default, @code{djtar} writes all files exactly as it finds them.

@item -u

Convert all text files to UNIX text format on output.  This won't usually
affect binary files, but as @code{djtar} detects the file type by looking
at its first 512 bytes, a small possibility of a binary file rendered
useless by this conversion still exists, so you're advised to only use
this option with archives of text files.

By default, @code{djtar} writes all files exactly as it finds them.

@item -b

Write all files exactly as found in the archive, with no conversions of
text files.  This is the default.
Files written to the console (when @samp{-p} is in effect) are always
written in text mode, so this option doesn't have any effect when used
with @samp{-p}, unless the output of @code{djtar} is redirected to a file
or a pipe.

@item -o @var{string}

Only extract files whose full path names begin with @var{string}.
This option can be used to extract portions of archive.  Files which aren't
extracted will still be shown, but with a string @samp{[ skipped ]}
appended to their names.  When given the @samp{-o} option, @code{djtar}
actually checks if @var{string} is the initial substring of each filename,
so you can specify incomplete file names, thus using @samp{-o} as a poor man's
wildcard facility.

@item -i

Attempt to unpack damaged archives.
By default, @code{djtar} will refuse to create files whose directory
entries in the tar archive fail the checksum test, and any files beyond
that point.  This option tells @code{djtar} to ignore the checksum test
and proceed anyway.  Checksum failure usually means that the tar file is
either corrupted or not in valid tar format, so this option is meant to be
used either with the @samp{-t} option, or in the rare cases when you
@emph{know} for sure the tar file is valid (like if you had to edit it to
change the filenames).

@item -p

When given this switch, @code{djtar} will write the files to its standard
output, which can be piped into another program (like a pager) or
redirected to a file.  This option is designed to allow you to view or
extract individual files (e.g., the @code{README} files) without having to
open the entire archive, and should be used with an appropriate @samp{-o
filename} option.

When this option is used, diagnostic messages will be directed to the
standard error stream (as opposed to standard output in normal operation),
so that they won't get mixed with the files' data.

@end table

@c -----------------------------------------------------------------------------
@node dtou, utod, djtar, Top
@chapter dtou

Usage: @code{dtou} [@code{-b}] [@code{-h}] [@code{-r}] [@code{-s}] [@code{-t}]
[@code{-v}] [@code{-vv}] @file{files}

Each file specified on the command line is converted from dos's CR/LF
text file mode to unix's NL text file mode.

All djgpp wildcards are supported.  Timestamps of the files are preserved.

@code{dtou} will pass an exit status of 0 to the calling context if all the
files have been successfully processed and an exit status greater than 0 if
not.  In this case, the exit status is equal to the amount of unsuccessfully
processed files.  A file has not been successfully processed if some kind of
I/O error occurred.

@strong{Options:}

@table @code

@item -b

Creates a backup of the original file if the file has been modified.
@file{.d2u} is used as backup suffix.  On systems with LFN support, the
backup suffix will be appended to the file name.  If no LFN support is
available the backup suffix will overwrite the original file suffix.

@item -h

Displays a help text and exits.

@item -r

Repair mode.  This mode transforms MSDOS-style EOL (CR/LF) into
UNIX-style EOL (LF).  It ignores Cntl-Z thus it will not truncate the file.
CR sequences in front of LFs are left unchanged.  This mode is intended
for repairing files that have erroneously been transmited in text-mode
instead of binary-mode during a FTP session or with Windows versions of
Netscape which have the bad habit to transfer files with such extensions
as @file{.gz}, @file{.bz2}, @file{.tgz} as text files.

@item -s

Strip mode.  It transforms MSDOS-style EOL (CR/LF) into UNIX-style EOL (LF)
and strips a CR sequence of arbitrary length from a file, if the sequence
followed by a LF.  CR sequences that are not followed by a LF are left
unchanged.  This mode is intended to repair files that have been processed
with buggy ports of Unix software, which always blindly add a CR to a LF,
even if there is already a CR there.

@item -t

Timestamp.  With this option the timestamp of a modified file will not be
preserved.  The timestamp of an unmodified file will always be preserved.

@item -v

Verbose mode.  Prints a single line showing the file name and if file
processing has been successful or not.  The only case that a file is
considered as unsuccessfully processed is if an I/O error has occurred.

@item -vv

Very verbose mode.  Prints the file name and shows the kind of modifications
that have been done to the file.  All possible output looks like:

@example
File: foo.c
File unchanged.
At least one CR/LF to LF transformation occurred.
Warning: At least one CR sequence striped from a LF.
Warning: At least one Cntl-Z has been found. File truncated
         at line n.
Warning: At least one LF without a preceeding CR has been found.
@end example

Of course, not all of the above lines will appear all together.  The first
line showing the file name will always be printed.  If the file has not been
modified at all, then only the next line will be printed.  If the file has
been modified an appropiate combination of the lines 3 to 6 will be printed,
indicating what has been modified.  The above output is of some use, e.g.:
if @code{dtou} reports a LF without a preceeding CR this will be a sure sign
that the file is either binary or has inconsistent EOL format for some other
reason.  If @code{dtou} reports that a Cntl-Z (software EOF) has been found,
then the file will be truncated at that line and the rest of the file will be
lost.

@end table

The program is backward compatible with previous program versions if no options
are given at all.  In this case, an occurrence of Cntl-Z will truncate the file,
MSDOS-style EOL (CR/LF) are transformed into UNIX-style EOL (LF) and CR sequence
stripping will not happen at all.  Also the timestamp will not be alterated and
no backup of the original file will be done.

@c -----------------------------------------------------------------------------
@node utod, gxx, dtou, Top
@chapter utod

Each file specified on the command line is converted from unix's NL text
file mode to dos's CR/LF text file mode.

All djgpp wildcards are supported.  Timestamps of the files are preserved.

@c -----------------------------------------------------------------------------
@node gxx, redir, utod, Top
@chapter gxx

This program is exactly like @code{gcc} (in fact, it @i{calls} gcc), except
that it provides the extra libraries required to link most C++ programs,
including the iostreams, stdc, and libg++ libraries.

@c -----------------------------------------------------------------------------
@node    redir, djsplit, gxx, Top
@chapter redir

DOS, in its many flavors and versions, lacks a decent I/O redirection
mechanism.  Sure, it's got < and > and >>, but what about error
messages?  Lots of people ask, ``How do you send those error messages
to a file?''  Well, you use a program like @code{redir}.

@code{redir} is basically a program that manipulates the standard file
descriptors by copying them, closing and opening them, etc.  Once it
has the file descriptors where it wants them, it runs your program,
which inherits the changed descriptors.  Thus, @code{redir} has nearly
complete control over the input and output of your program.

It also allows you to view the exit code of the program, and the
elapsed time of the program, by supplying the appropriate options on
the command line.

Note that @code{redir} is built with command-line expansion and response files
disabled, so as to allow the application to control that themselves.
This means that you can't use those features to provide @code{redir}'s options
or the command name, but if you use them for the command's options, the
command will do the expansion if it wants to.

The exit code of @code{redir} is 1 if it exits on its own accord, else it
returns the same error code as the program it runs.

Usage: @code{redir} [@code{-i} @var{file}] [@code{-o} @var{file}]
[@code{-oa} @var{file}] [@code{-e} @var{file}] [@code{-ea} @var{file}]
[@code{-eo}] [@code{-oe}] [@code{-x}] [@code{-t}] @var{command}
[@var{args} . . .]

@table @code

@item -i @var{file}
Redirect stdandard input from file

@item -o @var{file}
Redirect standard output to file

@item -oa @var{file}
Append standard output to file

@item -e @var{file}
Redirect standard error to file

@item -ea @var{file}
Append standard error to file

@item -eo
Redirect standard error to standard output

@item -oe
Redirect standard output to standard error

@item -x
Print the exit code of the command after it exits.  If the exit code is
0..255, it is printed as is.  If it is not, the low byte (0..255) is
printed in decimal and the whole value is also printed in hex.

@item -t
Print elapsed time, either in seconds (for short runs) or
hours:minutes:seconds.

@end table

Options are processed in the order they are encountered.  Thus, "-o foo
-eo" means "redirect output to foo, then redirect errors there also",
whereas "-eo -o foo" means "send errors to where output was going, then
move output to foo".


Examples:

To redirect errors to a file:

@example
redir -e errors.lst command ...
@end example

To redirect output to a file, and errors through a pipe:

@example
redir -eo -o prog.out command ... | pipe
@end example

@c -----------------------------------------------------------------------------
@node djsplit, djmerge, redir, Top
@chapter djsplit

The @code{djsplit} and @code{djmerge} programs are designed to assist in
transporting files across unreliable channels or small media (like
floppies).  @code{djsplit} takes a big file and splits it into up to 1000
smaller files.  @code{djmerge} puts them back together again.

Usage: @code{djsplit} @var{inputfile} @var{chunksize} @var{outputbase}

Each output file is made from appending a sequence number to
@var{outputbase}.  For example:

@example
djsplit foo.tgz 1300k footgz
@end example

would result in @code{footgz.000}, @code{footgz.001}, etc.

The @code{chunksize} parameter can be expressed as bytes (NNN),
kilobytes(NNNk) or megabytes (NNNm).  The number NNN @emph{must} be an
integer; for example, @samp{1.1m} will @strong{not} work.

@c -----------------------------------------------------------------------------
@node djmerge, texi2ps, djsplit, Top
@chapter djmerge

The @code{djsplit} and @code{djmerge} programs are designed to assist in
transporting files across unreliable channels or small media (like
floppies).  @code{djsplit} takes a big file and splits it into up to 1000
smaller files.  @code{djmerge} puts them back together again.

Usage: @code{djmerge} @var{inputbase} @var{outputfile}

Each input file is made from appending a sequence number to
@var{inputbase}.  For example, given @code{footgz.000},
@code{footgz.001}, etc,

@example
djmerge footgz foo.tgz
@end example

would result in @code{foo.tgz} being created.

@c -----------------------------------------------------------------------------
@node texi2ps, update, djmerge, Top
@chapter texi2ps

@code{texi2ps} is a modified version of @code{makeinfo} that quickly turns
texinfo files (such as info files are generated from) into crude
Postscript files, ready for printing.  The program is designed to
produce a crude page, so please don't complain if the printed copy looks
ugly.  If you want clean pages, get and install TeX and print it with
that.  It will produce a much cleaner print.  I'm also pretty sure that
texi2ps won't support 100% of the texinfo documents out there.  Again,
if you want it right use TeX.

Note that the input files are @i{texinfo} files, not TeX or LaTeX or
info files.  In normal djgpp distributions, the texinfo files are part
of the source distributions, and the info files are in the binary
distributions.

The default settings produce a pretty densely packed page - small font,
small margins.  You can set the margins and font even smaller to save on
paper, or make them bigger for more conventional manuals.

Usage: @code{texi2ps} [@code{-f} @var{size}] [@code{-I} @var{dir}]
[@code{-I}@var{dir}] [@code{-v}] [@code{-m} @var{pts}] @var{file}

@table @code

@item -f @var{size}

The font size, in points.  The default is 10 points.

@item -I @var{path}

Specifies an additional path to search for include files.

@item -v

Print verbose messages about files read, nodes encountered, and pages
generated.

@item -m @var{pts}

Set the margin size in points.  The default is 54 points, or 3/4 inches
(72 points = 1 inch).

@end table

Note that the Postscript file is sent to standard output, so you must
redirect the output to a file or a printer.

@c -----------------------------------------------------------------------------
@node update, , texi2ps, Top
@chapter update

@code{update} is a fancy copy-if-needed program.  Basically, it compares
the two files you give it, and if they differ, copies one to the other.
This is useful in makefiles where a file is generated often, but its
contents changes rarely, and other files depend on it.  For example,
@code{bison} emits a header file each time it parses the grammar.  The
header rarely changes, but the grammar changes often.  So, you use
@code{update} to copy the header to its real name only when it changes,
and everything else won't need to be recompiled each time.

Usage: @code{update} @var{new_file} @var{copied_to}

Example:

@example
foo.c foo.h : foo.y
        bison foo.y
        update y_tab.h foo.h
        update y_tab.c foo.c
@end example

@bye