=================================================================== RCS file: /cvs/djgpp/djgpp/src/utils/utils.tex,v retrieving revision 1.18 retrieving revision 1.19 diff -p -u -r1.18 -r1.19 --- djgpp/src/utils/utils.tex 2001/10/05 20:52:50 1.18 +++ /cvs/djgpp/djgpp/src/utils/utils.tex 2003/01/21 03:39:31 1.19 @@ -10,7 +10,7 @@ @ifinfo This is the reference manual for DJGPP V2's miscellaneous utilities -Copyright (c) 1995 DJ Delorie +Copyright (c) 1995,2003 DJ Delorie @end ifinfo @titlepage @@ -19,7 +19,7 @@ Copyright (c) 1995 DJ Delorie @center @titlefont{DJGPP Utilities Reference} @vskip 0pt plus 1filll -Copyright @copyright{} 1995 @email{dj@@delorie.com, DJ Delorie} +Copyright @copyright{} 1995,2003 @email{dj@@delorie.com, DJ Delorie} @end titlepage @c ----------------------------------------------------------------------------- @@ -52,20 +52,29 @@ come with DJGPP. * update:: conditionally copy one file to another. -* djasm:: The DJGPP 16-bit assembler. - * getconf:: Get system-dependent configuration values. +* go32-v2:: Run unstubbed COFF images +* stubify:: Add DOS executable stub to COFF images +* stubedit:: Modify the executable stub parameters +* exe2coff:: Strip the DOS executable stub and create COFF image +* coff2exe:: Convert COFF image to EXE image (see stubify) + +* dxegen:: Create Dynamic Executable file + +* djasm:: The DJGPP 16-bit assembler. + @end menu @c ----------------------------------------------------------------------------- @node bin2h, djecho, , Top -@chapter bin2h +@chapter @command{bin2h} +@pindex @command{bin2h} -@code{bin2h} allows a developer to embed a binary file into a source +@command{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} +Usage: @kbd{bin2h datafile symbol headerfile} The resulting header file has a format like this: @@ -77,7 +86,8 @@ unsigned char symbol[] = @{ @c ----------------------------------------------------------------------------- @node djecho, djtar, bin2h, Top -@chapter djecho +@chapter @command{djecho} +@pindex @command{djecho} This program simply echoes whatever is given to it on the command line. @@ -109,83 +119,84 @@ 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 +@command{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 +@command{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 +Latest versions of ported @command{make} do not invoke @file{command.com} +for redirection and @command{echo} commands, but @command{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 +single invocation. Since @command{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 +@chapter @command{djtar} +@pindex @command{djtar} Usage: @code{djtar} [@code{-n} @file{changeFile}] [@code{-e} @file{dir}] [@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 +@command{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} +illegal characters make regular tar programs useless. What @command{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 +@command{djtar} can read compressed tar files and decompress them on the +fly. (This can be also achieved by piping the output of @command{gzip} to +@command{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}). +@command{djtar} knows about all the compression methods supported by +@command{gzip}, namely, deflation (by @command{gzip}), LZW compression +(by @command{compress}), LZH compression (as with @command{compress -H} +available with some versions of @command{compress}), or Huffman compression +(by @command{pack}). -@code{djtar} can decompress @file{.tar} archive files compressed with -@code{bzip2}, even if several of such @code{bzip2}-compressed +@command{djtar} can decompress @file{.tar} archive files compressed with +@command{bzip2}, even if several of such @command{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 +@command{djtar} can decompress files compressed with @command{zip} or +@command{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 +@command{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 +filesystem). To use @command{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 +When extracting files from compressed archives, @command{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 +performed by @command{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 +the @samp{-i} switch, @command{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 +An additional bonus of using @command{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} will +@samp{-u} and @samp{-d} options can change that. @command{djtar} will always convert DOS batch files to DOS-style text files, if they have been stored as UNIX-style text files. This is because @file{command.com} refuses to run batch files that contain UNIX-style EOLs. -@code{djtar} performs a number of file name conversions in an attempt +@command{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 @@ -201,18 +212,18 @@ in which case the dot also becomes an un @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 +While @command{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 +If @command{djtar} is called as @command{djtart}, it behaves as if it were +called with the @samp{-t} switch; when called as @command{djtarx}, it +behaves like @command{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) +By default, @command{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. @@ -222,22 +233,22 @@ the @samp{-x} option. @item -x -By default, @code{djtar} just lists the contents of the archive(s) +By default, @command{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}. +this option, or call @command{djtar} via a link named @command{djtarx}. @item -t -This option causes @code{djtar} to only print the contents of the tar +This option causes @command{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}. +@command{djtar}, unless you call it via a link named @command{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 +file problems. It also causes @command{djtar} to emit more verbose warning messages and print the compression method for compressed archives. @item -. @@ -253,9 +264,9 @@ 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 +time. Thus, you can use @command{djtart} or @command{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 +file to @command{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: @@ -274,22 +285,22 @@ specified, the ``old'' one and all its s @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 +affect binary files, but as @command{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. +By default, @command{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 +affect binary files, but as @command{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. +By default, @command{djtar} writes all files exactly as it finds them. @item -b @@ -297,7 +308,7 @@ Write all files exactly as found in the 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 +with @samp{-p}, unless the output of @command{djtar} is redirected to a file or a pipe. @item -e @var{string} @@ -312,7 +323,7 @@ other ways @samp{-e} is similar to @samp 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} +appended to their names. When given the @samp{-o} option, @command{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. You may specify multiple @samp{-o} options to extract @@ -321,9 +332,9 @@ several different directories and files. @item -i Attempt to unpack damaged archives. -By default, @code{djtar} will refuse to create files whose directory +By default, @command{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 +that point. This option tells @command{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 @@ -332,10 +343,10 @@ change the filenames). @item -p -When given this switch, @code{djtar} will write the files to its standard +When given this switch, @command{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 +extract individual files (e.g., the @file{README} files) without having to open the entire archive, and should be used with an appropriate @samp{-o filename} option. @@ -347,7 +358,8 @@ so that they won't get mixed with the fi @c ----------------------------------------------------------------------------- @node dtou, utod, djtar, Top -@chapter dtou +@chapter @command{dtou} +@pindex @command{dtou} Usage: @code{dtou} [@code{-b}] [@code{-h}] [@code{-r}] [@code{-s}] [@code{-t}] [@code{-v}] [@code{-vv}] @file{files} @@ -357,7 +369,7 @@ text file mode to unix's NL text file mo 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 +@command{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 @@ -428,9 +440,9 @@ line showing the file name will always b 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 +if @command{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, +reason. If @command{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. @@ -444,7 +456,8 @@ no backup of the original file will be d @c ----------------------------------------------------------------------------- @node utod, gxx, dtou, Top -@chapter utod +@chapter @command{utod} +@pindex @command{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. @@ -453,38 +466,40 @@ All djgpp wildcards are supported. Time @c ----------------------------------------------------------------------------- @node gxx, redir, utod, Top -@chapter gxx +@chapter @command{gxx} +@pindex @command{gxx} -This program is exactly like @code{gcc} (in fact, it @i{calls} gcc), except +This program is exactly like @command{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 +@chapter @command{redir} +@pindex @command{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}. +to a file?'' Well, you use a program like @command{redir}. -@code{redir} is basically a program that manipulates the standard file +@command{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 +which inherits the changed descriptors. Thus, @command{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 +Note that @command{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 +This means that you can't use those features to provide @command{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 +The exit code of @command{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}] @@ -548,12 +563,13 @@ redir -eo -o prog.out command ... | pipe @c ----------------------------------------------------------------------------- @node djsplit, djmerge, redir, Top -@chapter djsplit +@chapter @command{djsplit} +@pindex @command{djsplit} -The @code{djsplit} and @code{djmerge} programs are designed to assist in +The @command{djsplit} and @command{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. +floppies). @command{djsplit} takes a big file and splits it into up to 1000 +smaller files. @command{djmerge} puts them back together again. Usage: @code{djsplit [-t] @var{inputfile} @var{chunksize} @var{outputbase}} @@ -564,41 +580,42 @@ Each output file is made from appending djsplit foo.tgz 1300k footgz @end example -would result in @code{footgz.000}, @code{footgz.001}, etc. +would result in @file{footgz.000}, @file{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. -By default, @code{djsplit} creates the output files +By default, @command{djsplit} creates the output files @file{@var{outputbase}.@var{nnn}} with the same time stamp and mode bits -as the original file @file{@var{inputfile}}. (@code{djmerge} will then +as the original file @file{@var{inputfile}}. (@command{djmerge} will then recreate the file's time and modes as they originally were.) If you want the output files to have the current time and the default attribute bits, use the @samp{-t} switch. @c ----------------------------------------------------------------------------- @node djmerge, texi2ps, djsplit, Top -@chapter djmerge +@chapter @command{djmerge} +@pindex @command{djmerge} -The @code{djsplit} and @code{djmerge} programs are designed to assist in +The @command{djsplit} and @command{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. +floppies). @command{djsplit} takes a big file and splits it into up to 1000 +smaller files. @command{djmerge} puts them back together again. Usage: @code{djmerge [-t] @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, +@var{inputbase}. For example, given @file{footgz.000}, +@file{footgz.001}, etc, @example djmerge footgz foo.tgz @end example -would result in @code{foo.tgz} being created. +would result in @file{foo.tgz} being created. -By default, @code{djmerge} creates the output file +By default, @command{djmerge} creates the output file @file{@var{outputfile}} with the same time stamp and mode bits as the first file @file{@var{inputbase}.000}. If you want the output file to have the current time and the default attribute bits, use the @samp{-t} @@ -606,9 +623,10 @@ switch. @c ----------------------------------------------------------------------------- @node texi2ps, update, djmerge, Top -@chapter texi2ps +@chapter @command{texi2ps} +@pindex @command{texi2ps} -@code{texi2ps} is a modified version of @code{makeinfo} that quickly turns +@command{texi2ps} is a modified version of @command{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 @@ -656,15 +674,16 @@ redirect the output to a file or a print @c ----------------------------------------------------------------------------- @node update, getconf, texi2ps, Top -@chapter update +@chapter @command{update} +@pindex @command{update} -@code{update} is a fancy copy-if-needed program. Basically, it compares +@command{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 +@command{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, +@command{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} @@ -678,7 +697,7 @@ foo.c foo.h : foo.y update y_tab.c foo.c @end example -Another use of @code{update} might be to validate (and replace if +Another use of @command{update} might be to validate (and replace if necessary) a local copy of some master data file: @example @@ -687,15 +706,15 @@ foo.dat: /master/data/foo.dat [ -f $@@ ] && cmp -s $< $@@ || cp -f $< $@@ && touch $@@ @end example -@code{update} is similar to the GNU-standard shell script +@command{update} is similar to the GNU-standard shell script @code{move-if-change} that comes with some GNU packages (e.g., GCC, binutils). The two are @emph{not} functionally equivalent, however; in particular, @code{move-if-change} always @strong{removes} the source file in the process of updating the target, -whereas @code{update} leaves the source file intact. +whereas @command{update} leaves the source file intact. -If you need a portable replacement for @code{update}, +If you need a portable replacement for @command{update}, there are several options: @itemize @bullet @@ -723,18 +742,19 @@ Copy source to target only if target dif @end itemize -An important feature of @code{update} is that @var{copied_to} +An important feature of @command{update} is that @var{copied_to} is created with the current timestamp. -If you are certain that @code{cp} on your system is not aliased -to @code{cp -p} or @code{cp --preserve} (to preserve timestamps), +If you are certain that @command{cp} on your system is not aliased +to @command{cp -p} or @command{cp --preserve} (to preserve timestamps), then you can omit the @samp{&& touch @var{copied_to}} bit in the above command strings. @c ----------------------------------------------------------------------------- @node getconf, djasm, update, Top -@chapter getconf +@chapter @command{getconf} +@pindex @command{getconf} -@code{getconf} writes the value of configuration dependent variables to +@command{getconf} writes the value of configuration dependent variables to standard output. Usage: @code{getconf} [@code{-v} @var{specification}] [@code{-h}] @@ -768,9 +788,13 @@ getconf -v POSIX_V6_ILP32_OFF32 PATH getconf NAME_MAX c:/djgpp @end example +@include ../stub/stubdocs.txi +@include ../dxe/dxegen.txi + @c ----------------------------------------------------------------------------- @node djasm, , getconf, Top -@chapter djasm +@chapter @command{djasm} +@pindex @command{djasm} @lowersections @include djasm.txi