*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> perlcall (1)              


PERLCALL(1)							   PERLCALL(1)

NAME    [Toc]    [Back]

     perlcall -	Perl calling conventions from C

DESCRIPTION    [Toc]    [Back]

     The purpose of this document is to	show you how to	call Perl subroutines
     directly from C, i.e., how	to write callbacks.

     Apart from	discussing the C interface provided by Perl for	writing
     callbacks the document uses a series of examples to show how the
     interface actually	works in practice.  In addition	some techniques	for
     coding callbacks are covered.

     Examples where callbacks are necessary include

     o An Error	Handler
	  You have created an XSUB interface to	an application's C API.

	  A fairly common feature in applications is to	allow you to define a
	  C function that will be called whenever something nasty occurs. What
	  we would like	is to be able to specify a Perl	subroutine that	will
	  be called instead.

     o An Event	Driven Program
	  The classic example of where callbacks are used is when writing an
	  event	driven program like for	an X windows application.  In this
	  case you register functions to be called whenever specific events
	  occur, e.g., a mouse button is pressed, the cursor moves into	a
	  window or a menu item	is selected.

     Although the techniques described here are	applicable when	embedding Perl
     in	a C program, this is not the primary goal of this document.  There are
     other details that	must be	considered and are specific to embedding Perl.
     For details on embedding Perl in C	refer to the perlembed manpage.

     Before you	launch yourself	head first into	the rest of this document, it
     would be a	good idea to have read the following two documents - the
     perlxs manpage and	the perlguts manpage.


     Although this stuff is easier to explain using examples, you first	need
     be	aware of a few important definitions.

     Perl has a	number of C functions that allow you to	call Perl subroutines.
     They are

	 I32 perl_call_sv(SV* sv, I32 flags) ;
	 I32 perl_call_pv(char *subname, I32 flags) ;
	 I32 perl_call_method(char *methname, I32 flags) ;
	 I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;

     The key function is perl_call_sv.	All the	other functions	are fairly
     simple wrappers which make	it easier to call Perl subroutines in special

									Page 1

PERLCALL(1)							   PERLCALL(1)

     cases. At the end of the day they will all	call perl_call_sv to invoke
     the Perl subroutine.

     All the perl_call_* functions have	a flags	parameter which	is used	to
     pass a bit	mask of	options	to Perl.  This bit mask	operates identically
     for each of the functions.	 The settings available	in the bit mask	are
     discussed in the section on FLAG VALUES.

     Each of the functions will	now be discussed in turn.

	  perl_call_sv takes two parameters, the first,	sv, is an SV*.	This
	  allows you to	specify	the Perl subroutine to be called either	as a C
	  string (which	has first been converted to an SV) or a	reference to a
	  subroutine. The section, Using perl_call_sv, shows how you can make
	  use of perl_call_sv.

	  The function,	perl_call_pv, is similar to perl_call_sv except	it
	  expects its first parameter to be a C	char* which identifies the
	  Perl subroutine you want to call, e.g., perl_call_pv("fred", 0).  If
	  the subroutine you want to call is in	another	package, just include
	  the package name in the string, e.g.,	"pkg::fred".

	  The function perl_call_method	is used	to call	a method from a	Perl
	  class.  The parameter	methname corresponds to	the name of the	method
	  to be	called.	 Note that the class that the method belongs to	is
	  passed on the	Perl stack rather than in the parameter	list. This
	  class	can be either the name of the class (for a static method) or a
	  reference to an object (for a	virtual	method).  See the perlobj
	  manpage for more information on static and virtual methods and the
	  section on Using perl_call_method for	an example of using

	  perl_call_argv calls the Perl	subroutine specified by	the C string
	  stored in the	subname	parameter. It also takes the usual flags
	  parameter.  The final	parameter, argv, consists of a NULL terminated
	  list of C strings to be passed as parameters to the Perl subroutine.
	  See Using perl_call_argv.

     All the functions return an integer. This is a count of the number	of
     items returned by the Perl	subroutine. The	actual items returned by the
     subroutine	are stored on the Perl stack.

     As	a general rule you should always check the return value	from these
     functions.	 Even if you are expecting only	a particular number of values
     to	be returned from the Perl subroutine, there is nothing to stop someone
     from doing	something unexpected - don't say you haven't been warned.

									Page 2

PERLCALL(1)							   PERLCALL(1)

FLAG VALUES    [Toc]    [Back]

     The flags parameter in all	the perl_call_*	functions is a bit mask	which
     can consist of any	combination of the symbols defined below, OR'ed

     G_VOID    [Toc]    [Back]

     Calls the Perl subroutine in a void context.

     This flag has 2 effects:

     1.	  It indicates to the subroutine being called that it is executing in
	  a void context (if it	executes wantarray the result will be the
	  undefined value).

     2.	  It ensures that nothing is actually returned from the	subroutine.

     The value returned	by the perl_call_* function indicates how many items
     have been returned	by the Perl subroutine - in this case it will be 0.

     G_SCALAR    [Toc]    [Back]

     Calls the Perl subroutine in a scalar context.  This is the default
     context flag setting for all the perl_call_* functions.

     This flag has 2 effects:

     1.	  It indicates to the subroutine being called that it is executing in
	  a scalar context (if it executes wantarray the result	will be

     2.	  It ensures that only a scalar	is actually returned from the
	  subroutine.  The subroutine can, of course,  ignore the wantarray
	  and return a list anyway. If so, then	only the last element of the
	  list will be returned.

     The value returned	by the perl_call_* function indicates how many items
     have been returned	by the Perl subroutine - in this case it will be
     either 0 or 1.

     If	0, then	you have specified the G_DISCARD flag.

     If	1, then	the item actually returned by the Perl subroutine will be
     stored on the Perl	stack -	the section Returning a	Scalar shows how to
     access this value on the stack.  Remember that regardless of how many
     items the Perl subroutine returns,	only the last one will be accessible
     from the stack - think of the case	where only one value is	returned as
     being a list with only one	element.  Any other items that were returned
     will not exist by the time	control	returns	from the perl_call_* function.
     The section Returning a list in a scalar context shows an example of this

									Page 3

PERLCALL(1)							   PERLCALL(1)

     G_ARRAY    [Toc]    [Back]

     Calls the Perl subroutine in a list context.

     As	with G_SCALAR, this flag has 2 effects:

     1.	  It indicates to the subroutine being called that it is executing in
	  an array context (if it executes wantarray the result	will be	true).

     2.	  It ensures that all items returned from the subroutine will be
	  accessible when control returns from the perl_call_* function.

     The value returned	by the perl_call_* function indicates how many items
     have been returned	by the Perl subroutine.

     If	0, then	you have specified the G_DISCARD flag.

     If	not 0, then it will be a count of the number of	items returned by the
     subroutine. These items will be stored on the Perl	stack.	The section
     Returning a list of values	gives an example of using the G_ARRAY flag and
     the mechanics of accessing	the returned items from	the Perl stack.

     G_DISCARD    [Toc]    [Back]

     By	default, the perl_call_* functions place the items returned from by
     the Perl subroutine on the	stack.	If you are not interested in these
     items, then setting this flag will	make Perl get rid of them
     automatically for you.  Note that it is still possible to indicate	a
     context to	the Perl subroutine by using either G_SCALAR or	G_ARRAY.

     If	you do not set this flag then it is very important that	you make sure
     that any temporaries (i.e., parameters passed to the Perl subroutine and
     values returned from the subroutine) are disposed of yourself.  The
     section Returning a Scalar	gives details of how to	dispose	of these
     temporaries explicitly and	the section Using Perl to dispose of
     temporaries discusses the specific	circumstances where you	can ignore the
     problem and let Perl deal with it for you.

     G_NOARGS    [Toc]    [Back]

     Whenever a	Perl subroutine	is called using	one of the perl_call_*
     functions,	it is assumed by default that parameters are to	be passed to
     the subroutine.  If you are not passing any parameters to the Perl
     subroutine, you can save a	bit of time by setting this flag.  It has the
     effect of not creating the	@_ array for the Perl subroutine.

     Although the functionality	provided by this flag may seem
     straightforward, it should	be used	only if	there is a good	reason to do
     so.  The reason for being cautious	is that	even if	you have specified the
     G_NOARGS flag, it is still	possible for the Perl subroutine that has been
     called to think that you have passed it parameters.

									Page 4

PERLCALL(1)							   PERLCALL(1)

     In	fact, what can happen is that the Perl subroutine you have called can
     access the	@_ array from a	previous Perl subroutine.  This	will occur
     when the code that	is executing the perl_call_* function has itself been
     called from another Perl subroutine. The code below illustrates this

	 sub fred
	   { print "@_\n"  }

	 sub joe
	   { &fred }

	 &joe(1,2,3) ;

     This will print

	 1 2 3

     What has happened is that fred accesses the @_ array which	belongs	to

     G_EVAL    [Toc]    [Back]

     It	is possible for	the Perl subroutine you	are calling to terminate
     abnormally, e.g., by calling die explicitly or by not actually existing.
     By	default, when either of	these of events	occurs,	the process will
     terminate immediately.  If	though,	you want to trap this type of event,
     specify the G_EVAL	flag.  It will put an eval { } around the subroutine

     Whenever control returns from the perl_call_* function you	need to	check
     the $@ variable as	you would in a normal Perl script.

     The value returned	from the perl_call_* function is dependent on what
     other flags have been specified and whether an error has occurred.	 Here
     are all the different cases that can occur:

     o	  If the perl_call_* function returns normally,	then the value
	  returned is as specified in the previous sections.

     o	  If G_DISCARD is specified, the return	value will always be 0.

     o	  If G_ARRAY is	specified and an error has occurred, the return	value
	  will always be 0.

     o	  If G_SCALAR is specified and an error	has occurred, the return value
	  will be 1 and	the value on the top of	the stack will be undef. This
	  means	that if	you have already detected the error by checking	$@ and
	  you want the program to continue, you	must remember to pop the undef
	  from the stack.

									Page 5

PERLCALL(1)							   PERLCALL(1)

     See Using G_EVAL for details on using G_EVAL.

     G_KEEPERR    [Toc]    [Back]

     You may have noticed that using the G_EVAL	flag described above will
     always clear the $@ variable and set it to	a string describing the	error
     iff there was an error in the called code.	 This unqualified resetting of
     $@	can be problematic in the reliable identification of errors using the
     eval {} mechanism,	because	the possibility	exists that perl will call
     other code	(end of	block processing code, for example) between the	time
     the error causes $@ to be set within eval {}, and the subsequent
     statement which checks for	the value of $@	gets executed in the user's

     This scenario will	mostly be applicable to	code that is meant to be
     called from within	destructors, asynchronous callbacks, signal handlers,
     __DIE__ or	__WARN__ hooks,	and tie	functions.  In such situations,	you
     will not want to clear $@ at all, but simply to append any	new errors to
     any existing value	of $@.

     The G_KEEPERR flag	is meant to be used in conjunction with	G_EVAL in
     perl_call_* functions that	are used to implement such code.  This flag
     has no effect when	G_EVAL is not used.

     When G_KEEPERR is used, any errors	in the called code will	be prefixed
     with the string "\t(in cleanup)", and appended to the current value of

     The G_KEEPERR flag	was introduced in Perl version 5.002.

     See Using G_KEEPERR for an	example	of a situation that warrants the use
     of	this flag.

     Determining the Context    [Toc]    [Back]

     As	mentioned above, you can determine the context of the currently
     executing subroutine in Perl with wantarray.  The equivalent test can be
     made in C by using	the GIMME_V macro, which returns G_ARRAY if you	have
     been called in an array context, G_SCALAR if in a scalar context, or
     G_VOID if in a void context (i.e. the return value	will not be used).  An
     older version of this macro is called GIMME; in a void context it returns
     G_SCALAR instead of G_VOID.  An example of	using the GIMME_V macro	is
     shown in section Using GIMME_V.

KNOWN PROBLEMS    [Toc]    [Back]

     This section outlines all known problems that exist in the	perl_call_*

     1.	  If you are intending to make use of both the G_EVAL and G_SCALAR
	  flags	in your	code, use a version of Perl greater than 5.000.	 There
	  is a bug in version 5.000 of Perl which means	that the combination
	  of these two flags will not work as described	in the section FLAG

									Page 6

PERLCALL(1)							   PERLCALL(1)


	  Specifically,	if the two flags are used when calling a subroutine
	  and that subroutine does not call die, the value returned by
	  perl_call_* will be wrong.

     2.	  In Perl 5.000	and 5.001 there	is a problem with using	perl_call_* if
	  the Perl sub you are calling attempts	to trap	a die.

	  The symptom of this problem is that the called Perl sub will
	  continue to completion, but whenever it attempts to pass control
	  back to the XSUB, the	program	will immediately terminate.

	  For example, say you want to call this Perl sub

	      sub fred
		  eval { die "Fatal Error" ; }
		  print	"Trapped error:	$@\n"
		      if $@ ;

	  via this XSUB

		  PUSHMARK(sp) ;
		  perl_call_pv("fred", G_DISCARD|G_NOARGS) ;
		  fprintf(stderr, "back	in Call_fred\n") ;

	  When Call_fred is executed it	will print

	      Trapped error: Fatal Error

	  As control never returns to Call_fred, the "back in Call_fred"
	  string will not get printed.

	  To work around this problem, you can either upgrade to Perl 5.002 or
	  higher, or use the G_EVAL flag with perl_call_* as shown below

		  PUSHMARK(sp) ;
		  perl_call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ;
		  fprintf(stderr, "back	in Call_fred\n") ;

									Page 7

PERLCALL(1)							   PERLCALL(1)

     Enough of the definition talk, let's have a few examples.

     Perl provides many	macros to assist in accessing the Perl stack.
     Wherever possible,	these macros should always be used when	interfacing to
     Perl internals.  We hope this should make the code	less vulnerable	to any
     changes made to Perl in the future.

     Another point worth noting	is that	in the first series of examples	I have
     made use of only the perl_call_pv function.  This has been	done to	keep
     the code simpler and ease you into	the topic.  Wherever possible, if the
     choice is between using perl_call_pv and perl_call_sv, you	should always
     try to use	perl_call_sv.  See Using perl_call_sv for details.

     No	Parameters, Nothing returned

     This first	trivial	example	will call a Perl subroutine, PrintUID, to
     print out the UID of the process.

	 sub PrintUID
	     print "UID	is $<\n" ;

     and here is a C function to call it

	 static	void
	     dSP ;

	     PUSHMARK(sp) ;
	     perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;

     Simple, eh.

     A few points to note about	this example.

     1.	  Ignore dSP and PUSHMARK(sp) for now. They will be discussed in the
	  next example.

     2.	  We aren't passing any	parameters to PrintUID so G_NOARGS can be

     3.	  We aren't interested in anything returned from PrintUID, so
	  G_DISCARD is specified. Even if PrintUID was changed to return some
	  value(s), having specified G_DISCARD will mean that they will	be
	  wiped	by the time control returns from perl_call_pv.

									Page 8

PERLCALL(1)							   PERLCALL(1)

     4.	  As perl_call_pv is being used, the Perl subroutine is	specified as a
	  C string. In this case the subroutine	name has been 'hard-wired'
	  into the code.

     5.	  Because we specified G_DISCARD, it is	not necessary to check the
	  value	returned from perl_call_pv. It will always be 0.

     Passing Parameters    [Toc]    [Back]

     Now let's make a slightly more complex example. This time we want to call
     a Perl subroutine,	LeftString, which will take 2 parameters - a string
     ($s) and an integer ($n).	The subroutine will simply print the first $n
     characters	of the string.

     So	the Perl subroutine would look like this

	 sub LeftString
	     my($s, $n)	= @_ ;
	     print substr($s, 0, $n), "\n" ;

     The C function required to	call LeftString	would look like	this.

	 static	void
	 call_LeftString(a, b)
	 char *	a ;
	 int b ;
	     dSP ;

	     PUSHMARK(sp) ;
	     XPUSHs(sv_2mortal(newSVpv(a, 0)));
	     PUTBACK ;

	     perl_call_pv("LeftString",	G_DISCARD);

     Here are a	few notes on the C function call_LeftString.

     1.	  Parameters are passed	to the Perl subroutine using the Perl stack.
	  This is the purpose of the code beginning with the line dSP and
	  ending with the line PUTBACK.

     2.	  If you are going to put something onto the Perl stack, you need to
	  know where to	put it.	This is	the purpose of the macro dSP - it
	  declares and initializes a local copy	of the Perl stack pointer.

	  All the other	macros which will be used in this example require you
	  to have used this macro.

									Page 9

PERLCALL(1)							   PERLCALL(1)

	  The exception	to this	rule is	if you are calling a Perl subroutine
	  directly from	an XSUB	function. In this case it is not necessary to
	  use the dSP macro explicitly - it will be declared for you

     3.	  Any parameters to be pushed onto the stack should be bracketed by
	  the PUSHMARK and PUTBACK macros.  The	purpose	of these two macros,
	  in this context, is to count the number of parameters	you are
	  pushing automatically.  Then whenever	Perl is	creating the @_	array
	  for the subroutine, it knows how big to make it.

	  The PUSHMARK macro tells Perl	to make	a mental note of the current
	  stack	pointer. Even if you aren't passing any	parameters (like the
	  example shown	in the section No Parameters, Nothing returned)	you
	  must still call the PUSHMARK macro before you	can call any of	the
	  perl_call_* functions	- Perl still needs to know that	there are no

	  The PUTBACK macro sets the global copy of the	stack pointer to be
	  the same as our local	copy. If we didn't do this perl_call_pv
	  wouldn't know	where the two parameters we pushed were	- remember
	  that up to now all the stack pointer manipulation we have done is
	  with our local copy, not the global copy.

     4.	  The only flag	specified this time is G_DISCARD. Because we are
	  passing 2 parameters to the Perl subroutine this time, we have not
	  specified G_NOARGS.

     5.	  Next,	we come	to XPUSHs. This	is where the parameters	actually get
	  pushed onto the stack. In this case we are pushing a string and an

	  See the section on XSUBs and the Argument Stack in the perlguts
	  manpage for details on how the XPUSH macros work.

     6.	  Finally, LeftString can now be called	via the	perl_call_pv function.

     Returning a Scalar    [Toc]    [Back]

     Now for an	example	of dealing with	the items returned from	a Perl

     Here is a Perl subroutine,	Adder, that takes 2 integer parameters and
     simply returns their sum.

	 sub Adder
	     my($a, $b)	= @_ ;
	     $a	+ $b ;

     Because we	are now	concerned with the return value	from Adder, the	C

								       Page 10

PERLCALL(1)							   PERLCALL(1)

     function required to call it is now a bit more complex.

	 static	void
	 call_Adder(a, b)
	 int a ;
	 int b ;
	     dSP ;
	     int count ;

	     ENTER ;

	     PUSHMARK(sp) ;
	     PUTBACK ;

	     count = perl_call_pv("Adder", G_SCALAR);

	     SPAGAIN ;

	     if	(count != 1)
		 croak("Big trouble\n")	;

	     printf ("The sum of %d and	%d is %d\n", a,	b, POPi) ;

	     PUTBACK ;
	     FREETMPS ;
	     LEAVE ;

     Points to note this time are

     1.	  The only flag	specified this time was	G_SCALAR. That means the @_
	  array	will be	created	and that the value returned by Adder will
	  still	exist after the	call to	perl_call_pv.

     2.	  Because we are interested in what is returned	from Adder we cannot
	  specify G_DISCARD. This means	that we	will have to tidy up the Perl
	  stack	and dispose of any temporary values ourselves. This is the
	  purpose of

	      ENTER ;
	      SAVETMPS ;

	  at the start of the function,	and

	      FREETMPS ;
	      LEAVE ;

	  at the end. The ENTER/SAVETMPS pair creates a	boundary for any

								       Page 11

PERLCALL(1)							   PERLCALL(1)

	  temporaries we create.  This means that the temporaries we get rid
	  of will be limited to	those which were created after these calls.

	  The FREETMPS/LEAVE pair will get rid of any values returned by the
	  Perl subroutine, plus	it will	also dump the mortal SVs we have
	  created.  Having ENTER/SAVETMPS at the beginning of the code makes
	  sure that no other mortals are destroyed.

	  Think	of these macros	as working a bit like using { and } in Perl to
	  limit	the scope of local variables.

	  See the section Using	Perl to	dispose	of temporaries for details of
	  an alternative to using these	macros.

     3.	  The purpose of the macro SPAGAIN is to refresh the local copy	of the
	  stack	pointer. This is necessary because it is possible that the
	  memory allocated to the Perl stack has been reallocated whilst in
	  the perl_call_pv call.

	  If you are making use	of the Perl stack pointer in your code you
	  must always refresh the local	copy using SPAGAIN whenever you	make
	  use of the perl_call_* functions or any other	Perl internal

     4.	  Although only	a single value was expected to be returned from	Adder,
	  it is	still good practice to check the return	code from perl_call_pv

	  Expecting a single value is not quite	the same as knowing that there
	  will be one. If someone modified Adder to return a list and we
	  didn't check for that	possibility and	take appropriate action	the
	  Perl stack would end up in an	inconsistent state. That is something
	  you really don't want	to happen ever.

     5.	  The POPi macro is used here to pop the return	value from the stack.
	  In this case we wanted an integer, so	POPi was used.

	  Here is the complete list of POP macros available, along with	the
	  types	they return.

	      POPs	  SV
	      POPp	  pointer
	      POPn	  double
	      POPi	  integer
	      POPl	  long

     6.	  The final PUTBACK is used to leave the Perl stack in a consistent
	  state	before exiting the function.  This is necessary	because	when
	  we popped the	return value from the stack with POPi it updated only
	  our local copy of the	stack pointer.	Remember, PUTBACK sets the
	  global stack pointer to be the same as our local copy.

								       Page 12

PERLCALL(1)							   PERLCALL(1)

     Returning a list of values    [Toc]    [Back]

     Now, let's	extend the previous example to return both the sum of the
     parameters	and the	difference.

     Here is the Perl subroutine

	 sub AddSubtract
	    my($a, $b) = @_ ;
	    ($a+$b, $a-$b) ;

     and this is the C function

	 static	void
	 call_AddSubtract(a, b)
	 int a ;
	 int b ;
	     dSP ;
	     int count ;

	     ENTER ;

	     PUSHMARK(sp) ;
	     PUTBACK ;

	     count = perl_call_pv("AddSubtract", G_ARRAY);

	     SPAGAIN ;

	     if	(count != 2)
		 croak("Big trouble\n")	;

	     printf ("%d - %d =	%d\n", a, b, POPi) ;
	     printf ("%d + %d =	%d\n", a, b, POPi) ;

	     PUTBACK ;
	     FREETMPS ;
	     LEAVE ;

     If	call_AddSubtract is called like	this

	 call_AddSubtract(7, 4)	;

     then here is the output

								       Page 13

PERLCALL(1)							   PERLCALL(1)

	 7 - 4 = 3
	 7 + 4 = 11


     1.	  We wanted array context, so G_ARRAY was used.

     2.	  Not surprisingly POPi	is used	twice this time	because	we were
	  retrieving 2 values from the stack. The important thing to note is
	  that when using the POP* macros they come off	the stack in reverse

     Returning a list in a scalar context    [Toc]    [Back]

     Say the Perl subroutine in	the previous section was called	in a scalar
     context, like this

	 static	void
	 call_AddSubScalar(a, b)
	 int a ;
	 int b ;
	     dSP ;
	     int count ;
	     int i ;

	     ENTER ;

	     PUSHMARK(sp) ;
	     PUTBACK ;

	     count = perl_call_pv("AddSubtract", G_SCALAR);

	     SPAGAIN ;

	     printf ("Items Returned = %d\n", count) ;

	     for (i = 1	; i <= count ; ++i)
		 printf	("Value	%d = %d\n", i, POPi) ;

	     PUTBACK ;
	     FREETMPS ;
	     LEAVE ;

     The other modification made is that call_AddSubScalar will	print the
     number of items returned from the Perl subroutine and their value (for
     simplicity	it assumes that	they are integer).  So if call_AddSubScalar is

								       Page 14

PERLCALL(1)							   PERLCALL(1)

	 call_AddSubScalar(7, 4) ;

     then the output will be

	 Items Returned	= 1
	 Value 1 = 3

     In	this case the main point to note is that only the last item in the
     list is returned from the subroutine, AddSubtract actually	made it	back
     to	call_AddSubScalar.

     Returning Data from Perl via the parameter	list

     It	is also	possible to return values directly via the parameter list -
     whether it	is actually desirable to do it is another matter entirely.

     The Perl subroutine, Inc, below takes 2 parameters	and increments each

	 sub Inc
	     ++	$_[0] ;
	     ++	$_[1] ;

     and here is a C function to call it.

	 static	void
	 call_Inc(a, b)
	 int a ;
	 int b ;
	     dSP ;
	     int count ;
	     SV	* sva ;
	     SV	* svb ;

	     ENTER ;

	     sva = sv_2mortal(newSViv(a)) ;
	     svb = sv_2mortal(newSViv(b)) ;

	     PUSHMARK(sp) ;
	     PUTBACK ;

	     count = perl_call_pv("Inc", G_DISCARD);

								       Page 15

PERLCALL(1)							   PERLCALL(1)

	     if	(count != 0)
		 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
			count) ;

	     printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
	     printf ("%d + 1 = %d\n", b, SvIV(svb)) ;

	     FREETMPS ;
	     LEAVE ;

     To	be able	to access the two parameters that were pushed onto the stack
     after they	return from perl_call_pv it is necessary to make a note	of
     their addresses - thus the	two variables sva and svb.

     The reason	this is	necessary is that the area of the Perl stack which
     held them will very likely	have been overwritten by something else	by the
     time control returns from perl_call_pv.

     Using G_EVAL    [Toc]    [Back]

     Now an example using G_EVAL. Below	is a Perl subroutine which computes
     the difference of its 2 parameters. If this would result in a negative
     result, the subroutine calls die.

	 sub Subtract
	     my	($a, $b) = @_ ;

	     die "death	can be fatal\n"	if $a <	$b ;

	     $a	- $b ;

     and some C	to call	it

	 static	void
	 call_Subtract(a, b)
	 int a ;
	 int b ;
	     dSP ;
	     int count ;

	     ENTER ;

	     PUSHMARK(sp) ;
	     PUTBACK ;

								       Page 16

PERLCALL(1)							   PERLCALL(1)

	     count = perl_call_pv("Subtract", G_EVAL|G_SCALAR);

	     SPAGAIN ;

	     /*	Check the eval first */
	     if	(SvTRUE(GvSV(errgv)))
		 printf	("Uh oh	- %s\n", SvPV(GvSV(errgv), na))	;
		 POPs ;
		 if (count != 1)
		    croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
			     count) ;

		 printf	("%d - %d = %d\n", a, b, POPi) ;

	     PUTBACK ;
	     FREETMPS ;
	     LEAVE ;

     If	call_Subtract is called	thus

	 call_Subtract(4, 5)

     the following will	be printed

	 Uh oh - death can be fatal


     1.	  We want to be	able to	catch the die so we have used the G_EVAL flag.
	  Not specifying this flag would mean that the program would terminate
	  immediately at the die statement in the subroutine Subtract.

     2.	  The code

	      if (SvTRUE(GvSV(errgv)))
		  printf ("Uh oh - %s\n", SvPV(GvSV(errgv), na)) ;
		  POPs ;

	  is the direct	equivalent of this bit of Perl

	      print "Uh	oh - $@\n" if $@ ;

	  errgv	is a perl global of type GV * that points to the symbol	table
	  entry	containing the error.  GvSV(errgv) therefore refers to the C

								       Page 17

PERLCALL(1)							   PERLCALL(1)

	  equivalent of	$@.

     3.	  Note that the	stack is popped	using POPs in the block	where
	  SvTRUE(GvSV(errgv)) is true.	This is	necessary because whenever a
	  perl_call_* function invoked with G_EVAL|G_SCALAR returns an error,
	  the top of the stack holds the value undef. Because we want the
	  program to continue after detecting this error, it is	essential that
	  the stack is tidied up by removing the undef.

     Using G_KEEPERR    [Toc]    [Back]

     Consider this rather facetious example, where we have used	an XS version
     of	the call_Subtract example above	inside a destructor:

	 package Foo;
	 sub new { bless {}, $_[0] }
	 sub Subtract {
	     my($a,$b) = @_;
	     die "death	can be fatal" if $a < $b ;
	     $a	- $b;
	 sub DESTROY { call_Subtract(5,	4); }
	 sub foo { die "foo dies"; }

	 package main;
	 eval {	Foo->new->foo };
	 print "Saw: $@" if $@;		    # should be, but isn't

     This example will fail to recognize that an error occurred	inside the
     eval {}.  Here's why: the call_Subtract code got executed while perl was
     cleaning up temporaries when exiting the eval block, and because
     call_Subtract is implemented with perl_call_pv using the G_EVAL flag, it
     promptly reset $@.	 This results in the failure of	the outermost test for
     $@, and thereby the failure of the	error trap.

     Appending the G_KEEPERR flag, so that the perl_call_pv call in
     call_Subtract reads:

	     count = perl_call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);

     will preserve the error and restore reliable error	handling.

     Using perl_call_sv    [Toc]    [Back]

     In	all the	previous examples I have 'hard-wired' the name of the Perl
     subroutine	to be called from C.  Most of the time though, it is more
     convenient	to be able to specify the name of the Perl subroutine from
     within the	Perl script.

     Consider the Perl code below

								       Page 18

PERLCALL(1)							   PERLCALL(1)

	 sub fred
	     print "Hello there\n" ;

	 CallSubPV("fred") ;

     Here is a snippet of XSUB which defines CallSubPV.

	     char *  name
	     PUSHMARK(sp) ;
	     perl_call_pv(name,	G_DISCARD|G_NOARGS) ;

     That is fine as far as it goes. The thing is, the Perl subroutine can be
     specified as only a string.  For Perl 4 this was adequate,	but Perl 5
     allows references to subroutines and anonymous subroutines.  This is
     where perl_call_sv	is useful.

     The code below for	CallSubSV is identical to CallSubPV except that	the
     name parameter is now defined as an SV* and we use	perl_call_sv instead
     of	perl_call_pv.

	     SV	*    name
	     PUSHMARK(sp) ;
	     perl_call_sv(name,	G_DISCARD|G_NOARGS) ;

     Because we	are using an SV	to call	fred the following can all be used

	 CallSubSV("fred") ;
	 CallSubSV(\&fred) ;
	 $ref =	\&fred ;
	 CallSubSV($ref) ;
	 CallSubSV( sub	{ print	"Hello there\n"	} ) ;

     As	you can	see, perl_call_sv gives	you much greater flexibility in	how
     you can specify the Perl subroutine.

     You should	note that if it	is necessary to	store the SV (name in the
     example above) which corresponds to the Perl subroutine so	that it	can be
     used later	in the program,	it not enough just to store a copy of the
     pointer to	the SV.	Say the	code above had been like this

	 static	SV * rememberSub ;

								       Page 19

PERLCALL(1)							   PERLCALL(1)

	     SV	*    name
	     rememberSub = name	;

	     PUSHMARK(sp) ;
	     perl_call_sv(rememberSub, G_DISCARD|G_NOARGS) ;

     The reason	this is	wrong is that by the time you come to use the pointer
     rememberSub in CallSavedSub1, it may or may not still refer to the	Perl
     subroutine	that was recorded in SaveSub1.	This is	particularly true for
     these cases

	 SaveSub1(\&fred) ;
	 CallSavedSub1() ;

	 SaveSub1( sub { print "Hello there\n" } ) ;
	 CallSavedSub1() ;

     By	the time each of the SaveSub1 statements above have been executed, the
     SV*s which	corresponded to	the parameters will no longer exist.  Expect
     an	error message from Perl	of the form

	 Can't use an undefined	value as a subroutine reference	at ...

     for each of the CallSavedSub1 lines.

     Similarly,	with this code

	 $ref =	\&fred ;
	 SaveSub1($ref)	;
	 $ref =	47 ;
	 CallSavedSub1() ;

     you can expect one	of these messages (which you actually get is dependent
     on	the version of Perl you	are using)

	 Not a CODE reference at ...
	 Undefined subroutine &main::47	called ...

     The variable $ref may have	referred to the	subroutine fred	whenever the
     call to SaveSub1 was made but by the time CallSavedSub1 gets called it
     now holds the number 47. Because we saved only a pointer to the original
     SV	in SaveSub1, any changes to $ref will be tracked by the	pointer
     rememberSub. This means that whenever CallSavedSub1 gets called, it will
     attempt to	execute	the code which is referenced by	the SV*	rememberSub.
     In	this case though, it now refers	to the integer 47, so expect Perl to
     complain loudly.

								       Page 20

PERLCALL(1)							   PERLCALL(1)

     A similar but more	subtle problem is illustrated with this	code

	 $ref =	\&fred ;
	 SaveSub1($ref)	;
	 $ref =	\&joe ;
	 CallSavedSub1() ;

     This time whenever	CallSavedSub1 get called it will execute the Perl
     subroutine	joe (assuming it exists) rather	than fred as was originally
     requested in the call to SaveSub1.

     To	get around these problems it is	necessary to take a full copy of the
     SV.  The code below shows SaveSub2	modified to do that

	 static	SV * keepSub = (SV*)NULL ;

	     SV	*    name
	     /*	Take a copy of the callback */
	     if	(keepSub == (SV*)NULL)
		 /* First time,	so create a new	SV */
		 keepSub = newSVsv(name) ;
		 /* Been here before, so overwrite */
		 SvSetSV(keepSub, name)	;

	     PUSHMARK(sp) ;
	     perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ;

     To	avoid creating a new SV	every time SaveSub2 is called, the function
     first checks to see if it has been	called before.	If not,	then space for
     a new SV is allocated and the reference to	the Perl subroutine, name is
     copied to the variable keepSub in one operation using newSVsv.
     Thereafter, whenever SaveSub2 is called the existing SV, keepSub, is
     overwritten with the new value using SvSetSV.

     Using perl_call_argv    [Toc]    [Back]

     Here is a Perl subroutine which prints whatever parameters	are passed to

	 sub PrintList
	     my(@list) = @_ ;

	     foreach (@list) { print "$_\n" }

								       Page 21

PERLCALL(1)							   PERLCALL(1)

     and here is an example of perl_call_argv which will call PrintList.

	 static	char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ;

	 static	void
	     dSP ;

	     perl_call_argv("PrintList", G_DISCARD, words) ;

     Note that it is not necessary to call PUSHMARK in this instance.  This is
     because perl_call_argv will do it for you.

     Using perl_call_method    [Toc]    [Back]

     Consider the following Perl code

	     package Mine ;

	     sub new
		 my($type) = shift ;
		 bless [@_]

	     sub Display
		 my ($self, $index) = @_ ;
		 print "$index:	$$self[$index]\n" ;

	     sub PrintID
		 my($class) = @_ ;
		 print "This is	Class $class version 1.0\n" ;

     It	implements just	a very simple class to manage an array.	 Apart from
     the constructor, new, it declares methods,	one static and one virtual.
     The static	method,	PrintID, prints	out simply the class name and a
     version number. The virtual method, Display, prints out a single element
     of	the array.  Here is an all Perl	example	of using it.

	 $a = new Mine ('red', 'green',	'blue')	;
	 $a->Display(1)	;
	 PrintID Mine;

     will print

								       Page 22

PERLCALL(1)							   PERLCALL(1)

	 1: green
	 This is Class Mine version 1.0

     Calling a Perl method from	C is fairly straightforward. The following
     things are	required

     o	  a reference to the object for	a virtual method or the	name of	the
	  class	for a static method.

     o	  the name of the method.

     o	  any other parameters specific	to the method.

     Here is a simple XSUB which illustrates the mechanics of calling both the
     PrintID and Display methods from C.

	 call_Method(ref, method, index)
	     SV	*    ref
	     char *  method
	     int	     index
	     XPUSHs(sv_2mortal(newSViv(index)))	;

	     perl_call_method(method, G_DISCARD) ;

	 call_PrintID(class, method)
	     char *  class
	     char *  method
	     XPUSHs(sv_2mortal(newSVpv(class, 0))) ;

	     perl_call_method(method, G_DISCARD) ;

     So	the methods PrintID and	Display	can be invoked like this

	 $a = new Mine ('red', 'green',	'blue')	;
	 call_Method($a, 'Display', 1) ;
	 call_PrintID('Mine', 'PrintID') ;

     The only thing to note is that in both the	static and virtual methods,
     the method	name is	not passed via the stack - it is used as the first
     parameter to perl_call_method.

								       Page 23

PERLCALL(1)							   PERLCALL(1)

     Using GIMME_V    [Toc]    [Back]

     Here is a trivial XSUB which prints the context in	which it is currently

	     I32 gimme = GIMME_V;
	     if	(gimme == G_VOID)
		 printf	("Context is Void\n") ;
	     else if (gimme == G_SCALAR)
		 printf	("Context is Scalar\n")	;
		 printf	("Context is Array\n") ;

     and here is some Perl to test it

	 PrintContext ;
	 $a = PrintContext ;
	 @a = PrintContext ;

     The output	from that will be

	 Context is Void
	 Context is Scalar
	 Context is Array

     Using Perl	to dispose of temporaries

     In	the examples given to date, any	temporaries created in the callback
     (i.e., parameters passed on the stack to the perl_call_* function or
     values returned via the stack) have been freed by one of these methods

     o	  specifying the G_DISCARD flag	with perl_call_*.

     o	  explicitly disposed of using the ENTER/SAVETMPS - FREETMPS/LEAVE

     There is another method which can be used,	namely letting Perl do it for
     you automatically whenever	it regains control after the callback has
     terminated.  This is done by simply not using the


     sequence in the callback (and not,	of course, specifying the G_DISCARD

								       Page 24

PERLCALL(1)							   PERLCALL(1)

     If	you are	going to use this method you have to be	aware of a possible
     memory leak which can arise under very specific circumstances.  To
     explain these circumstances you need to know a bit	about the flow of
     control between Perl and the callback routine.

     The examples given	at the start of	the document (an error handler and an
     event driven program) are typical of the two main sorts of	flow control
     that you are likely to encounter with callbacks.  There is	a very
     important distinction between them, so pay	attention.

     In	the first example, an error handler, the flow of control could be as
     follows.  You have	created	an interface to	an external library.  Control
     can reach the external library like this

	 perl --> XSUB --> external library

     Whilst control is in the library, an error	condition occurs. You have
     previously	set up a Perl callback to handle this situation, so it will
     get executed. Once	the callback has finished, control will	drop back to
     Perl again.  Here is what the flow	of control will	be like	in that

	 perl --> XSUB --> external library
			   error occurs
			   external library -->	perl_call --> perl
	 perl <-- XSUB <-- external library <--	perl_call <----+

     After processing of the error using perl_call_* is	completed, control
     reverts back to Perl more or less immediately.

     In	the diagram, the further right you go the more deeply nested the scope
     is.  It is	only when control is back with perl on the extreme left	of the
     diagram that you will have	dropped	back to	the enclosing scope and	any
     temporaries you have left hanging around will be freed.

     In	the second example, an event driven program, the flow of control will
     be	more like this

								       Page 25

PERLCALL(1)							   PERLCALL(1)

	 perl --> XSUB --> event handler
			   event handler --> perl_call --> perl
			   event handler <-- perl_call <----+
			   event handler --> perl_call --> perl
			   event handler <-- perl_call <----+
			   event handler --> perl_call --> perl
			   event handler <-- perl_call <----+

     In	this case the flow of control can consist of only the repeated

	 event handler --> perl_call --> perl

     for practically the complete duration of the program.  This means that
     control may never drop back to the	surrounding scope in Perl at the
     extreme left.

     So	what is	the big	problem? Well, if you are expecting Perl to tidy up
     those temporaries for you,	you might be in	for a long wait.  For Perl to
     dispose of	your temporaries, control must drop back to the	enclosing
     scope at some stage.  In the event	driven scenario	that may never happen.
     This means	that as	time goes on, your program will	create more and	more
     temporaries, none of which	will ever be freed. As each of these
     temporaries consumes some memory your program will	eventually consume all
     the available memory in your system - kapow!

     So	here is	the bottom line	- if you are sure that control will revert
     back to the enclosing Perl	scope fairly quickly after the end of your
     callback, then it isn't absolutely	necessary to dispose explicitly	of any
     temporaries you may have created. Mind you, if you	are at all uncertain
     about what	to do, it doesn't do any harm to tidy up anyway.

     Strategies	for storing Callback Context Information

     Potentially one of	the trickiest problems to overcome when	designing a
     callback interface	can be figuring	out how	to store the mapping between
     the C callback function and the Perl equivalent.

     To	help understand	why this can be	a real problem first consider how a
     callback is set up	in an all C environment.  Typically a C	API will
     provide a function	to register a callback.	 This will expect a pointer to
     a function	as one of its parameters.  Below is a call to a	hypothetical
     function register_fatal which registers the C function to get called when
     a fatal error occurs.

								       Page 26

PERLCALL(1)							   PERLCALL(1)

	 register_fatal(cb1) ;

     The single	parameter cb1 is a pointer to a	function, so you must have
     defined cb1 in your code, say something like this

	 static	void
	     printf ("Fatal Error\n") ;
	     exit(1) ;

     Now change	that to	call a Perl subroutine instead

	 static	SV * callback =	(SV*)NULL;

	 static	void
	     dSP ;

	     PUSHMARK(sp) ;

	     /*	Call the Perl sub to process the callback */
	     perl_call_sv(callback, G_DISCARD) ;

	     SV	*    fn
	     /*	Remember the Perl sub */
	     if	(callback == (SV*)NULL)
		 callback = newSVsv(fn)	;
		 SvSetSV(callback, fn) ;

	     /*	register the callback with the external	library	*/
	     register_fatal(cb1) ;

     where the Perl equivalent of register_fatal and the callback it
     registers,	pcb1, might look like this

	 # Register the	sub pcb1
	 register_fatal(\&pcb1)	;

	 sub pcb1
	     die "I'm dying...\n" ;

     The mapping between the C callback	and the	Perl equivalent	is stored in

								       Page 27

PERLCALL(1)							   PERLCALL(1)

     the global	variable callback.

     This will be adequate if you ever need to have only one callback
     registered	at any time. An	example	could be an error handler like the
     code sketched out above. Remember though, repeated	calls to
     register_fatal will replace the previously	registered callback function
     with the new one.

     Say for example you want to interface to a	library	which allows
     asynchronous file i/o.  In	this case you may be able to register a
     callback whenever a read operation	has completed. To be of	any use	we
     want to be	able to	call separate Perl subroutines for each	file that is
     opened.  As it stands, the	error handler example above would not be
     adequate as it allows only	a single callback to be	defined	at any time.
     What we require is	a means	of storing the mapping between the opened file
     and the Perl subroutine we	want to	be called for that file.

     Say the i/o library has a function	asynch_read which associates a C
     function ProcessRead with a file handle fh	- this assumes that it has
     also provided some	routine	to open	the file and so	obtain the file

	 asynch_read(fh, ProcessRead)

     This may expect the C ProcessRead function	of this	form

	 ProcessRead(fh, buffer)
	 int fh	;
	 char *	     buffer ;

     To	provide	a Perl interface to this library we need to be able to map
     between the fh parameter and the Perl subroutine we want called.  A hash
     is	a convenient mechanism for storing this	mapping.  The code below shows
     a possible	implementation

	 static	HV * Mapping = (HV*)NULL ;

	 asynch_read(fh, callback)
	     int     fh
	     SV	*    callback
	     /*	If the hash doesn't already exist, create it */
	     if	(Mapping == (HV*)NULL)
		 Mapping = newHV() ;

	     /*	Save the fh -> callback	mapping	*/
	     hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ;

								       Page 28

PERLCALL(1)							   PERLCALL(1)

	     /*	Register with the C Library */
	     asynch_read(fh, asynch_read_if) ;

     and asynch_read_if	could look like	this

	 static	void
	 asynch_read_if(fh, buffer)
	 int fh	;
	 char *	     buffer ;
	     dSP ;
	     SV	** sv ;

	     /*	Get the	callback associated with fh */
	     sv	=  hv_fetch(Mapping, (char*)&fh	, sizeof(fh), FALSE) ;
	     if	(sv == (SV**)NULL)
		 croak("Internal error...\n") ;

	     PUSHMARK(sp) ;
	     XPUSHs(sv_2mortal(newSViv(fh))) ;
	     XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
	     PUTBACK ;

	     /*	Call the Perl sub */
	     perl_call_sv(*sv, G_DISCARD) ;

     For completeness, here is asynch_close.  This shows how to	remove the
     entry from	the hash Mapping.

	     int     fh
	     /*	Remove the entry from the hash */
	     (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ;

	     /*	Now call the real asynch_close */
	     asynch_close(fh) ;

     So	the Perl interface would look like this

	 sub callback1
	     my($handle, $buffer) = @_ ;

	 # Register the	Perl callback
	 asynch_read($fh, \&callback1) ;

	 asynch_close($fh) ;

								       Page 29

PERLCALL(1)							   PERLCALL(1)

     The mapping between the C callback	and Perl is stored in the global hash
     Mapping this time.	Using a	hash has the distinct advantage	that it	allows
     an	unlimited number of callbacks to be registered.

     What if the interface provided by the C callback doesn't contain a
     parameter which allows the	file handle to Perl subroutine mapping?	 Say
     in	the asynchronous i/o package, the callback function gets passed	only
     the buffer	parameter like this

	 char *	     buffer ;

     Without the file handle there is no straightforward way to	map from the C
     callback to the Perl subroutine.

     In	this case a possible way around	this problem is	to predefine a series
     of	C functions to act as the interface to Perl, thus

	 #define MAX_CB		     3
	 #define NULL_HANDLE -1
	 typedef void (*FnMap)() ;

	 struct	MapStruct {
	     FnMap    Function ;
	     SV	*     PerlSub ;
	     int      Handle ;
	   } ;

	 static	void  fn1() ;
	 static	void  fn2() ;
	 static	void  fn3() ;

	 static	struct MapStruct Map [MAX_CB] =
		 { fn1,	NULL, NULL_HANDLE },
		 { fn2,	NULL, NULL_HANDLE },
		 { fn3,	NULL, NULL_HANDLE }
	     } ;

	 static	void
	 Pcb(index, buffer)
	 int index ;
	 char *	buffer ;
	     dSP ;

								       Page 30

PERLCALL(1)							   PERLCALL(1)

	     PUSHMARK(sp) ;
	     XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
	     PUTBACK ;

	     /*	Call the Perl sub */
	     perl_call_sv(Map[index].PerlSub, G_DISCARD) ;

	 static	void
	 char *	buffer ;
	     Pcb(0, buffer) ;

	 static	void
	 char *	buffer ;
	     Pcb(1, buffer) ;

	 static	void
	 char *	buffer ;
	     Pcb(2, buffer) ;

	 array_asynch_read(fh, callback)
	     int	     fh
	     SV	*    callback
	     int index ;
	     int null_index = MAX_CB ;

	     /*	Find the same handle or	an empty entry */
	     for (index	= 0 ; index < MAX_CB ; ++index)
		 if (Map[index].Handle == fh)
		     break ;

		 if (Map[index].Handle == NULL_HANDLE)
		     null_index	= index	;

	     if	(index == MAX_CB && null_index == MAX_CB)
		 croak ("Too many callback functions registered\n") ;

	     if	(index == MAX_CB)
		 index = null_index ;

								       Page 31

PERLCALL(1)							   PERLCALL(1)

	     /*	Save the file handle */
	     Map[index].Handle = fh ;

	     /*	Remember the Perl sub */
	     if	(Map[index].PerlSub == (SV*)NULL)
		 Map[index].PerlSub = newSVsv(callback)	;
		 SvSetSV(Map[index].PerlSub, callback) ;

	     asynch_read(fh, Map[index].Function) ;

	     int     fh
	     int index ;

	     /*	Find the file handle */
	     for (index	= 0; index < MAX_CB ; ++ index)
		 if (Map[index].Handle == fh)
		     break ;

	     if	(index == MAX_CB)
		 croak ("could not close fh %d\n", fh) ;

	     Map[index].Handle = NULL_HANDLE ;
	     SvREFCNT_dec(Map[index].PerlSub) ;
	     Map[index].PerlSub	= (SV*)NULL ;

	     asynch_close(fh) ;

     In	this case the functions	fn1, fn2, and fn3 are used to remember the
     Perl subroutine to	be called. Each	of the functions holds a separate
     hard-wired	index which is used in the function Pcb	to access the Map
     array and actually	call the Perl subroutine.

     There are some obvious disadvantages with this technique.

     Firstly, the code is considerably more complex than with the previous

     Secondly, there is	a hard-wired limit (in this case 3) to the number of
     callbacks that can	exist simultaneously. The only way to increase the
     limit is by modifying the code to add more	functions and then
     recompiling.  None	the less, as long as the number	of functions is	chosen
     with some care, it	is still a workable solution and in some cases is the
     only one available.

     To	summarize, here	are a number of	possible methods for you to consider
     for storing the mapping between C and the Perl callback

								       Page 32

		 Similar pages
Name OS Title
perljp OpenBSD AEuEU,i Perl Y~YxYE `A^a`I`A Perl xIAx3|xOxex|x3x1/2! Perl 5.8.0 xexeicUni- _ codeYuYYi1/4YEx~AcEyxE...
suffix HP-UX file-name suffix conventions
term Linux conventions for naming terminal types
tttk_message_create HP-UX create a message conforming to the CDE conventions
intro Linux Introduction to conventions and miscellany section
term OpenBSD conventions for naming terminal types
tttk_message_destroy HP-UX destroy a message conforming to the CDE conventions
term FreeBSD conventions for naming terminal types
stl_scp Tru64 Subset control program conventions for the setld utility (*.scp)
pthread_self FreeBSD get the calling thread's ID
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service