EditPageHistoryDiffInfoLikePages

Annotated edit history of perlxs(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	PERLXS
		2	!!!PERLXS
		3	NAME
		4	DESCRIPTION
		5	EXAMPLES
		6	XS VERSION
		7	AUTHOR
		8	----
		9	!!NAME
		10
		11
		12	perlxs - XS language reference manual
		13	!!DESCRIPTION
		14
		15
		16	__Introduction__
		17
		18
		19	XS is an interface description file format
		20	used to create an extension interface between Perl and C
		21	code (or a C library) which one wishes to use with Perl. The
		22	XS interface is combined with the library to
		23	create a new library which can then be either dynamically
		24	loaded or statically linked into perl. The XS
		25	interface description is written in the XS
		26	language and is the core component of the Perl extension
		27	interface.
		28
		29
		30	An __XSUB__ forms the basic unit of the
		31	XS interface. After compilation by the
		32	__xsubpp__ compiler, each XSUB amounts to
		33	a C function definition which will provide the glue between
		34	Perl calling conventions and C calling
		35	conventions.
		36
		37
		38	The glue code pulls the arguments from the Perl stack,
		39	converts these Perl values to the formats expected by a C
		40	function, call this C function, transfers the return values
		41	of the C function back to Perl. Return values here may be a
		42	conventional C return value or any C function arguments that
		43	may serve as output parameters. These return values may be
		44	passed back to Perl either by putting them on the Perl
		45	stack, or by modifying the arguments supplied from the Perl
		46	side.
		47
		48
		49	The above is a somewhat simplified view of what really
		50	happens. Since Perl allows more flexible calling conventions
		51	than C, XSUBs may do much more in practice, such as checking
		52	input parameters for validity, throwing exceptions (or
		53	returning undef/empty list) if the return value from the C
		54	function indicates failure, calling different C functions
		55	based on numbers and types of the arguments, providing an
		56	object-oriented interface, etc.
		57
		58
		59	Of course, one could write such glue code directly in C.
		60	However, this would be a tedious task, especially if one
		61	needs to write glue for multiple C functions, and/or one is
		62	not familiar enough with the Perl stack discipline and other
		63	such arcana. XS comes to the rescue here:
		64	instead of writing this glue C code in long-hand, one can
		65	write a more concise short-hand ''description'' of what
		66	should be done by the glue, and let the XS
		67	compiler __xsubpp__ handle the rest.
		68
		69
		70	The XS language allows one to describe the
		71	mapping between how the C routine is used, and how the
		72	corresponding Perl routine is used. It also allows creation
		73	of Perl routines which are directly translated to C code and
		74	which are not related to a pre-existing C function. In cases
		75	when the C interface coincides with the Perl interface, the
		76	XSUB declaration is almost identical to a
		77	declaration of a C function (in K
		78	h2xs
		79	that is able to translate an entire C header file into a
		80	corresponding XS file that will provide glue
		81	to the functions/macros described in the header
		82	file.
		83
		84
		85	The XS compiler is called __xsubpp__. This
		86	compiler creates the constructs necessary to let an
		87	XSUB manipulate Perl values, and creates the
		88	glue necessary to let Perl call the XSUB .
		89	The compiler uses __typemaps__ to determine how to map C
		90	function parameters and output values to Perl values and
		91	back. The default typemap (which comes with Perl) handles
		92	many common C types. A supplementary typemap may also be
		93	needed to handle any special structures and types for the
		94	library being linked.
		95
		96
		97	A file in XS format starts with a C language
		98	section which goes until the first MODULE =
		99	directive. Other XS directives and
		100	XSUB definitions may follow this line. The
		101	``language'' used in this part of the file is usually
		102	referred to as the XS language. __xsubpp__
		103	recognizes and skips POD (see perlpod) in
		104	both the C and XS language sections, which
		105	allows the XS file to contain embedded
		106	documentation.
		107
		108
		109	See perlxstut for a tutorial on the whole extension creation
		110	process.
		111
		112
		113	Note: For some extensions, Dave Beazley's
		114	SWIG system may provide a significantly more
		115	convenient mechanism for creating the extension glue code.
		116	See http://www.swig.org/ for more information.
		117
		118
		119	__On The Road__
		120
		121
		122	Many of the examples which follow will concentrate on
		123	creating an interface between Perl and the ONC+
		124	RPC bind library functions. The
		125	''rpcb_gettime()'' function is used to demonstrate many
		126	features of the XS language. This function
		127	has two parameters; the first is an input parameter and the
		128	second is an output parameter. The function also returns a
		129	status value.
		130
		131
		132	bool_t rpcb_gettime(const char *host, time_t *timep);
		133	From C this function will be called with the following statements.
		134
		135
		136	#include
		137	If an XSUB is created to offer a direct translation between this function and Perl, then this XSUB will be used from Perl with the following code. The $status and $timep variables will contain the output of the function.
		138
		139
		140	use RPC;
		141	$status = rpcb_gettime(
		142	The following XS file shows an XS subroutine, or XSUB , which demonstrates one possible interface to the ''rpcb_gettime()'' function. This XSUB represents a direct translation between C and Perl and so preserves the interface even from Perl. This XSUB will be invoked from Perl with the usage shown above. Note that the first three #include statements, for EXTERN.h, perl.h, and XSUB.h, will always be present at the beginning of an XS file. This approach and others will be expanded later in this document.
		143
		144
		145	#include
		146	MODULE = RPC PACKAGE = RPC
		147	bool_t
		148	rpcb_gettime(host,timep)
		149	char *host
		150	time_t
		151	Any extension to Perl, including those containing XSUBs, should have a Perl module to serve as the bootstrap which pulls the extension into Perl. This module will export the extension's functions and variables to the Perl program and will cause the extension's XSUBs to be linked into Perl. The following module will be used for most of the examples in this document and should be used from Perl with the use command as shown earlier. Perl modules are explained in more detail later in this document.
		152
		153
		154	package RPC;
		155	require Exporter;
2	perry	156	require !DynaLoader;
		157	@ISA = qw(Exporter !DynaLoader);
1	perry	158	@EXPORT = qw( rpcb_gettime );
		159	bootstrap RPC;
		160	1;
		161	Throughout this document a variety of interfaces to the ''rpcb_gettime()'' XSUB will be explored. The XSUBs will take their parameters in different orders or will take different numbers of parameters. In each case the XSUB is an abstraction between Perl and the real C ''rpcb_gettime()'' function, and the XSUB must always ensure that the real ''rpcb_gettime()'' function is called with the correct parameters. This abstraction will allow the programmer to create a more Perl-like interface to the C function.
		162
		163
		164	__The Anatomy of an XSUB__
		165
		166
		167	The simplest XSUBs consist of 3 parts: a description of the
		168	return value, the name of the XSUB routine
		169	and the names of its arguments, and a description of types
		170	or formats of the arguments.
		171
		172
		173	The following XSUB allows a Perl program to
		174	access a C library function called ''sin()''. The
		175	XSUB will imitate the C function which takes
		176	a single argument and returns a single value.
		177
		178
		179	double
		180	sin(x)
		181	double x
		182	Optionally, one can merge the description of types and the list of argument names, rewriting this as
		183
		184
		185	double
		186	sin(double x)
		187	This makes this XSUB look similar to an ANSI C declaration. An optional semicolon is allowed after the argument list, as in
		188
		189
		190	double
		191	sin(double x);
		192	Parameters with C pointer types can have different semantic: C functions with similar declarations
		193
		194
		195	bool string_looks_as_a_number(char *s);
		196	bool make_char_uppercase(char *c);
		197	are used in absolutely incompatible manner. Parameters to these functions could be described __xsubpp__ like this:
		198
		199
		200	char * s
		201	char
		202	Both these XS declarations correspond to the char* C type, but they have different semantics, see ``The
		203
		204
		205	It is convenient to think that the indirection operator
		206	* should be considered as a part of the type and
		207	the address operator should be considered
		208	part of the variable. See ``The Typemap'' for more info
		209	about handling qualifiers and unary operators in C
		210	types.
		211
		212
		213	The function name and the return type must be placed on
		214	separate lines and should be flush
		215	left-adjusted.
		216
		217
		218	INCORRECT CORRECT
		219	double sin(x) double
		220	double x sin(x)
		221	double x
		222	The rest of the function description may be indented or left-adjusted. The following example shows a function with its body left-adjusted. Most examples in this document will indent the body for better readability.
		223
		224
		225	CORRECT
		226	double
		227	sin(x)
		228	double x
		229	More complicated XSUBs may contain many other sections. Each section of an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP: . However, the first two lines of an XSUB always contain the same data: descriptions of the return type and the names of the function and its parameters. Whatever immediately follows these is considered to be an INPUT: section unless explicitly marked with another keyword. (See ``The INPUT: Keyword''.)
		230
		231
		232	An XSUB section continues until another
		233	section-start keyword is found.
		234
		235
		236	__The Argument Stack__
		237
		238
		239	The Perl argument stack is used to store the values which
		240	are sent as parameters to the XSUB and to
		241	store the XSUB 's return value(s). In reality
		242	all Perl functions (including non-XSUB ones) keep their
		243	values on this stack all the same time, each limited to its
		244	own range of positions on the stack. In this document the
		245	first position on that stack which belongs to the active
		246	function will be referred to as position 0 for that
		247	function.
		248
		249
		250	XSUBs refer to their stack arguments with the macro
		251	__ST (x)__, where ''x'' refers to a
		252	position in this XSUB 's part of the stack.
		253	Position 0 for that function would be known to the
		254	XSUB as ''ST'' (0). The
		255	XSUB 's incoming parameters and outgoing
		256	return values always begin at ''ST'' (0).
		257	For many simple cases the __xsubpp__ compiler will
		258	generate the code necessary to handle the argument stack by
		259	embedding code fragments found in the typemaps. In more
		260	complex cases the programmer must supply the
		261	code.
		262
		263
		264	__The RETVAL Variable__
		265
		266
		267	The RETVAL variable is a special C variable
		268	that is declared automatically for you. The C type of
		269	RETVAL matches the return type of the C
		270	library function. The __xsubpp__ compiler will declare
		271	this variable in each XSUB with
		272	non-void return type. By default the generated C
		273	function will use RETVAL to hold the return
		274	value of the C library function being called. In simple
		275	cases the value of RETVAL will be placed in
		276	''ST'' (0) of the argument stack where it
		277	can be received by Perl as the return value of the
		278	XSUB .
		279
		280
		281	If the XSUB has a return type of
		282	void then the compiler will not declare a
		283	RETVAL variable for that function. When using
		284	a PPCODE: section no manipulation of the
		285	RETVAL variable is required, the section may
		286	use direct stack manipulation to place output values on the
		287	stack.
		288
		289
		290	If PPCODE: directive is not used,
		291	void return value should be used only for
		292	subroutines which do not return a value, ''even if''
		293	CODE: directive is used which sets
		294	''ST'' (0) explicitly.
		295
		296
		297	Older versions of this document recommended to use
		298	void return value in such cases. It was discovered
		299	that this could lead to segfaults in cases when
		300	XSUB was ''truly'' void. This
		301	practice is now deprecated, and may be not supported at some
		302	future version. Use the return value SV * in such
		303	cases. (Currently xsubpp contains some heuristic
		304	code which tries to disambiguate between ``truly-void'' and
		305	``old-practice-declared-as-void'' functions. Hence your code
		306	is at mercy of this heuristics unless you use SV *
		307	as return value.)
		308
		309
		310	__The MODULE Keyword__
		311
		312
		313	The MODULE keyword is used to start the
		314	XS code and to specify the package of the
		315	functions which are being defined. All text preceding the
		316	first MODULE keyword is considered C code and
		317	is passed through to the output with POD
		318	stripped, but otherwise untouched. Every XS
		319	module will have a bootstrap function which is used to hook
		320	the XSUBs into Perl. The package name of this bootstrap
		321	function will match the value of the last
		322	MODULE statement in the XS
		323	source files. The value of MODULE should
		324	always remain constant within the same XS
		325	file, though this is not required.
		326
		327
		328	The following example will start the XS code
		329	and will place all functions in a package named
		330	RPC .
		331
		332
		333	MODULE = RPC
		334
		335
		336	__The PACKAGE Keyword__
		337
		338
		339	When functions within an XS source file must
		340	be separated into packages the PACKAGE
		341	keyword should be used. This keyword is used with the
		342	MODULE keyword and must follow immediately
		343	after it when used.
		344
		345
		346	MODULE = RPC PACKAGE = RPC
		347	[[ XS code in package RPC ]
		348	MODULE = RPC PACKAGE = RPCB
		349	[[ XS code in package RPCB ]
		350	MODULE = RPC PACKAGE = RPC
		351	[[ XS code in package RPC ]
		352	Although this keyword is optional and in some cases provides redundant information it should always be used. This keyword will ensure that the XSUBs appear in the desired package.
		353
		354
		355	__The PREFIX Keyword__
		356
		357
		358	The PREFIX keyword designates prefixes which
		359	should be removed from the Perl function names. If the C
		360	function is rpcb_gettime() and the
		361	PREFIX value is rpcb_ then Perl will
		362	see this function as gettime().
		363
		364
		365	This keyword should follow the PACKAGE
		366	keyword when used. If PACKAGE is not used
		367	then PREFIX should follow the
		368	MODULE keyword.
		369
		370
		371	MODULE = RPC PREFIX = rpc_
		372	MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
		373
		374
		375	__The OUTPUT: Keyword__
		376
		377
		378	The OUTPUT: keyword indicates that certain
		379	function parameters should be updated (new values made
		380	visible to Perl) when the XSUB terminates or
		381	that certain values should be returned to the calling Perl
		382	function. For simple functions which have no
		383	CODE: or PPCODE: section, such
		384	as the ''sin()'' function above, the
		385	RETVAL variable is automatically designated
		386	as an output value. For more complex functions the
		387	__xsubpp__ compiler will need help to determine which
		388	variables are output variables.
		389
		390
		391	This keyword will normally be used to complement the
		392	CODE: keyword. The RETVAL
		393	variable is not recognized as an output variable when the
		394	CODE: keyword is present. The
		395	OUTPUT: keyword is used in this situation to
		396	tell the compiler that RETVAL really is an
		397	output variable.
		398
		399
		400	The OUTPUT: keyword can also be used to
		401	indicate that function parameters are output variables. This
		402	may be necessary when a parameter has been modified within
		403	the function and the programmer would like the update to be
		404	seen by Perl.
		405
		406
		407	bool_t
		408	rpcb_gettime(host,timep)
		409	char *host
		410	time_t
		411	The OUTPUT: keyword will also allow an output parameter to be mapped to a matching piece of code rather than to a typemap.
		412
		413
		414	bool_t
		415	rpcb_gettime(host,timep)
		416	char *host
		417	time_t
		418	__xsubpp__ emits an automatic SvSETMAGIC() for all parameters in the OUTPUT section of the XSUB , except RETVAL . This is the usually desired behavior, as it takes care of properly invoking 'set' magic on output parameters (needed for hash or array element parameters that must be created if they didn't exist). If for some reason, this behavior is not desired, the OUTPUT section may contain a SETMAGIC: DISABLE line to disable it for the remainder of the parameters in the OUTPUT section. Likewise, SETMAGIC: ENABLE can be used to reenable it for the remainder of the OUTPUT section. See perlguts for more details about 'set' magic.
		419
		420
		421	__The NO_OUTPUT Keyword__
		422
		423
		424	The NO_OUTPUT can be placed as the first
		425	token of the XSUB . This keyword indicates
		426	that while the C subroutine we provide an interface to has a
		427	non-void return type, the return value of this C
		428	subroutine should not be returned from the generated Perl
		429	subroutine.
		430
		431
		432	With this keyword present ``The RETVAL
		433	Variable'' is created, and in the generated call to the
		434	subroutine this variable is assigned to, but the value of
		435	this variable is not going to be used in the auto-generated
		436	code.
		437
		438
		439	This keyword makes sense only if RETVAL is going to
		440	be accessed by the user-supplied code. It is especially
		441	useful to make a function interface more Perl-like,
		442	especially when the C return value is just an error
		443	condition indicator. For example,
		444
		445
		446	NO_OUTPUT int
		447	delete_file(char *name)
		448	POST_CALL:
		449	if (RETVAL != 0)
		450	croak(
		451	Here the generated XS function returns nothing on success, and will ''die()'' with a meaningful error message on error.
		452
		453
		454	__The CODE: Keyword__
		455
		456
		457	This keyword is used in more complicated XSUBs which require
		458	special handling for the C function. The
		459	RETVAL variable is still declared, but it
		460	will not be returned unless it is specified in the
		461	OUTPUT: section.
		462
		463
		464	The following XSUB is for a C function which
		465	requires special handling of its parameters. The Perl usage
		466	is given first.
		467
		468
		469	$status = rpcb_gettime(
		470	The XSUB follows.
		471
		472
		473	bool_t
		474	rpcb_gettime(host,timep)
		475	char *host
		476	time_t timep
		477	CODE:
		478	RETVAL = rpcb_gettime( host,
		479
		480
		481	__The INIT: Keyword__
		482
		483
		484	The INIT: keyword allows initialization to be
		485	inserted into the XSUB before the compiler
		486	generates the call to the C function. Unlike the
		487	CODE: keyword above, this keyword does not
		488	affect the way the compiler handles RETVAL
		489	.
		490
		491
		492	bool_t
		493	rpcb_gettime(host,timep)
		494	char *host
		495	time_t
		496	Another use for the INIT: section is to check for preconditions before making a call to the C function:
		497
		498
		499	long long
		500	lldiv(a,b)
		501	long long a
		502	long long b
		503	INIT:
		504	if (a == 0
		505
		506
		507	__The NO_INIT Keyword__
		508
		509
		510	The NO_INIT keyword is used to indicate that
		511	a function parameter is being used only as an output value.
		512	The __xsubpp__ compiler will normally generate code to
		513	read the values of all function parameters from the argument
		514	stack and assign them to C variables upon entry to the
		515	function. NO_INIT will tell the compiler that
		516	some parameters will be used for output rather than for
		517	input and that they will be handled before the function
		518	terminates.
		519
		520
		521	The following example shows a variation of the
		522	''rpcb_gettime()'' function. This function uses the timep
		523	variable only as an output variable and does not care about
		524	its initial contents.
		525
		526
		527	bool_t
		528	rpcb_gettime(host,timep)
		529	char *host
		530	time_t
		531
		532
		533	__Initializing Function Parameters__
		534
		535
		536	C function parameters are normally initialized with their
		537	values from the argument stack (which in turn contains the
		538	parameters that were passed to the XSUB from
		539	Perl). The typemaps contain the code segments which are used
		540	to translate the Perl values to the C parameters. The
		541	programmer, however, is allowed to override the typemaps and
		542	supply alternate (or additional) initialization code.
		543	Initialization code starts with the first =,
		544	; or + on a line in the
		545	INPUT: section. The only exception happens if
		546	this ; terminates the line, then this ; is
		547	quietly ignored.
		548
		549
		550	The following code demonstrates how to supply initialization
		551	code for function parameters. The initialization code is
		552	eval'd within double quotes by the compiler before it is
		553	added to the output so anything which should be interpreted
		554	literally [[mainly $, @, or \]
		555	must be protected with backslashes. The variables
		556	$var, $arg, and $type can be used
		557	as in typemaps.
		558
		559
		560	bool_t
		561	rpcb_gettime(host,timep)
		562	char *host = (char *)SvPV($arg,PL_na);
		563	time_t
		564	This should not be used to supply default values for parameters. One would normally use this when a function parameter must be processed by another library function before it can be used. Default parameters are covered in the next section.
		565
		566
		567	If the initialization begins with =, then it is
		568	output in the declaration for the input variable, replacing
		569	the initialization supplied by the typemap. If the
		570	initialization begins with ; or +, then it
		571	is performed after all of the input variables have been
		572	declared. In the ; case the initialization normally
		573	supplied by the typemap is not performed. For the +
		574	case, the declaration for the variable will include the
		575	initialization from the typemap. A global variable,
		576	%v, is available for the truly rare case where
		577	information from one initialization is needed in another
		578	initialization.
		579
		580
		581	Here's a truly obscure example:
		582
		583
		584	bool_t
		585	rpcb_gettime(host,timep)
		586	time_t
		587	The construct $v{timep}=@{[[$v{timep}=$arg]} used in the above example has a two-fold purpose: first, when this line is processed by __xsubpp__, the Perl snippet $v{timep}=$arg is evaluated. Second, the text of the evaluated snippet is output into the generated C file (inside a C comment)! During the processing of char *host line, $arg will evaluate to ST(0), and $v{timep} will evaluate to ST(1).
		588
		589
		590	__Default Parameter Values__
		591
		592
		593	Default values for XSUB arguments can be
		594	specified by placing an assignment statement in the
		595	parameter list. The default value may be a number, a string
		596	or the special string NO_INIT. Defaults should
		597	always be used on the right-most parameters
		598	only.
		599
		600
		601	To allow the XSUB for ''rpcb_gettime()''
		602	to have a default host value the parameters to the
		603	XSUB could be rearranged. The
		604	XSUB will then call the real
		605	''rpcb_gettime()'' function with the parameters in the
		606	correct order. This XSUB can be called from
		607	Perl with either of the following statements:
		608
		609
		610	$status = rpcb_gettime( $timep, $host );
		611	$status = rpcb_gettime( $timep );
		612	The XSUB will look like the code which follows. A CODE: block is used to call the real ''rpcb_gettime()'' function with the parameters in the correct order for that function.
		613
		614
		615	bool_t
		616	rpcb_gettime(timep,host=
		617
		618
		619	__The PREINIT: Keyword__
		620
		621
		622	The PREINIT: keyword allows extra variables
		623	to be declared immediately before or after the declarations
		624	of the parameters from the INPUT: section are
		625	emitted.
		626
		627
		628	If a variable is declared inside a CODE:
		629	section it will follow any typemap code that is emitted for
		630	the input parameters. This may result in the declaration
		631	ending up after C code, which is C syntax error. Similar
		632	errors may happen with an explicit ;-type or
		633	+-type initialization of parameters is used (see
		634	``Initializing Function Parameters''). Declaring these
		635	variables in an INIT: section will not
		636	help.
		637
		638
		639	In such cases, to force an additional variable to be
		640	declared together with declarations of other variables,
		641	place the declaration into a PREINIT:
		642	section. The PREINIT: keyword may be used one
		643	or more times within an XSUB .
		644
		645
		646	The following examples are equivalent, but if the code is
		647	using complex typemaps then the first example is
		648	safer.
		649
		650
		651	bool_t
		652	rpcb_gettime(timep)
		653	time_t timep = NO_INIT
		654	PREINIT:
		655	char *host =
		656	For this particular case an INIT: keyword would generate the same C code as the PREINIT: keyword. Another correct, but error-prone example:
		657
		658
		659	bool_t
		660	rpcb_gettime(timep)
		661	time_t timep = NO_INIT
		662	CODE:
		663	char *host =
		664	Another way to declare host is to use a C block in the CODE: section:
		665
		666
		667	bool_t
		668	rpcb_gettime(timep)
		669	time_t timep = NO_INIT
		670	CODE:
		671	{
		672	char *host =
		673	The ability to put additional declarations before the typemap entries are processed is very handy in the cases when typemap conversions manipulate some global state:
		674
		675
2	perry	676	!MyObject
1	perry	677	mutate(o)
		678	PREINIT:
2	perry	679	!MyState st = global_state;
1	perry	680	INPUT:
2	perry	681	!MyObject o;
1	perry	682	CLEANUP:
		683	reset_to(global_state, st);
2	perry	684	Here we suppose that conversion to !MyObject in the INPUT: section and from !MyObject when processing RETVAL will modify a global variable global_state. After these conversions are performed, we restore the old value of global_state (to avoid memory leaks, for example).
1	perry	685
		686
		687	There is another way to trade clarity for compactness:
		688	INPUT sections allow declaration of C
		689	variables which do not appear in the parameter list of a
		690	subroutine. Thus the above code for ''mutate()'' can be
		691	rewritten as
		692
		693
2	perry	694	!MyObject
1	perry	695	mutate(o)
2	perry	696	!MyState st = global_state;
		697	!MyObject o;
1	perry	698	CLEANUP:
		699	reset_to(global_state, st);
		700	and the code for ''rpcb_gettime()'' can be rewritten as
		701
		702
		703	bool_t
		704	rpcb_gettime(timep)
		705	time_t timep = NO_INIT
		706	char *host =
		707
		708
		709	__The SCOPE: Keyword__
		710
		711
		712	The SCOPE: keyword allows scoping to be
		713	enabled for a particular XSUB . If enabled,
		714	the XSUB will invoke ENTER and
		715	LEAVE automatically.
		716
		717
		718	To support potentially complex type mappings, if a typemap
		719	entry used by an XSUB contains a comment like
		720	/*scope*/ then scoping will be automatically
		721	enabled for that XSUB .
		722
		723
		724	To enable scoping:
		725
		726
		727	SCOPE: ENABLE
		728	To disable scoping:
		729
		730
		731	SCOPE: DISABLE
		732
		733
		734	__The INPUT: Keyword__
		735
		736
		737	The XSUB 's parameters are usually evaluated
		738	immediately after entering the XSUB . The
		739	INPUT: keyword can be used to force those
		740	parameters to be evaluated a little later. The
		741	INPUT: keyword can be used multiple times
		742	within an XSUB and can be used to list one or
		743	more input variables. This keyword is used with the
		744	PREINIT: keyword.
		745
		746
		747	The following example shows how the input parameter
		748	timep can be evaluated late, after a
		749	PREINIT .
		750
		751
		752	bool_t
		753	rpcb_gettime(host,timep)
		754	char *host
		755	PREINIT:
		756	time_t tt;
		757	INPUT:
		758	time_t timep
		759	CODE:
		760	RETVAL = rpcb_gettime( host,
		761	The next example shows each input parameter evaluated late.
		762
		763
		764	bool_t
		765	rpcb_gettime(host,timep)
		766	PREINIT:
		767	time_t tt;
		768	INPUT:
		769	char *host
		770	PREINIT:
		771	char *h;
		772	INPUT:
		773	time_t timep
		774	CODE:
		775	h = host;
		776	RETVAL = rpcb_gettime( h,
		777	Since INPUT sections allow declaration of C variables which do not appear in the parameter list of a subroutine, this may be shortened to:
		778
		779
		780	bool_t
		781	rpcb_gettime(host,timep)
		782	time_t tt;
		783	char *host;
		784	char *h = host;
		785	time_t timep;
		786	CODE:
		787	RETVAL = rpcb_gettime( h,
		788	(We used our knowledge that input conversion for char * is a ``simple'' one, thus host is initialized on the declaration line, and our assignment h = host is not performed too early. Otherwise one would need to have the assignment h = host in a CODE: or INIT: section.)
		789
		790
		791	__The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT
		792	Keywords__
		793
		794
		795	In the list of parameters for an XSUB , one
		796	can precede parameter names by the
		797	IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT
		798	keywords. IN keyword is the default, the other
		799	keywords indicate how the Perl interface should differ from
		800	the C interface.
		801
		802
		803	Parameters preceded by
		804	OUTLIST/IN_OUTLIST/OUT/IN_OUT
		805	keywords are considered to be used by the C subroutine
		806	''via pointers''. OUTLIST/OUT keywords
		807	indicate that the C subroutine does not inspect the memory
		808	pointed by this parameter, but will write through this
		809	pointer to provide additional return values.
		810
		811
		812	Parameters preceded by OUTLIST keyword do not
		813	appear in the usage signature of the generated Perl
		814	function.
		815
		816
		817	Parameters preceded by
		818	IN_OUTLIST/IN_OUT/OUT ''do''
		819	appear as parameters to the Perl function. With the
		820	exception of OUT-parameters, these parameters are
		821	converted to the corresponding C type, then pointers to
		822	these data are given as arguments to the C function. It is
		823	expected that the C function will write through these
		824	pointers.
		825
		826
		827	The return list of the generated Perl function consists of
		828	the C return value from the function (unless the
		829	XSUB is of void return type or
		830	The NO_OUTPUT Keyword was used) followed by all the
		831	OUTLIST and IN_OUTLIST parameters (in the
		832	order of appearance). On the return from the
		833	XSUB the IN_OUT/OUT Perl
		834	parameter will be modified to have the values written by the
		835	C function.
		836
		837
		838	For example, an XSUB
		839
		840
		841	void
		842	day_month(OUTLIST day, IN unix_time, OUTLIST month)
		843	int day
		844	int unix_time
		845	int month
		846	should be used from Perl as
		847
		848
		849	my ($day, $month) = day_month(time);
		850	The C signature of the corresponding function should be
		851
		852
		853	void day_month(int *day, int unix_time, int *month);
		854	The IN/OUTLIST/IN_OUTLIST/IN_OUT/OUT keywords can be mixed with ANSI-style declarations, as in
		855
		856
		857	void
		858	day_month(OUTLIST int day, int unix_time, OUTLIST int month)
		859	(here the optional IN keyword is omitted).
		860
		861
		862	The IN_OUT parameters are identical with parameters
		863	introduced with ``The
		864	OUTPUT: section (see ``The
		865	OUTPUT: Keyword''). The IN_OUTLIST
		866	parameters are very similar, the only difference being that
		867	the value C function writes through the pointer would not
		868	modify the Perl parameter, but is put in the output
		869	list.
		870
		871
		872	The OUTLIST/OUT parameter differ from
		873	IN_OUTLIST/IN_OUT parameters only by the
		874	the initial value of the Perl parameter not being read (and
		875	not being given to the C function - which gets some garbage
		876	instead). For example, the same C function as above can be
		877	interfaced with as
		878
		879
		880	void day_month(OUT int day, int unix_time, OUT int month);
		881	or
		882
		883
		884	void
		885	day_month(day, unix_time, month)
		886	int
		887	However, the generated Perl function is called in very C-ish style:
		888
		889
		890	my ($day, $month);
		891	day_month($day, time, $month);
		892
		893
		894	__Variable-length Parameter Lists__
		895
		896
		897	XSUBs can have variable-length parameter lists by specifying
		898	an ellipsis (...) in the parameter list. This use
		899	of the ellipsis is similar to that found in
		900	ANSI C. The programmer is able to determine
		901	the number of arguments passed to the XSUB by
		902	examining the items variable which the
		903	__xsubpp__ compiler supplies for all XSUBs. By using this
		904	mechanism one can create an XSUB which
		905	accepts a list of parameters of unknown length.
		906
		907
		908	The ''host'' parameter for the ''rpcb_gettime()''
		909	XSUB can be optional so the ellipsis can be
		910	used to indicate that the XSUB will take a
		911	variable number of parameters. Perl should be able to call
		912	this XSUB with either of the following
		913	statements.
		914
		915
		916	$status = rpcb_gettime( $timep, $host );
		917	$status = rpcb_gettime( $timep );
		918	The XS code, with ellipsis, follows.
		919
		920
		921	bool_t
		922	rpcb_gettime(timep, ...)
		923	time_t timep = NO_INIT
		924	PREINIT:
		925	char *host =
		926
		927
		928	__The C_ARGS: Keyword__
		929
		930
		931	The C_ARGS: keyword allows creating of XSUBS
		932	which have different calling sequence from Perl than from C,
		933	without a need to write CODE: or
		934	PPCODE: section. The contents of the C_ARGS:
		935	paragraph is put as the argument to the called C function
		936	without any change.
		937
		938
		939	For example, suppose that a C function is declared
		940	as
		941
		942
		943	symbolic nth_derivative(int n, symbolic function, int flags);
		944	and that the default flags are kept in a global C variable default_flags. Suppose that you want to create an interface which is called as
		945
		946
		947	$second_deriv = $function-
		948	To do this, declare the XSUB as
		949
		950
		951	symbolic
		952	nth_derivative(function, n)
		953	symbolic function
		954	int n
		955	C_ARGS:
		956	n, function, default_flags
		957
		958
		959	__The PPCODE: Keyword__
		960
		961
		962	The PPCODE: keyword is an alternate form of
		963	the CODE: keyword and is used to tell the
		964	__xsubpp__ compiler that the programmer is supplying the
		965	code to control the argument stack for the XSUBs return
		966	values. Occasionally one will want an XSUB to
		967	return a list of values rather than a single value. In these
		968	cases one must use PPCODE: and then
		969	explicitly push the list of values on the stack. The
		970	PPCODE: and CODE: keywords
		971	should not be used together within the same
		972	XSUB .
		973
		974
		975	The actual difference between PPCODE: and
		976	CODE: sections is in the initialization of
		977	SP macro (which stands for the ''current'' Perl
		978	stack pointer), and in the handling of data on the stack
		979	when returning from an XSUB . In
		980	CODE: sections SP preserves
		981	the value which was on entry to the XSUB: SP
		982	is on the function pointer (which follows the last
		983	parameter). In PPCODE: sections
		984	SP is moved backward to the beginning of the
		985	parameter list, which allows PUSH*() macros to
		986	place output values in the place Perl expects them to be
		987	when the XSUB returns back to
		988	Perl.
		989
		990
		991	The generated trailer for a CODE: section
		992	ensures that the number of return values Perl will see is
		993	either 0 or 1 (depending on the voidness of the
		994	return value of the C function, and heuristics mentioned in
		995	``The RETVAL Variable''). The trailer
		996	generated for a PPCODE: section is based on
		997	the number of return values and on the number of times
		998	SP was updated by [[X]PUSH*()
		999	macros.
		1000
		1001
		1002	Note that macros ST(i), XST_m*() and
		1003	XSRETURN*() work equally well in
		1004	CODE: sections and PPCODE:
		1005	sections.
		1006
		1007
		1008	The following XSUB will call the C
		1009	''rpcb_gettime()'' function and will return its two
		1010	output values, timep and status, to Perl as a single
		1011	list.
		1012
		1013
		1014	void
		1015	rpcb_gettime(host)
		1016	char *host
		1017	PREINIT:
		1018	time_t timep;
		1019	bool_t status;
		1020	PPCODE:
		1021	status = rpcb_gettime( host,
		1022	Notice that the programmer must supply the C code necessary to have the real ''rpcb_gettime()'' function called and to have the return values properly placed on the argument stack.
		1023
		1024
		1025	The void return type for this function tells the
		1026	__xsubpp__ compiler that the RETVAL
		1027	variable is not needed or used and that it should not be
		1028	created. In most scenarios the void return type should be
		1029	used with the PPCODE: directive.
		1030
		1031
		1032	The ''EXTEND ()'' macro is used to make
		1033	room on the argument stack for 2 return values. The
		1034	PPCODE: directive causes the __xsubpp__
		1035	compiler to create a stack pointer available as SP,
		1036	and it is this pointer which is being used in the
		1037	''EXTEND ()'' macro. The values are then
		1038	pushed onto the stack with the ''PUSHs()''
		1039	macro.
		1040
		1041
		1042	Now the ''rpcb_gettime()'' function can be used from Perl
		1043	with the following statement.
		1044
		1045
		1046	($status, $timep) = rpcb_gettime(
		1047	When handling output parameters with a PPCODE section, be sure to handle 'set' magic properly. See perlguts for details about 'set' magic.
		1048
		1049
		1050	__Returning Undef And Empty Lists__
		1051
		1052
		1053	Occasionally the programmer will want to return simply
		1054	undef or an empty list if a function fails rather
		1055	than a separate status value. The ''rpcb_gettime()''
		1056	function offers just this situation. If the function
		1057	succeeds we would like to have it return the time and if it
		1058	fails we would like to have undef returned. In the following
		1059	Perl code the value of $timep will either be undef
		1060	or it will be a valid time.
		1061
		1062
		1063	$timep = rpcb_gettime(
		1064	The following XSUB uses the SV * return type as a mnemonic only, and uses a CODE: block to indicate to the compiler that the programmer has supplied all the necessary code. The ''sv_newmortal()'' call will initialize the return value to undef, making that the default return value.
		1065
		1066
		1067	SV *
		1068	rpcb_gettime(host)
		1069	char * host
		1070	PREINIT:
		1071	time_t timep;
		1072	bool_t x;
		1073	CODE:
		1074	ST(0) = sv_newmortal();
		1075	if( rpcb_gettime( host,
		1076	The next example demonstrates how one would place an explicit undef in the return value, should the need arise.
		1077
		1078
		1079	SV *
		1080	rpcb_gettime(host)
		1081	char * host
		1082	PREINIT:
		1083	time_t timep;
		1084	bool_t x;
		1085	CODE:
		1086	ST(0) = sv_newmortal();
		1087	if( rpcb_gettime( host,
		1088	To return an empty list one must use a PPCODE: block and then not push return values on the stack.
		1089
		1090
		1091	void
		1092	rpcb_gettime(host)
		1093	char *host
		1094	PREINIT:
		1095	time_t timep;
		1096	PPCODE:
		1097	if( rpcb_gettime( host,
		1098	Some people may be inclined to include an explicit return in the above XSUB , rather than letting control fall through to the end. In those situations XSRETURN_EMPTY should be used, instead. This will ensure that the XSUB stack is properly adjusted. Consult `` API LISTING '' in perlguts for other XSRETURN macros.
		1099
		1100
		1101	Since XSRETURN_* macros can be used with
		1102	CODE blocks as well, one can rewrite this
		1103	example as:
		1104
		1105
		1106	int
		1107	rpcb_gettime(host)
		1108	char *host
		1109	PREINIT:
		1110	time_t timep;
		1111	CODE:
		1112	RETVAL = rpcb_gettime( host,
		1113	In fact, one can put this check into a POST_CALL: section as well. Together with PREINIT: simplifications, this leads to:
		1114
		1115
		1116	int
		1117	rpcb_gettime(host)
		1118	char *host
		1119	time_t timep;
		1120	POST_CALL:
		1121	if (RETVAL == 0)
		1122	XSRETURN_UNDEF;
		1123
		1124
		1125	__The REQUIRE: Keyword__
		1126
		1127
		1128	The REQUIRE: keyword is used to indicate the
		1129	minimum version of the __xsubpp__ compiler needed to
		1130	compile the XS module. An XS
		1131	module which contains the following statement will compile
		1132	with only __xsubpp__ version 1.922 or
		1133	greater:
		1134
		1135
		1136	REQUIRE: 1.922
		1137
		1138
		1139	__The CLEANUP: Keyword__
		1140
		1141
		1142	This keyword can be used when an XSUB
		1143	requires special cleanup procedures before it terminates.
		1144	When the CLEANUP: keyword is used it must
		1145	follow any CODE: , PPCODE: ,
		1146	or OUTPUT: blocks which are present in the
		1147	XSUB . The code specified for the cleanup
		1148	block will be added as the last statements in the
		1149	XSUB .
		1150
		1151
		1152	__The POST_CALL: Keyword__
		1153
		1154
		1155	This keyword can be used when an XSUB
		1156	requires special procedures executed after the C subroutine
		1157	call is performed. When the POST_CALL:
		1158	keyword is used it must precede OUTPUT: and
		1159	CLEANUP: blocks which are present in the
		1160	XSUB .
		1161
		1162
		1163	The POST_CALL: block does not make a lot of
		1164	sense when the C subroutine call is supplied by user by
		1165	providing either CODE: or
		1166	PPCODE: section.
		1167
		1168
		1169	__The BOOT: Keyword__
		1170
		1171
		1172	The BOOT: keyword is used to add code to the
		1173	extension's bootstrap function. The bootstrap function is
		1174	generated by the __xsubpp__ compiler and normally holds
		1175	the statements necessary to register any XSUBs with Perl.
		1176	With the BOOT: keyword the programmer can
		1177	tell the compiler to add extra statements to the bootstrap
		1178	function.
		1179
		1180
		1181	This keyword may be used any time after the first
		1182	MODULE keyword and should appear on a line by
		1183	itself. The first blank line after the keyword will
		1184	terminate the code block.
		1185
		1186
		1187	BOOT:
		1188	# The following message will be printed when the
		1189	# bootstrap function executes.
		1190	printf(
		1191
		1192
		1193	__The VERSIONCHECK: Keyword__
		1194
		1195
		1196	The VERSIONCHECK: keyword corresponds to
		1197	__xsubpp__'s -versioncheck and
		1198	-noversioncheck options. This keyword overrides the
		1199	command line options. Version checking is enabled by
		1200	default. When version checking is enabled the
		1201	XS module will attempt to verify that its
		1202	version matches the version of the PM
		1203	module.
		1204
		1205
		1206	To enable version checking:
		1207
		1208
		1209	VERSIONCHECK: ENABLE
		1210	To disable version checking:
		1211
		1212
		1213	VERSIONCHECK: DISABLE
		1214
		1215
		1216	__The PROTOTYPES: Keyword__
		1217
		1218
		1219	The PROTOTYPES: keyword corresponds to
		1220	__xsubpp__'s -prototypes and
		1221	-noprototypes options. This keyword overrides the
		1222	command line options. Prototypes are enabled by default.
		1223	When prototypes are enabled XSUBs will be given Perl
		1224	prototypes. This keyword may be used multiple times in an
		1225	XS module to enable and disable prototypes
		1226	for different parts of the module.
		1227
		1228
		1229	To enable prototypes:
		1230
		1231
		1232	PROTOTYPES: ENABLE
		1233	To disable prototypes:
		1234
		1235
		1236	PROTOTYPES: DISABLE
		1237
		1238
		1239	__The PROTOTYPE: Keyword__
		1240
		1241
		1242	This keyword is similar to the PROTOTYPES:
		1243	keyword above but can be used to force __xsubpp__ to use
		1244	a specific prototype for the XSUB . This
		1245	keyword overrides all other prototype options and keywords
		1246	but affects only the current XSUB . Consult
		1247	``Prototypes'' in perlsub for information about Perl
		1248	prototypes.
		1249
		1250
		1251	bool_t
		1252	rpcb_gettime(timep, ...)
		1253	time_t timep = NO_INIT
		1254	PROTOTYPE: $;$
		1255	PREINIT:
		1256	char *host =
		1257
		1258
		1259	__The ALIAS: Keyword__
		1260
		1261
		1262	The ALIAS: keyword allows an
		1263	XSUB to have two or more unique Perl names
		1264	and to know which of those names was used when it was
		1265	invoked. The Perl names may be fully-qualified with package
		1266	names. Each alias is given an index. The compiler will setup
		1267	a variable called ix which contain the index of the
		1268	alias which was used. When the XSUB is called
		1269	with its declared name ix will be 0.
		1270
		1271
		1272	The following example will create aliases
		1273	FOO::gettime() and BAR::getit() for this
		1274	function.
		1275
		1276
		1277	bool_t
		1278	rpcb_gettime(host,timep)
		1279	char *host
		1280	time_t
		1281
		1282
		1283	__The INTERFACE: Keyword__
		1284
		1285
		1286	This keyword declares the current XSUB as a
		1287	keeper of the given calling signature. If some text follows
		1288	this keyword, it is considered as a list of functions which
		1289	have this signature, and should be attached to the current
		1290	XSUB .
		1291
		1292
		1293	For example, if you have 4 C functions ''multiply()'',
		1294	''divide()'', ''add()'', ''subtract()'' all having
		1295	the signature:
		1296
		1297
		1298	symbolic f(symbolic, symbolic);
		1299	you can make them all to use the same XSUB using this:
		1300
		1301
		1302	symbolic
		1303	interface_s_ss(arg1, arg2)
		1304	symbolic arg1
		1305	symbolic arg2
		1306	INTERFACE:
		1307	multiply divide
		1308	add subtract
		1309	(This is the complete XSUB code for 4 Perl functions!) Four generated Perl function share names with corresponding C functions.
		1310
		1311
		1312	The advantage of this approach comparing to
		1313	ALIAS: keyword is that there is no need to
		1314	code a switch statement, each Perl function (which shares
		1315	the same XSUB ) knows which C function it
		1316	should call. Additionally, one can attach an extra function
		1317	''remainder()'' at runtime by using
		1318
		1319
		1320	CV *mycv = newXSproto(
		1321	say, from another XSUB . (This example supposes that there was no INTERFACE_MACRO: section, otherwise one needs to use something else instead of XSINTERFACE_FUNC_SET, see the next section.)
		1322
		1323
		1324	__The INTERFACE_MACRO:
		1325	Keyword__
		1326
		1327
		1328	This keyword allows one to define an
		1329	INTERFACE using a different way to extract a
		1330	function pointer from an XSUB . The text
		1331	which follows this keyword should give the name of macros
		1332	which would extract/set a function pointer. The extractor
		1333	macro is given return type, CV*, and
		1334	XSANY.any_dptr for this CV*. The setter
		1335	macro is given cv, and the function pointer.
		1336
		1337
		1338	The default value is XSINTERFACE_FUNC and
		1339	XSINTERFACE_FUNC_SET. An INTERFACE
		1340	keyword with an empty list of functions can be omitted if
		1341	INTERFACE_MACRO keyword is used.
		1342
		1343
		1344	Suppose that in the previous example functions pointers for
		1345	''multiply()'', ''divide()'', ''add()'',
		1346	''subtract()'' are kept in a global C array fp[[]
		1347	with offsets being multiply_off,
		1348	divide_off, add_off,
		1349	subtract_off. Then one can use
		1350
		1351
		1352	#define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
		1353	((XSINTERFACE_CVT(ret,))fp[[CvXSUBANY(cv).any_i32])
		1354	#define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
		1355	CvXSUBANY(cv).any_i32 = CAT2( f, _off )
		1356	in C section,
		1357
		1358
		1359	symbolic
		1360	interface_s_ss(arg1, arg2)
		1361	symbolic arg1
		1362	symbolic arg2
		1363	INTERFACE_MACRO:
		1364	XSINTERFACE_FUNC_BYOFFSET
		1365	XSINTERFACE_FUNC_BYOFFSET_set
		1366	INTERFACE:
		1367	multiply divide
		1368	add subtract
		1369	in XSUB section.
		1370
		1371
		1372	__The INCLUDE: Keyword__
		1373
		1374
		1375	This keyword can be used to pull other files into the
		1376	XS module. The other files may have
		1377	XS code. INCLUDE: can also be
		1378	used to run a command to generate the XS code
		1379	to be pulled into the module.
		1380
		1381
		1382	The file ''Rpcb1.xsh'' contains our
		1383	rpcb_gettime() function:
		1384
		1385
		1386	bool_t
		1387	rpcb_gettime(host,timep)
		1388	char *host
		1389	time_t
		1390	The XS module can use INCLUDE: to pull that file into it.
		1391
		1392
		1393	INCLUDE: Rpcb1.xsh
		1394	If the parameters to the INCLUDE: keyword are followed by a pipe () then the compiler will interpret the parameters as a command.
		1395
		1396
		1397	INCLUDE: cat Rpcb1.xsh
		1398
		1399
		1400	__The CASE: Keyword__
		1401
		1402
		1403	The CASE: keyword allows an
		1404	XSUB to have multiple distinct parts with
		1405	each part acting as a virtual XSUB .
		1406	CASE: is greedy and if it is used then all
		1407	other XS keywords must be contained within a
		1408	CASE: . This means nothing may precede the
		1409	first CASE: in the XSUB and
		1410	anything following the last CASE: is included
		1411	in that case.
		1412
		1413
		1414	A CASE: might switch via a parameter of the
		1415	XSUB , via the ix
		1416	ALIAS: variable (see ``The
		1417	ALIAS: Keyword''), or maybe via the
		1418	items variable (see ``Variable-length Parameter
		1419	Lists''). The last CASE: becomes the
		1420	__default__ case if it is not associated with a
		1421	conditional. The following example shows CASE
		1422	switched via ix with a function
		1423	rpcb_gettime() having an alias
		1424	x_gettime(). When the function is called as
		1425	rpcb_gettime() its parameters are the usual
		1426	(char *host, time_t *timep), but when the function
		1427	is called as x_gettime() its parameters are
		1428	reversed, (time_t *timep, char *host).
		1429
		1430
		1431	long
		1432	rpcb_gettime(a,b)
		1433	CASE: ix == 1
		1434	ALIAS:
		1435	x_gettime = 1
		1436	INPUT:
		1437	# 'a' is timep, 'b' is host
		1438	char *b
		1439	time_t a = NO_INIT
		1440	CODE:
		1441	RETVAL = rpcb_gettime( b,
		1442	That function can be called with either of the following statements. Note the different argument lists.
		1443
		1444
		1445	$status = rpcb_gettime( $host, $timep );
		1446	$status = x_gettime( $timep, $host );
		1447
		1448
		1449	__The __
		1450
		1451
		1452	The unary operator in the
		1453	INPUT: section is used to tell __xsubpp__
		1454	that it should convert a Perl value to/from C using the C
		1455	type to the left of , but provide a pointer to
		1456	this value when the C function is called.
		1457
		1458
		1459	This is useful to avoid a CODE: block for a C
		1460	function which takes a parameter by reference. Typically,
		1461	the parameter should be not a pointer type (an int
		1462	or long but not a int* or
		1463	long*).
		1464
		1465
		1466	The following XSUB will generate incorrect C
		1467	code. The __xsubpp__ compiler will turn this into code
		1468	which calls rpcb_gettime() with parameters
		1469	(char *host, time_t timep), but the real
		1470	rpcb_gettime() wants the timep parameter
		1471	to be of type time_t* rather than
		1472	time_t.
		1473
		1474
		1475	bool_t
		1476	rpcb_gettime(host,timep)
		1477	char *host
		1478	time_t timep
		1479	OUTPUT:
		1480	timep
		1481	That problem is corrected by using the operator. The __xsubpp__ compiler will now turn this into code which calls rpcb_gettime() correctly with parameters (char *host, time_t *timep). It does this by carrying the through, so the function call looks like rpcb_gettime(host, .
		1482
		1483
		1484	bool_t
		1485	rpcb_gettime(host,timep)
		1486	char *host
		1487	time_t
		1488
		1489
		1490	__Inserting POD , Comments and C
		1491	Preprocessor Directives__
		1492
		1493
		1494	C preprocessor directives are allowed within
		1495	BOOT: , PREINIT: INIT: ,
		1496	CODE: , PPCODE: ,
		1497	POST_CALL: , and CLEANUP:
		1498	blocks, as well as outside the functions. Comments are
		1499	allowed anywhere after the MODULE keyword.
		1500	The compiler will pass the preprocessor directives through
		1501	untouched and will remove the commented lines.
		1502	POD documentation is allowed at any point,
		1503	both in the C and XS language sections.
		1504	POD must be terminated with a =cut
		1505	command; xsubpp will exit with an error if it does
		1506	not. It is very unlikely that human generated C code will be
		1507	mistaken for POD , as most indenting styles
		1508	result in whitespace in front of any line starting with
		1509	=. Machine generated XS files may
		1510	fall into this trap unless care is taken to ensure that a
		1511	space breaks the sequence ``n=''.
		1512
		1513
		1514	Comments can be added to XSUBs by placing a # as
		1515	the first non-whitespace of a line. Care should be taken to
		1516	avoid making the comment look like a C preprocessor
		1517	directive, lest it be interpreted as such. The simplest way
		1518	to prevent this is to put whitespace in front of the
		1519	#.
		1520
		1521
		1522	If you use preprocessor directives to choose one of two
		1523	versions of a function, use
		1524
		1525
		1526	#if ... version1
		1527	#else /* ... version2 */
		1528	#endif
		1529	and not
		1530
		1531
		1532	#if ... version1
		1533	#endif
		1534	#if ... version2
		1535	#endif
		1536	because otherwise __xsubpp__ will believe that you made a duplicate definition of the function. Also, put a blank line before the #else/#endif so it will not be seen as part of the function body.
		1537
		1538
		1539	__Using XS With C
		1540	++__
		1541
		1542
		1543	If an XSUB name contains ::, it is
		1544	considered to be a C ++ method. The generated
		1545	Perl function will assume that its first argument is an
		1546	object pointer. The object pointer will be stored in a
		1547	variable called THIS . The object should have
		1548	been created by C ++ with the ''new()''
		1549	function and should be blessed by Perl with the
		1550	''sv_setref_pv()'' macro. The blessing of the object by
		1551	Perl can be handled by a typemap. An example typemap is
		1552	shown at the end of this section.
		1553
		1554
		1555	If the return type of the XSUB includes
		1556	static, the method is considered to be a static
		1557	method. It will call the C ++ function using
		1558	the ''class::method()'' syntax. If the method is not
		1559	static the function will be called using the
		1560	THIS- method()''
		1561	syntax.
		1562
		1563
		1564	The next examples will use the following C ++
		1565	class.
		1566
		1567
		1568	class color {
		1569	public:
		1570	color();
		1571	~color();
		1572	int blue();
		1573	void set_blue( int );
		1574	private:
		1575	int c_blue;
		1576	};
		1577	The XSUBs for the ''blue()'' and ''set_blue()'' methods are defined with the class name but the parameter for the object ( THIS , or ``self'') is implicit and is not listed.
		1578
		1579
		1580	int
		1581	color::blue()
		1582	void
		1583	color::set_blue( val )
		1584	int val
		1585	Both Perl functions will expect an object as the first parameter. In the generated C ++ code the object is called THIS, and the method call will be performed on this object. So in the C ++ code the ''blue()'' and ''set_blue()'' methods will be called as this:
		1586
		1587
		1588	RETVAL = THIS-
		1589	THIS-
		1590	You could also write a single get/set method using an optional argument:
		1591
		1592
		1593	int
		1594	color::blue( val = NO_INIT )
		1595	int val
		1596	PROTOTYPE $;$
		1597	CODE:
		1598	if (items
		1599	If the function's name is __DESTROY__ then the C ++ delete function will be called and THIS will be given as its parameter. The generated C ++ code for
		1600
		1601
		1602	void
		1603	color::DESTROY()
		1604	will look like this:
		1605
		1606
		1607	color *THIS = ...; // Initialized as in typemap
		1608	delete THIS;
		1609	If the function's name is __new__ then the C ++ new function will be called to create a dynamic C ++ object. The XSUB will expect the class name, which will be kept in a variable called CLASS, to be given as the first argument.
		1610
		1611
		1612	color *
		1613	color::new()
		1614	The generated C ++ code will call new.
		1615
		1616
		1617	RETVAL = new color();
		1618	The following is an example of a typemap that could be used for this C ++ example.
		1619
		1620
		1621	TYPEMAP
		1622	color * O_OBJECT
		1623	OUTPUT
		1624	# The Perl object is blessed into 'CLASS', which should be a
		1625	# char* having the name of the package for the blessing.
		1626	O_OBJECT
		1627	sv_setref_pv( $arg, CLASS, (void*)$var );
		1628	INPUT
		1629	O_OBJECT
		1630	if( sv_isobject($arg)
		1631
		1632
		1633	__Interface Strategy__
		1634
		1635
		1636	When designing an interface between Perl and a C library a
		1637	straight translation from C to XS (such as
		1638	created by h2xs -x) is often sufficient. However,
		1639	sometimes the interface will look very C-like and
		1640	occasionally nonintuitive, especially when the C function
		1641	modifies one of its parameters, or returns failure inband
		1642	(as in ``negative return values mean failure''). In cases
		1643	where the programmer wishes to create a more Perl-like
		1644	interface the following strategy may help to identify the
		1645	more critical parts of the interface.
		1646
		1647
		1648	Identify the C functions with input/output or output
		1649	parameters. The XSUBs for these functions may be able to
		1650	return lists to Perl.
		1651
		1652
		1653	Identify the C functions which use some inband info as an
		1654	indication of failure. They may be candidates to return
		1655	undef or an empty list in case of failure. If the failure
		1656	may be detected without a call to the C function, you may
		1657	want to use an INIT: section to report the
		1658	failure. For failures detectable after the C function
		1659	returns one may want to use a POST_CALL:
		1660	section to process the failure. In more complicated cases
		1661	use CODE: or PPCODE:
		1662	sections.
		1663
		1664
		1665	If many functions use the same failure indication based on
		1666	the return value, you may want to create a special typedef
		1667	to handle this situation. Put
		1668
		1669
		1670	typedef int negative_is_failure;
		1671	near the beginning of XS file, and create an OUTPUT typemap entry for negative_is_failure which converts negative values to undef, or maybe ''croak()''s. After this the return value of type negative_is_failure will create more Perl-like interface.
		1672
		1673
		1674	Identify which values are used by only the C and
		1675	XSUB functions themselves, say, when a
		1676	parameter to a function should be a contents of a global
		1677	variable. If Perl does not need to access the contents of
		1678	the value then it may not be necessary to provide a
		1679	translation for that value from C to Perl.
		1680
		1681
		1682	Identify the pointers in the C function parameter lists and
		1683	return values. Some pointers may be used to implement
		1684	input/output or output parameters, they can be handled in
		1685	XS with the unary operator,
		1686	and, possibly, using the NO_INIT keyword.
		1687	Some others will require handling of types like int
		1688	*, and one needs to decide what a useful Perl
		1689	translation will do in such a case. When the semantic is
		1690	clear, it is advisable to put the translation into a typemap
		1691	file.
		1692
		1693
		1694	Identify the structures used by the C functions. In many
		1695	cases it may be helpful to use the T_PTROBJ typemap for
		1696	these structures so they can be manipulated by Perl as
		1697	blessed objects. (This is handled automatically by h2xs
		1698	-x.)
		1699
		1700
		1701	If the same C type is used in several different contexts
		1702	which require different translations, typedef
		1703	several new types mapped to this C type, and create separate
		1704	''typemap'' entries for these new types. Use these types
		1705	in declarations of return type and parameters to
		1706	XSUBs.
		1707
		1708
		1709	__Perl Objects And C Structures__
		1710
		1711
		1712	When dealing with C structures one should select either
		1713	__T_PTROBJ__ or __T_PTRREF__ for the XS
		1714	type. Both types are designed to handle pointers to complex
		1715	objects. The T_PTRREF type will allow the Perl object to be
		1716	unblessed while the T_PTROBJ type requires that the object
		1717	be blessed. By using T_PTROBJ one can achieve a form of
		1718	type-checking because the XSUB will attempt
		1719	to verify that the Perl object is of the expected
		1720	type.
		1721
		1722
		1723	The following XS code shows the
		1724	''getnetconfigent()'' function which is used with
		1725	ONC+ TIRPC . The ''getnetconfigent()''
		1726	function will return a pointer to a C structure and has the
		1727	C prototype shown below. The example will demonstrate how
		1728	the C pointer will become a Perl reference. Perl will
		1729	consider this reference to be a pointer to a blessed object
		1730	and will attempt to call a destructor for the object. A
		1731	destructor will be provided in the XS source
		1732	to free the memory used by ''getnetconfigent()''.
		1733	Destructors in XS can be created by
		1734	specifying an XSUB function whose name ends
		1735	with the word __DESTROY__ .
		1736	XS destructors can be used to free memory
		1737	which may have been malloc'd by another XSUB
		1738	.
		1739
		1740
		1741	struct netconfig *getnetconfigent(const char *netid);
		1742	A typedef will be created for struct netconfig. The Perl object will be blessed in a class matching the name of the C type, with the tag Ptr appended, and the name should not have embedded spaces if it will be a Perl package name. The destructor will be placed in a class corresponding to the class of the object and the PREFIX keyword will be used to trim the name to the word DESTROY as Perl will expect.
		1743
		1744
		1745	typedef struct netconfig Netconfig;
		1746	MODULE = RPC PACKAGE = RPC
		1747	Netconfig *
		1748	getnetconfigent(netid)
		1749	char *netid
2	perry	1750	MODULE = RPC PACKAGE = !NetconfigPtr PREFIX = rpcb_
1	perry	1751	void
		1752	rpcb_DESTROY(netconf)
		1753	Netconfig *netconf
		1754	CODE:
		1755	printf(
		1756	This example requires the following typemap entry. Consult the typemap section for more information about adding new typemaps for an extension.
		1757
		1758
		1759	TYPEMAP
		1760	Netconfig * T_PTROBJ
		1761	This example will be used with the following Perl statements.
		1762
		1763
		1764	use RPC;
		1765	$netconf = getnetconfigent(
		1766	When Perl destroys the object referenced by $netconf it will send the object to the supplied XSUB DESTROY function. Perl cannot determine, and does not care, that this object is a C struct and not a Perl object. In this sense, there is no difference between the object created by the ''getnetconfigent()'' XSUB and an object created by a normal Perl subroutine.
		1767
		1768
		1769	__The Typemap__
		1770
		1771
		1772	The typemap is a collection of code fragments which are used
		1773	by the __xsubpp__ compiler to map C function parameters
		1774	and values to Perl values. The typemap file may consist of
		1775	three sections labelled TYPEMAP, INPUT,
		1776	and OUTPUT. An unlabelled initial section is
		1777	assumed to be a TYPEMAP section. The
		1778	INPUT section tells the compiler how to
		1779	translate Perl values into variables of certain C types. The
		1780	OUTPUT section tells the compiler how to
		1781	translate the values from certain C types into values Perl
		1782	can understand. The TYPEMAP section tells the
		1783	compiler which of the INPUT and
		1784	OUTPUT code fragments should be used to map a
		1785	given C type to a Perl value. The section labels
		1786	TYPEMAP, INPUT, or OUTPUT must
		1787	begin in the first column on a line by themselves, and must
		1788	be in uppercase.
		1789
		1790
2	perry	1791	The default typemap in the lib/!ExtUtils directory
1	perry	1792	of the Perl source contains many useful types which can be
		1793	used by Perl extensions. Some extensions define additional
		1794	typemaps which they keep in their own directory. These
		1795	additional typemaps may reference INPUT and
		1796	OUTPUT maps in the main typemap. The
		1797	__xsubpp__ compiler will allow the extension's own
		1798	typemap to override any mappings which are in the default
		1799	typemap.
		1800
		1801
		1802	Most extensions which require a custom typemap will need
		1803	only the TYPEMAP section of the typemap file.
		1804	The custom typemap used in the ''getnetconfigent()''
		1805	example shown earlier demonstrates what may be the typical
		1806	use of extension typemaps. That typemap is used to equate a
		1807	C structure with the T_PTROBJ typemap. The typemap used by
		1808	''getnetconfigent()'' is shown here. Note that the C type
		1809	is separated from the XS type with a tab and
		1810	that the C unary operator * is considered to be a
		1811	part of the C type name.
		1812
		1813
		1814	TYPEMAP
		1815	Netconfig *
		1816	Here's a more complicated example: suppose that you wanted struct netconfig to be blessed into the class Net::Config. One way to do this is to use underscores (_) to separate package names, as follows:
		1817
		1818
		1819	typedef struct netconfig * Net_Config;
		1820	And then provide a typemap entry T_PTROBJ_SPECIAL that maps underscores to double-colons (::), and declare Net_Config to be of that type:
		1821
		1822
		1823	TYPEMAP
		1824	Net_Config T_PTROBJ_SPECIAL
		1825	INPUT
		1826	T_PTROBJ_SPECIAL
		1827	if (sv_derived_from($arg,
		1828	OUTPUT
		1829	T_PTROBJ_SPECIAL
		1830	sv_setref_pv($arg,
		1831	The INPUT and OUTPUT sections substitute underscores for double-colons on the fly, giving the desired effect. This example demonstrates some of the power and versatility of the typemap facility.
		1832	!!EXAMPLES
		1833
		1834
		1835	File RPC.xs: Interface to some ONC+
		1836	RPC bind library functions.
		1837
		1838
		1839	#include
		1840	#include
		1841	typedef struct netconfig Netconfig;
		1842	MODULE = RPC PACKAGE = RPC
		1843	SV *
		1844	rpcb_gettime(host=
		1845	Netconfig *
		1846	getnetconfigent(netid=
2	perry	1847	MODULE = RPC PACKAGE = !NetconfigPtr PREFIX = rpcb_
1	perry	1848	void
		1849	rpcb_DESTROY(netconf)
		1850	Netconfig *netconf
		1851	CODE:
		1852	printf(
		1853	File typemap: Custom typemap for RPC .xs.
		1854
		1855
		1856	TYPEMAP
		1857	Netconfig * T_PTROBJ
		1858	File RPC.pm: Perl module for the RPC extension.
		1859
		1860
		1861	package RPC;
		1862	require Exporter;
2	perry	1863	require !DynaLoader;
		1864	@ISA = qw(Exporter !DynaLoader);
1	perry	1865	@EXPORT = qw(rpcb_gettime getnetconfigent);
		1866	bootstrap RPC;
		1867	1;
		1868	File rpctest.pl: Perl test program for the RPC extension.
		1869
		1870
		1871	use RPC;
		1872	$netconf = getnetconfigent();
		1873	$a = rpcb_gettime();
		1874	print
		1875	$netconf = getnetconfigent(
		1876	!!XS VERSION
		1877
		1878
		1879	This document covers features supported by xsubpp
		1880	1.935.
		1881	!!AUTHOR
		1882
		1883
		1884	Originally written by Dean Roehrich
		1885	roehrich@cray.com''''
		1886
		1887
		1888	Maintained since 1996 by The Perl Porters
		1889	perlbug@perl.org''''
		1890	----