Subversion Repositories pentevo

.TH pbind 1

.SH NAME
.B pbind \- recombine output files generated by AS

.SH SYNTAX
.B pbind
[ option(s) ] <name(s)> [ further options/names ]

.SH DESCRIPTION

BIND is a tool to combine code files generated by the AS cross
assembler to a single file or to extract records out of a code file. 
.B pbind
is the Unix/C implementation of BIND.  BIND is 
.B not
a linker; AS does not generate linkable code!  

Arguments to BIND can be either file name specifications or
command line parameters; any argument starting with a plus(+), minus(-)
or slash(/) is recognized as a parameter; anything else is regarded as 
a file name.  BIND always regards the last name as the target file's name
specification; all other files are regarded as source files.  A target
name and no source will yield an empty target file, whereas no file name
at all will result in an error message.  File names that do not have an
extension will be expanded with '.p', the standard extension for code
files.

The way BIND operates is to process source files in the order they are given
in the command line, reading record by record, and to write records that fit
into the given filtering criteria to the target file.  After all source files
have been processed, BIND will write a new creator entry to the target file.

.SH COMMAND-LINE PARAMETERS

If a command-line parameter starts with a slash(/) or minus sign(-), it
turns an option on; if a command-line parameter starts with a plus sign(+),
it turns a specific option off.  Numeric arguments to parameters can be
either written in decimal or hexadecimal notation.  For hexadecimal notation,
prefix the number with a dollar($) sign.

.B pbind
accepts the following command-line parameters:
.TP
.B -f <number>[,<further numbers>]
Add <number> to the list of record header IDs that allow a record from a source
file to be written to the target file.  A certain header ID marks code for a certain
target processor family; thus, this filter allows to distill code for a certain
processor out of a source file that contains code for different processor families.
Negation of this parameter removes certain header IDs from BIND's list.  See
the user manual of AS for a list of all possible header ID values.  If BIND's list
of header IDs is empty, no filtering will take place, i.e. all records from a source
file will make it into the target file.
.TP
.B -q or -quiet

Enable quiet operation mode, suppressing copyright and purely informative
messages.  Only errors will be displayed.

.SH PRESETTING PARAMETERS

Parameters need not neccessarily be given in the command line itself.  Before
processing of command line parameters starts, BIND will look if the
.B BINDCMD
environment variable is defined.  If it exists, its contents will be
treated as additional command line paramters whose syntax is absolutely 
equal to normal command line parameters.  As exception is made if the 
variable's contents start with a '@' sign; in such a case, the string after
the '@' sign is treated as the name of a file that contains the options.
Such a file (also called a 'key file') has the advantage that it allows
the options to be written in different lines, and it does not have a size
limit.  Some operating systems (like MS-DOS) do have a length limit on 
command lines and environment variable contents, so the key file may be
your only option if you have a lot of lengthy parameters for BIND.

.SH RETURN CODES

.B pbind
may return with the following codes:
.TP
.B 0
no errors.
.TP
.B 1
incorrect command line parameters.
.TP
.B 2
I/O-error.
.TP
.B 3
An input file had an incorrect format.

.SH EXAMPLES

To combine all records of 
.B src1.p
and
.B src2.p
into a single file
.B dest.p,
use:
.PP
.B pbind src1 src2 dest
.PP
To extract all records with MCS-51-code from a file
.B mixed.p,
use
.PP
.B pbind -f \e$31 mixed only51,
.PP
and the record will be written to a file
.B only51.p.
Notice that the dollar sign in this example had to be protected with a backslash
sign, as a UNIX shell uses the dollar character for expansion of variables.  This
would not have been necessary on an OS/2 or MS-DOS system (it would result in
an error).

.SH NATIONAL LANGUAGE SUPPORT

pbind supports national languages in the same way as AS.  See the manual
page for asl(1) for more information about this.

.SH TIPS

Calling BIND without any arguments will print a short help
listing all command line parameters.

.SH SEE ALSO

asl(1), plist(1), p2hex(1), p2bin(1)

.SH HISTORY

BIND originally appeared as an AS tool in 1992, written in
Borland-Pascal, and was ported to C and UNIX in 1997.

.SH BUGS

Command line interpreters of some operating systems reserve some 
characters for their own use, so it might be necessary to give
command line parameters with certain tricks (e.g., with the help
of escape characters).

BIND does not have so far an opportunity to filter records by
target segment.

.SH AUTHOR(S)

Alfred Arnold (alfred@ccac.rwth-aachen.de)