H2XS(1)								       H2XS(1)

NAME    [Toc]    [Back]

     h2xs - convert .h C header	files to Perl extensions

SYNOPSIS    [Toc]    [Back]

     h2xs [-AOPXcdf] [-v version] [-n module_name] [-p prefix] [-s sub]
     [headerfile [extra_libraries]]

     h2xs -h

DESCRIPTION    [Toc]    [Back]

     h2xs builds a Perl	extension from any C header file.  The extension will
     include functions which can be used to retrieve the value of any #define
     statement which was in the	C header.

     The module_name will be used for the name of the extension.  If
     module_name is not	supplied then the name of the header file will be
     used, with	the first character capitalized.

     If	the extension might need extra libraries, they should be included
     here.  The	extension Makefile.PL will take	care of	checking whether the
     libraries actually	exist and how they should be loaded.  The extra
     libraries should be specified in the form -lm -lposix, etc, just as on
     the cc command line.  By default, the Makefile.PL will search through the
     library path determined by	Configure.  That path can be augmented by
     including arguments of the	form -L/another/library/path in	the extralibraries
 argument.

OPTIONS    [Toc]    [Back]

     -A	  Omit all autoload facilities.	 This is the same as -c	but also
	  removes the require AutoLoader statement from	the .pm	file.

     -F	  Additional flags to specify to C preprocessor	when scanning header
	  for function declarations. Should not	be used	without	-x.

     -O	  Allows a pre-existing	extension directory to be overwritten.

     -P	  Omit the autogenerated stub POD section.

     -X	  Omit the XS portion.	Used to	generate templates for a module	which
	  is not XS-based.

     -c	  Omit constant() from the .xs file and	corresponding specialised
	  AUTOLOAD from	the .pm	file.

     -d	  Turn on debugging messages.

     -f	  Allows an extension to be created for	a header even if that header
	  is not found in /usr/include.

     -h	  Print	the usage, help	and version for	this h2xs and exit.





									Page 1






H2XS(1)								       H2XS(1)



     -n	module_name
	  Specifies a name to be used for the extension, e.g., -n RPC::DCE

     -p	prefix
	  Specify a prefix which should	be removed from	the Perl function
	  names, e.g., -p sec_rgy_ This	sets up	the XS PREFIX keyword and
	  removes the prefix from functions that are autoloaded	via the
	  constant() mechansim.

     -s	sub1,sub2
	  Create a perl	subroutine for the specified macros rather than
	  autoload with	the constant() subroutine.  These macros are assumed
	  to have a return type	of char	*, e.g.,
	  -s sec_rgy_wildcard_name,sec_rgy_wildcard_sid.

     -v	version
	  Specify a version number for this extension.	This version number is
	  added	to the templates.  The default is 0.01.

     -x	  Automatically	generate XSUBs basing on function declarations in the
	  header file.	The package C::Scan should be installed. If this
	  option is specified, the name	of the header file may look like
	  NAME1,NAME2. In this case NAME1 is used instead of the specified
	  string, but XSUBs are	emitted	only for the declarations included
	  from file NAME2.

	  Note that some types of arguments/return-values for functions	may
	  result in XSUB-declarations/typemap-entries which need hand-editing.
	  Such may be objects which cannot be converted	from/to	a pointer
	  (like	long long), pointers to	functions, or arrays.

EXAMPLES    [Toc]    [Back]

	     # Default behavior, extension is Rusers
	     h2xs rpcsvc/rusers

	     # Same, but extension is RUSERS
	     h2xs -n RUSERS rpcsvc/rusers

	     # Extension is rpcsvc::rusers. Still finds	<rpcsvc/rusers.h>
	     h2xs rpcsvc::rusers

	     # Extension is ONC::RPC.  Still finds <rpcsvc/rusers.h>
	     h2xs -n ONC::RPC rpcsvc/rusers

	     # Without constant() or AUTOLOAD
	     h2xs -c rpcsvc/rusers

	     # Creates templates for an	extension named	RPC
	     h2xs -cfn RPC

	     # Extension is ONC::RPC.
	     h2xs -cfn ONC::RPC



									Page 2






H2XS(1)								       H2XS(1)



	     # Makefile.PL will	look for library -lrpc in
	     # additional directory /opt/net/lib
	     h2xs rpcsvc/rusers	-L/opt/net/lib -lrpc

	     # Extension is DCE::rgynbase
	     # prefix "sec_rgy_" is dropped from perl function names
	     h2xs -n DCE::rgynbase -p sec_rgy_ dce/rgynbase

	     # Extension is DCE::rgynbase
	     # prefix "sec_rgy_" is dropped from perl function names
	     # subroutines are created for sec_rgy_wildcard_name and sec_rgy_wildcard_sid
	     h2xs -n DCE::rgynbase -p sec_rgy_ \
	     -s	sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase

	     # Make XS without defines in perl.h, but with function declarations
	     # visible from perl.h. Name of the	extension is perl1.
	     # When scanning perl.h, define -DEXT=extern -DdEXT= -DINIT(x)=
	     # Extra backslashes below because the string is passed to shell.
	     # Note that a directory with perl header files would
	     #	be added automatically to include path.
	     h2xs -xAn perl1 -F	"-DEXT=extern -DdEXT= -DINIT\(x\)=" perl.h

	     # Same with function declaration in proto.h as visible from perl.h.
	     h2xs -xAn perl2 perl.h,proto.h

ENVIRONMENT    [Toc]    [Back]

     No	environment variables are used.

AUTHOR    [Toc]    [Back]

     Larry Wall	and others

SEE ALSO    [Toc]    [Back]

     the perl manpage, the perlxstut manpage, the ExtUtils::MakeMaker manpage,
     and the AutoLoader	manpage.

DIAGNOSTICS    [Toc]    [Back]

     The usual warnings	if it cannot read or write the files involved.

















									Page 3






H2XS(1)								       H2XS(1)


									PPPPaaaaggggeeee 4444