.\" This file was originally generated by help2man 1.36, but
.\" hand-edited to combine the pages for h2xml and xml2py together.
.TH ctypeslib 1 "March 2010" "ctypeslib" "User Commands"

.SH NAME
.B h2xml
- convert header files to XML intermediates
.br
.B xml2py
- convert XML intermediates to Python ctypes interface


.SH SYNOPSIS
.B h2xml
.I includefile\fR ... [\fIoptions\fR]
.B -o
.I outputxmlfile
.br
.B xml2py
.I xmlfile\fR ... [\fIoptions\fR]
.B -o
.I outputpyfile

.SH DESCRIPTION

.B
ctypeslib
is a Python code generator capable of converting C header files
into xml files (using gccxml), and then converting the xmlfiles into
Python modules which define a ctypes interface to the corresponding C
library.

Ctypeslib is not ctypes.  Ctypes is included in Python 2.5+ and as an
add-on for lower versions, while ctypeslib is a lesser known add-on
written by the ctypes author.  If you use ctypes a lot and are tired
of setting argtypes and restype of the called functions, you should
look into ctypeslib.  Ctypeslib can also set up data types and
structures from C header files automatically.

.B h2xml
and
.B xml2py
are the user interface scripts to ctypeslib. 
.B h2xml
converts C header files into xml intermediates (using \fBgccxml\fR) and
.B xml2py
converts these intermediates to Python files.  At the minimum, you can
get automatic construction of the C types (structures, etc) in ctypes
definitions.  With extra options, macro definitions can be expanded
and the output Python file can be automatically linked (using ctypes)
to the corresponding C library.

The briefest example is:

.RS
.B h2xml \fIheader.h\fR -o \fIout_c.xml\fR
.br
.B xml2py \fIout_c.xml\fR -o \fIout_c.py\fR
.RE

Key options are 
.B -c
(include C preprocessor headers) to
.B h2xml
and
.B -l
.I library.so
(automatically link to the C library using ctypes) to
.B xml2py\fR.



.SH OPTIONS

.B h2xml
options:
.RS

.TP
\fB\-h\fR, \fB\-\-help\fR
show brief help message
.HP
\fB\-q\fR, \fB\-\-quiet\fR

.TP
\fB\-D\fR NAME[=VALUE]
macros to define
.TP
\fB\-U\fR NAME
macros to undefine
.TP
\fB\-I\fR DIRECTORY
additional include directories
.TP
\fB\-o\fR XMLFILE
XML output filename
.TP
\fB\-c\fR, \fB\-\-cpp\-symbols\fR
try to find #define symbols \- this may give compiler
errors, so it's off by default.
.TP
\fB\-k\fR
don't delete the temporary files created (useful for
finding problems)
.RE



.B xml2py
options:
.RS
.TP
\fB\-h\fR, \fB\-\-help\fR
show this help message and exit
.TP
\fB\-c\fR
include source file location in comments
.TP
\fB\-d\fR
include docstrings containing C prototype and source file
location
.TP
\fB\-k\fR TYPEKIND
kind of type descriptions to include: d = #defines, e =
enumerations, f = functions, s = structures, t = typedefs
.TP
\fB\-l\fR DLLS
libraries to search for exported functions
.TP
\fB\-o\fR OUTPUT
output filename (if not specified, standard output will be
used)
.TP
\fB\-r\fR EXPRESSION
regular expression for symbols to include (if neither symbols
nor expressions are specified,everything will be included)
.TP
\fB\-s\fR SYMBOL
symbol to include (if neither symbols nor expressions are
specified,everything will be included)
.TP
\fB\-v\fR
verbose output
.TP
\fB\-w\fR
add all standard windows dlls to the searched dlls list
.TP
\fB\-m\fR module
Python module(s) containing symbols which will be imported
instead of generated
.TP
\fB\-\-preload\fR=\fIDLL\fR
dlls to be loaded before all others (to resolve symbols)
.TP
\fB\-h\fR, \fB\-\-help\fR
show this help message and exit
.TP
\fB\-c\fR
include source file location in comments
.TP
\fB\-d\fR
include docstrings containing C prototype and source file
location
.TP
\fB\-k\fR TYPEKIND
kind of type descriptions to include: d = #defines, e =
enumerations, f = functions, s = structures, t = typedefs
.TP
\fB\-l\fR DLLS
libraries to search for exported functions
.TP
\fB\-o\fR OUTPUT
output filename (if not specified, standard output will be
used)
.TP
\fB\-r\fR EXPRESSION
regular expression for symbols to include (if neither symbols
nor expressions are specified,everything will be included)
.TP
\fB\-s\fR SYMBOL
symbol to include (if neither symbols nor expressions are
specified,everything will be included)
.TP
\fB\-v\fR
verbose output
.TP
\fB\-w\fR
add all standard windows dlls to the searched dlls list
.TP
\fB\-m\fR module
Python module(s) containing symbols which will be imported
instead of generated
.TP
\fB\-\-preload\fR=\fIDLL\fR
dlls to be loaded before all others (to resolve symbols)

.RE




.SH "EXAMPLES"

Please see
.I /usr/share/doc/python-ctypeslib/examples.Debian
for examples and explanation.




.SH "SEE ALSO"
.I /usr/share/doc/python-ctypeslib/examples.Debian
contains a brief tutorial on some key features

Python docstrings (\fBpydoc ctypeslib\fR)

Ctypeslib upstream is
.I http://python.net/crew/theller/ctypes/
(see "Related Projects").

For ctypes information, see
.I http://docs.python.org/library/ctypes.html



.SH "AUTHOR"
.B ctypeslib
was written by Thomas Heller <theller@ctypes.org>.
.PP
This manual page was written by Richard Darst <rkd@zgib.net>,
for the Debian project (and may be used by others).