fpc/install/man/man1/h2pas.1

.TH h2pas 1 "12 Dec 1999" "Free Pascal" "Free Pascal C header conversion utility"
.SH NAME
h2pas \- The C header to pascal unit conversion program.

.SH SYNOPSIS

.B h2pas
.I "[options] filename"

.SH DESCRIPTION

.B h2pas
attempts to convert a C header file to a pascal unit. 
it can handle most C constructs that one finds in a C header file,
and attempts to translate them to their pascal counterparts. see the 
.B CONSTRUCTS
section for a full description of what the translator can handle.

.SH USAGE

H2pas is a command-line tool that translates a C header file to a spascal
unit. It reads the C header file and translates the C declarations to
equivalent pascal declarations that can be used to access code written in C.

The output of the h2pas program is written to a file with the same name as
the C header file that was used as input, but with the extension \fI.pp\fP.
The output file that h2pas creates can be customized in a number of ways by
means of many options.

.SH OPTIONS

The output of 
.B h2pas
can be controlled with the following options:


.TP
.B \-d 
use 
.I external;
for all procedure and function declarations.
.TP
.B \-D 
use 
.B external
.I libname 
.B name
.I 'func\_name'
for function and procedure declarations.
.TP
.B \-e 
Emit a series of constants instead of an enumeration type for the C 
.I enum
construct.
.TP
.B \-i
create an include file instead of a unit (omits the unit header).
.TP
.BI \-l " libname"
specify the library name for external function declarations.
.TP
.BI \-o " outfile"
Specify the output file name. Default is the input file name with 
the extension replaced by 
.I ".pp"
"."
.TP
.B \-p
use the letter  
.B P
in front of pointer type parameters instead of "^".
.TP
.B \-s
Strip comments from the input file. By default comments are converted
to comments, but they may be displaced, since a comment is handled by the
scanner.
.TP
.B \-t
prepend typedef type names with the letter
.B T
(used to follow Borland's convention that all types should be defined with
T).
.TP
.B \-v
replace pointer parameters by call by reference parameters.
Use with care because some calls can expect a NIL pointer.
.TP
.B \-w
Header file is a win32 header file (adds support for some special macros).
.TP
.B \-x
handle SYS\_TRAP of the PalmOS header files.

.SH CONSTRUCTS
The following C declarations and statements are recognized:

.TP
.B defines
defines are changed into pascal constants if they are simple defines.
macros are changed - wherever possible to functions; however the arguments
are all integers, so these must be changed manually. Simple expressions 
in define staments are recognized, as are most arithmetic operators: 
addition, substraction, multiplication, division, logical operators, 
comparision operators, shift operators. The C construct ( A ? B : C)
is also recognized and translated to a pascal construct with an IF
statement (this is buggy, however).

.TP
.B "preprocessor statements"
the conditional preprocessing commands are recognized and translated into
equivalent pascal compiler directives. The special 
.B "#ifdef \_\_cplusplus"
is also recognized and removed.


.TP
.B typedef
A typedef statement is changed into a pascal type statement. The following
basic types are recognized:
.RS
.TP
.I char
changed to char.
.TP
.I float
changed to real (=double in free pascal).
.TP
.I int
changed to longint.
.TP
.I long
changed to longint.
.TP 
.I "long int"
changed to longint.
.TP
.I short
changed to integer.
.TP
.I unsigned
changed to cardinal.
.TP
.I "unsigned char"
changed to byte.
.TP 
.I "unsigned int"
changed to cardinal.
.TP
.I "unsigned long int"
changed to cardinal.
.TP
.I "unsigned short"
changed to word.
.TP 
.I void
ignored.
.RE
These types are also changed if they appear in the arguments of a function
or procedure.
.TP 
.B "functions and procedures"
functions and procedures are translated as well; pointer types may be
changed to call by reference arguments (using the 
.B var
argument) by using the 
.B \-p
command line argument. functions that have a variable number of arguments
are changed to a function with an 
.B "array of const"
argument.
.TP
.B specifiers
the 
.I extern
specifier is recognized; however it is ignored. the
.I packed
specifier is also recognised and changed with the
.I PACKRECORDS
directive. The 
.I const
specifier is also recognized, but is ignored.

.TP
.B modifiers
If the 
.B \-w 
option is specified, then the following modifiers are recognized:
.I STDCALL
, 
.I CDECL
, 
.I CALLBACK
, 
.I PASCAL
, 
.I WINAPI
, 
.I APIENTRY
, 
.I WINGDIAPI
as defined in the win32 headers.
If additionally the
.B \-x
option is specified then the 
.I SYS\_TRAP
specifier is also recognized.

.TP
.B enums
enum constructs are changed into enumeration types; bear in mind that in C
enumeration types can have values assigned to them; Free Pascal also allows
this to a certain degree. If you know that values are assigned to enums, it
is best to use the 
.B \-e
option to change the enus to a series of integer constants.

.TP 
.B unions
unions are changed to variant records. 

.TP
.B structs
are changed to pascal records, with 
.B C
packing.

.IP 

.SH SEE ALSO
.IP 
.BR  ppc386 (1)
.BR  ppumove (1)