DJGPP Utilities Reference

Copyright © 1995 DJ Delorie (dj@delorie.com)

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

1 bin2h

bin2h allows a developer to embed a binary file into a source file, bu converting the binary data to an array of integer values.

Usage: bin2h ‘datafile’ symbol ‘headerfile’

The resulting header file has a format like this:

unsigned char symbol[] = {
  ... data ...
};

2 djtar

Usage: djtar [-n ‘changeFile’] [-o ‘dir’] [-t|-x] [-i] [-v] [-p] [-.|-!.] [-d|-u|-b] ‘tarfile’

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 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.

djtar can read compressed tar files and decompress them on the fly. (This can be also achieved by piping the output of gzip to djtar, but for very large archives you can run out of free disk space, because DOS implements pipes as temporary disk files.) djtar knows about all the compression methods supported by gzip, namely, deflation (aka LZ77, either by gzip, by zip, or by pkzip), LZW compression (by compress), LZH compression (as with compress -H available with some versions of compress), or Huffman compression (by pack). Tar files compressed with zip or pkzip can be decompressed by djtar only if the ‘.zip’ file contains a single tar file compressed with either the deflation or stored (i.e., uncompressed, like with ‘pkzip -e0’) methods; if more than a single tar file was put into a compressed zip file, files beyond the first one will be ignored by djtar (a message to this effect will be printed under -v option).

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 djtar with such archives, specify a name of the drive (like A:) as a tarfile argument.

When extracting files from compressed archives, 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 gzip. Some of the diagnostics are only printed under the verbose operation switched on by the -v switch. Unless you use the -i switch, 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 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 -u and -d options can change that.

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 ‘.info-N’ becomes ‘.iN’. Any file ending in ‘.tar.gz’ becomes ‘.tgz’. Any file with ‘++’ becomes ‘plus’. Any leading dots are changed to underscores (but current and parent directories, ‘./’ and ‘../’ 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., ‘.foo.a.b’ becomes ‘_foo.a-b’, and ‘sh.lex.c’ becomes ‘sh_lex.c’.

While 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 djtar is called as djtart, it behaves as if it were called with the -t switch; when called as djtarx, it behaves like djtar -x. Thus you can create 2 links to ‘djtar.exe’ which will save you some typing.

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

Options:

-x

By default, 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 djtar via a link named djtarx.

-t

This option causes 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 djtar, unless you call it via a link named djtarx.

-v

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

-.

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

-!.

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

-n ‘changeFile’

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

The format of the ‘changeFile’ file is like this:

dir/dir/dir/old.name.here  dir/dir/dir/newname.hre
dir/dir/dir/old2.name.here  dir/dir/dir/newname2.hre

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.

-d

Convert all text files to DOS text format on output. This won’t usually affect binary files, but as 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, djtar writes all files exactly as it finds them.

-u

Convert all text files to UNIX text format on output. This won’t usually affect binary files, but as 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, djtar writes all files exactly as it finds them.

-b

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

-o ‘dir’

Only extract files which are children of the given directory ‘dir’. This option can be used to extract portions of archive. Files which aren’t extracted will still be shown, but with a string [ skipped ] appended to their names. When given the -o option, djtar actually checks if ‘dir’ is contained in filenames as a substring, so you can specify incomplete directory names, thus using it as a poor man’s wildcard facility.

-i

By default, 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 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 -t option, or in the rare cases when you know for sure the tar file is valid (like if you had to edit it to change the filenames).

-p

When given this switch, 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 README files) without having to open the entire archive, and should be used with an appropriate -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.

3 dtou

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.

4 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.

5 echo

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

Usage: echo [-n] [-o file] stuff . . .

-n

Do not emit the trailing newline after printing the text.

-o file

Send output to a file.

The purpose of this program is to be able to interact directly with make’s ability to pass long command lines to programs. If you use redirection, you aren’t always able to handle long command lines. With echo, you can, and you can use the -o option to redirect output to a file (and use the file later as a response file) without using dos’s redirection.

6 gxx

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

7 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 redir.

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, 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 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 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 redir is 1 if it exits on its own accord, else it returns the same error code as the program it runs.

Usage: redir [-i file] [-o file] [-oa file] [-e file] [-ea file] [-eo] [-oe] [-x] [-t] command [args . . .]

-i file

Redirect stdandard input from file

-o file

Redirect standard output to file

-oa file

Append standard output to file

-e file

Redirect standard error to file

-ea file

Append standard error to file

-eo

Redirect standard error to standard output

-oe

Redirect standard output to standard error

-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.

-t

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

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:

redir -e errors.lst command ...

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

redir -eo -o prog.out command ... | pipe

8 split

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

Usage: split inputfile chunksize outputbase

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

split foo.tgz 1300k footgz

would result in footgz.000, footgz.001, etc.

The chunksize parameter can be expressed as bytes (NNN), kilobytes(NNNk) or megabytes (NNNm).

9 merge

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

Usage: split inputbase outputfile

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

merge footgz foo.tgz

would result in foo.tgz being created.

10 texi2ps

texi2ps is a modified version of 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 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: texi2ps [-f size] [-I dir] [-Idir] [-v] [-m pts] file

-f size

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

-I path

Specifies an additional path to search for include files.

-v

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

-m pts

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

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

11 update

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, bison emits a header file each time it parses the grammar. The header rarely changes, but the grammar changes often. So, you use 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: update new_file copied_to

Example:

foo.c foo.h : foo.y
        bison foo.y
        update y_tab.h foo.h
        update y_tab.c foo.c

About This Document

This document was generated on June 1, 2025 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on June 1, 2025 using texi2html 5.0.