3 * Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
4 * 2003, 2004, 2005, 2006, 2007, 2008 by Larry Wall and others
6 * You may distribute under the terms of either the GNU General Public
7 * License or the Artistic License, as specified in the README file.
11 #ifndef _INC_PERL_XSUB_H
12 #define _INC_PERL_XSUB_H 1
14 /* first, some documentation for xsubpp-generated items */
17 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
19 =for apidoc Amn|char*|CLASS
20 Variable which is setup by C<xsubpp> to indicate the
21 class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
23 =for apidoc Amn|(whatever)|RETVAL
24 Variable which is setup by C<xsubpp> to hold the return value for an
25 XSUB. This is always the proper type for the XSUB. See
26 L<perlxs/"The RETVAL Variable">.
28 =for apidoc Amn|(whatever)|THIS
29 Variable which is setup by C<xsubpp> to designate the object in a C++
30 XSUB. This is always the proper type for the C++ object. See C<CLASS> and
31 L<perlxs/"Using XS With C++">.
33 =for apidoc Amn|I32|ax
34 Variable which is setup by C<xsubpp> to indicate the stack base offset,
35 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
36 must be called prior to setup the C<MARK> variable.
38 =for apidoc Amn|I32|items
39 Variable which is setup by C<xsubpp> to indicate the number of
40 items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
42 =for apidoc Amn|I32|ix
43 Variable which is setup by C<xsubpp> to indicate which of an
44 XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
46 =for apidoc Am|SV*|ST|int ix
47 Used to access elements on the XSUB's stack.
50 Macro to declare an XSUB and its C parameter list. This is handled by
54 Sets up the C<ax> variable.
55 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
57 =for apidoc Ams||dAXMARK
58 Sets up the C<ax> variable and stack marker variable C<mark>.
59 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
61 =for apidoc Ams||dITEMS
62 Sets up the C<items> variable.
63 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
65 =for apidoc Ams||dXSARGS
66 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
67 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
68 This is usually handled automatically by C<xsubpp>.
70 =for apidoc Ams||dXSI32
71 Sets up the C<ix> variable for an XSUB which has aliases. This is usually
72 handled automatically by C<xsubpp>.
74 =for apidoc Ams||dUNDERBAR
75 Sets up any variable needed by the C<UNDERBAR> macro. It used to define
76 C<padoff_du>, but it is currently a noop. However, it is strongly advised
77 to still use it for ensuring past and future compatibility.
79 =for apidoc AmU||UNDERBAR
80 The SV* corresponding to the $_ variable. Works even if there
81 is a lexical $_ in scope.
86 #ifndef PERL_UNUSED_ARG
87 # if defined(lint) && defined(S_SPLINT_S) /* www.splint.org */
89 # define PERL_UNUSED_ARG(x) NOTE(ARGUNUSED(x))
91 # define PERL_UNUSED_ARG(x) ((void)x)
94 #ifndef PERL_UNUSED_VAR
95 # define PERL_UNUSED_VAR(x) ((void)x)
98 #define ST(off) PL_stack_base[ax + (off)]
100 /* XSPROTO() is also used by SWIG like this:
102 * typedef XSPROTO(SwigPerlWrapper);
103 * typedef SwigPerlWrapper *SwigPerlWrapperPtr;
105 * This code needs to be compilable under both C and C++.
107 * Don't forget to change the __attribute__unused__ version of XS()
108 * below too if you change XSPROTO() here.
110 #define XSPROTO(name) void name(pTHX_ CV* cv)
113 #if defined(__CYGWIN__) && defined(USE_DYNAMIC_LOADING)
114 # define XS(name) __declspec(dllexport) XSPROTO(name)
116 #if defined(__SYMBIAN32__)
117 # define XS(name) EXPORT_C XSPROTO(name)
120 # if defined(HASATTRIBUTE_UNUSED) && !defined(__cplusplus)
121 # define XS(name) void name(pTHX_ CV* cv __attribute__unused__)
124 # define XS(name) extern "C" XSPROTO(name)
126 # define XS(name) XSPROTO(name)
131 #define dAX const I32 ax = (I32)(MARK - PL_stack_base + 1)
135 register SV **mark = PL_stack_base + ax++
137 #define dITEMS I32 items = (I32)(SP - MARK)
139 #if defined(lint) && defined(S_SPLINT_S) /* www.splint.org */
141 NOTE(ARGUNUSED(cv)) \
148 #define dXSTARG SV * const targ = ((PL_op->op_private & OPpENTERSUB_HASTARG) \
149 ? PAD_SV(PL_op->op_targ) : sv_newmortal())
151 /* Should be used before final PUSHi etc. if not in PPCODE section. */
152 #define XSprePUSH (sp = PL_stack_base + ax - 1)
154 #define XSANY CvXSUBANY(cv)
156 #define dXSI32 I32 ix = XSANY.any_i32
159 # define XSINTERFACE_CVT(ret,name) ret (*name)(...)
160 # define XSINTERFACE_CVT_ANON(ret) ret (*)(...)
162 # define XSINTERFACE_CVT(ret,name) ret (*name)()
163 # define XSINTERFACE_CVT_ANON(ret) ret (*)()
165 #define dXSFUNCTION(ret) XSINTERFACE_CVT(ret,XSFUNCTION)
166 #define XSINTERFACE_FUNC(ret,cv,f) ((XSINTERFACE_CVT_ANON(ret))(f))
167 #define XSINTERFACE_FUNC_SET(cv,f) \
168 CvXSUBANY(cv).any_dxptr = (void (*) (pTHX_ void*))(f)
170 #define dUNDERBAR dNOOP
171 #define UNDERBAR find_rundefsv()
173 /* Simple macros to put new mortal values onto the stack. */
174 /* Typically used to return values from XS functions. */
177 =head1 Stack Manipulation Macros
179 =for apidoc Am|void|XST_mIV|int pos|IV iv
180 Place an integer into the specified position C<pos> on the stack. The
181 value is stored in a new mortal SV.
183 =for apidoc Am|void|XST_mNV|int pos|NV nv
184 Place a double into the specified position C<pos> on the stack. The value
185 is stored in a new mortal SV.
187 =for apidoc Am|void|XST_mPV|int pos|char* str
188 Place a copy of a string into the specified position C<pos> on the stack.
189 The value is stored in a new mortal SV.
191 =for apidoc Am|void|XST_mNO|int pos
192 Place C<&PL_sv_no> into the specified position C<pos> on the
195 =for apidoc Am|void|XST_mYES|int pos
196 Place C<&PL_sv_yes> into the specified position C<pos> on the
199 =for apidoc Am|void|XST_mUNDEF|int pos
200 Place C<&PL_sv_undef> into the specified position C<pos> on the
203 =for apidoc Am|void|XSRETURN|int nitems
204 Return from XSUB, indicating number of items on the stack. This is usually
205 handled by C<xsubpp>.
207 =for apidoc Am|void|XSRETURN_IV|IV iv
208 Return an integer from an XSUB immediately. Uses C<XST_mIV>.
210 =for apidoc Am|void|XSRETURN_UV|IV uv
211 Return an integer from an XSUB immediately. Uses C<XST_mUV>.
213 =for apidoc Am|void|XSRETURN_NV|NV nv
214 Return a double from an XSUB immediately. Uses C<XST_mNV>.
216 =for apidoc Am|void|XSRETURN_PV|char* str
217 Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
219 =for apidoc Ams||XSRETURN_NO
220 Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
222 =for apidoc Ams||XSRETURN_YES
223 Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
225 =for apidoc Ams||XSRETURN_UNDEF
226 Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
228 =for apidoc Ams||XSRETURN_EMPTY
229 Return an empty list from an XSUB immediately.
231 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
233 =for apidoc AmU||newXSproto|char* name|XSUBADDR_t f|char* filename|const char *proto
234 Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
237 =for apidoc AmU||XS_VERSION
238 The version identifier for an XS module. This is usually
239 handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
241 =for apidoc Ams||XS_VERSION_BOOTCHECK
242 Macro to verify that a PM module's $VERSION variable matches the XS
243 module's C<XS_VERSION> variable. This is usually handled automatically by
244 C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
246 =for apidoc Ams||XS_APIVERSION_BOOTCHECK
247 Macro to verify that the perl api version an XS module has been compiled against
248 matches the api version of the perl interpreter it's being loaded into.
250 =head1 Simple Exception Handling Macros
252 =for apidoc Ams||dXCPT
253 Set up necessary local variables for exception handling.
254 See L<perlguts/"Exception Handling">.
256 =for apidoc AmU||XCPT_TRY_START
257 Starts a try block. See L<perlguts/"Exception Handling">.
259 =for apidoc AmU||XCPT_TRY_END
260 Ends a try block. See L<perlguts/"Exception Handling">.
262 =for apidoc AmU||XCPT_CATCH
263 Introduces a catch block. See L<perlguts/"Exception Handling">.
265 =for apidoc Ams||XCPT_RETHROW
266 Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
271 #define XST_mIV(i,v) (ST(i) = sv_2mortal(newSViv(v)) )
272 #define XST_mUV(i,v) (ST(i) = sv_2mortal(newSVuv(v)) )
273 #define XST_mNV(i,v) (ST(i) = sv_2mortal(newSVnv(v)) )
274 #define XST_mPV(i,v) (ST(i) = sv_2mortal(newSVpv(v,0)))
275 #define XST_mPVN(i,v,n) (ST(i) = newSVpvn_flags(v,n, SVs_TEMP))
276 #define XST_mNO(i) (ST(i) = &PL_sv_no )
277 #define XST_mYES(i) (ST(i) = &PL_sv_yes )
278 #define XST_mUNDEF(i) (ST(i) = &PL_sv_undef)
280 #define XSRETURN(off) \
282 const IV tmpXSoff = (off); \
283 PL_stack_sp = PL_stack_base + ax + (tmpXSoff - 1); \
287 #define XSRETURN_IV(v) STMT_START { XST_mIV(0,v); XSRETURN(1); } STMT_END
288 #define XSRETURN_UV(v) STMT_START { XST_mUV(0,v); XSRETURN(1); } STMT_END
289 #define XSRETURN_NV(v) STMT_START { XST_mNV(0,v); XSRETURN(1); } STMT_END
290 #define XSRETURN_PV(v) STMT_START { XST_mPV(0,v); XSRETURN(1); } STMT_END
291 #define XSRETURN_PVN(v,n) STMT_START { XST_mPVN(0,v,n); XSRETURN(1); } STMT_END
292 #define XSRETURN_NO STMT_START { XST_mNO(0); XSRETURN(1); } STMT_END
293 #define XSRETURN_YES STMT_START { XST_mYES(0); XSRETURN(1); } STMT_END
294 #define XSRETURN_UNDEF STMT_START { XST_mUNDEF(0); XSRETURN(1); } STMT_END
295 #define XSRETURN_EMPTY STMT_START { XSRETURN(0); } STMT_END
297 #define newXSproto(a,b,c,d) newXS_flags(a,b,c,d,0)
300 # define XS_VERSION_BOOTCHECK \
301 Perl_xs_version_bootcheck(aTHX_ items, ax, STR_WITH_LEN(XS_VERSION))
303 # define XS_VERSION_BOOTCHECK
306 #define XS_APIVERSION_BOOTCHECK \
307 Perl_xs_apiversion_bootcheck(aTHX_ ST(0), STR_WITH_LEN("v" PERL_API_VERSION_STRING))
310 # define dXCPT dJMPENV; int rEtV = 0
311 # define XCPT_TRY_START JMPENV_PUSH(rEtV); if (rEtV == 0)
312 # define XCPT_TRY_END JMPENV_POP;
313 # define XCPT_CATCH if (rEtV != 0)
314 # define XCPT_RETHROW JMPENV_JUMP(rEtV)
318 The DBM_setFilter & DBM_ckFilter macros are only used by
319 the *DB*_File modules
322 #define DBM_setFilter(db_type,code) \
325 RETVAL = sv_mortalcopy(db_type) ; \
327 if (db_type && (code == &PL_sv_undef)) { \
328 SvREFCNT_dec(db_type) ; \
333 sv_setsv(db_type, code) ; \
335 db_type = newSVsv(code) ; \
339 #define DBM_ckFilter(arg,type,name) \
342 if (db->filtering) { \
343 croak("recursion detected in %s", name) ; \
347 SAVEINT(db->filtering) ; \
348 db->filtering = TRUE ; \
350 if (name[7] == 's') \
351 arg = newSVsv(arg); \
356 (void) perl_call_sv(db->type, G_DISCARD); \
361 if (name[7] == 's'){ \
362 arg = sv_2mortal(arg); \
366 #if 1 /* for compatibility */
367 # define VTBL_sv &PL_vtbl_sv
368 # define VTBL_env &PL_vtbl_env
369 # define VTBL_envelem &PL_vtbl_envelem
370 # define VTBL_sig &PL_vtbl_sig
371 # define VTBL_sigelem &PL_vtbl_sigelem
372 # define VTBL_pack &PL_vtbl_pack
373 # define VTBL_packelem &PL_vtbl_packelem
374 # define VTBL_dbline &PL_vtbl_dbline
375 # define VTBL_isa &PL_vtbl_isa
376 # define VTBL_isaelem &PL_vtbl_isaelem
377 # define VTBL_arylen &PL_vtbl_arylen
378 # define VTBL_glob &PL_vtbl_glob
379 # define VTBL_mglob &PL_vtbl_mglob
380 # define VTBL_nkeys &PL_vtbl_nkeys
381 # define VTBL_taint &PL_vtbl_taint
382 # define VTBL_substr &PL_vtbl_substr
383 # define VTBL_vec &PL_vtbl_vec
384 # define VTBL_pos &PL_vtbl_pos
385 # define VTBL_bm &PL_vtbl_bm
386 # define VTBL_fm &PL_vtbl_fm
387 # define VTBL_uvar &PL_vtbl_uvar
388 # define VTBL_defelem &PL_vtbl_defelem
389 # define VTBL_regexp &PL_vtbl_regexp
390 # define VTBL_regdata &PL_vtbl_regdata
391 # define VTBL_regdatum &PL_vtbl_regdatum
392 # ifdef USE_LOCALE_COLLATE
393 # define VTBL_collxfrm &PL_vtbl_collxfrm
395 # define VTBL_amagic &PL_vtbl_amagic
396 # define VTBL_amagicelem &PL_vtbl_amagicelem
401 #if defined(PERL_IMPLICIT_CONTEXT) && !defined(PERL_NO_GET_CONTEXT) && !defined(PERL_CORE)
404 # define aTHX PERL_GET_THX
408 #if defined(PERL_IMPLICIT_SYS) && !defined(PERL_CORE)
410 # if defined (NETWARE) && defined (USE_STDIO)
411 # define times PerlProc_times
412 # define setuid PerlProc_setuid
413 # define setgid PerlProc_setgid
414 # define getpid PerlProc_getpid
415 # define pause PerlProc_pause
416 # define exit PerlProc_exit
417 # define _exit PerlProc__exit
434 /* Following symbols were giving redefinition errors while building extensions - sgp 17th Oct 2000 */
444 # undef gethostbyaddr
445 # undef gethostbyname
450 # undef getprotobyname
451 # undef getprotobynumber
453 # undef getservbyname
454 # undef getservbyport
463 /* to avoid warnings: "xyz" redefined */
471 # define mkdir PerlDir_mkdir
472 # define chdir PerlDir_chdir
473 # define rmdir PerlDir_rmdir
474 # define closedir PerlDir_close
475 # define opendir PerlDir_open
476 # define readdir PerlDir_read
477 # define rewinddir PerlDir_rewind
478 # define seekdir PerlDir_seek
479 # define telldir PerlDir_tell
480 # define putenv PerlEnv_putenv
481 # define getenv PerlEnv_getenv
482 # define uname PerlEnv_uname
483 # define stdin PerlSIO_stdin
484 # define stdout PerlSIO_stdout
485 # define stderr PerlSIO_stderr
486 # define fopen PerlSIO_fopen
487 # define fclose PerlSIO_fclose
488 # define feof PerlSIO_feof
489 # define ferror PerlSIO_ferror
490 # define clearerr PerlSIO_clearerr
491 # define getc PerlSIO_getc
492 # define fgets PerlSIO_fgets
493 # define fputc PerlSIO_fputc
494 # define fputs PerlSIO_fputs
495 # define fflush PerlSIO_fflush
496 # define ungetc PerlSIO_ungetc
497 # define fileno PerlSIO_fileno
498 # define fdopen PerlSIO_fdopen
499 # define freopen PerlSIO_freopen
500 # define fread PerlSIO_fread
501 # define fwrite PerlSIO_fwrite
502 # define setbuf PerlSIO_setbuf
503 # define setvbuf PerlSIO_setvbuf
504 # define setlinebuf PerlSIO_setlinebuf
505 # define stdoutf PerlSIO_stdoutf
506 # define vfprintf PerlSIO_vprintf
507 # define ftell PerlSIO_ftell
508 # define fseek PerlSIO_fseek
509 # define fgetpos PerlSIO_fgetpos
510 # define fsetpos PerlSIO_fsetpos
511 # define frewind PerlSIO_rewind
512 # define tmpfile PerlSIO_tmpfile
513 # define access PerlLIO_access
514 # define chmod PerlLIO_chmod
515 # define chsize PerlLIO_chsize
516 # define close PerlLIO_close
517 # define dup PerlLIO_dup
518 # define dup2 PerlLIO_dup2
519 # define flock PerlLIO_flock
520 # define fstat PerlLIO_fstat
521 # define ioctl PerlLIO_ioctl
522 # define isatty PerlLIO_isatty
523 # define link PerlLIO_link
524 # define lseek PerlLIO_lseek
525 # define lstat PerlLIO_lstat
526 # define mktemp PerlLIO_mktemp
527 # define open PerlLIO_open
528 # define read PerlLIO_read
529 # define rename PerlLIO_rename
530 # define setmode PerlLIO_setmode
531 # define stat(buf,sb) PerlLIO_stat(buf,sb)
532 # define tmpnam PerlLIO_tmpnam
533 # define umask PerlLIO_umask
534 # define unlink PerlLIO_unlink
535 # define utime PerlLIO_utime
536 # define write PerlLIO_write
537 # define malloc PerlMem_malloc
538 # define realloc PerlMem_realloc
539 # define free PerlMem_free
540 # define abort PerlProc_abort
541 # define exit PerlProc_exit
542 # define _exit PerlProc__exit
543 # define execl PerlProc_execl
544 # define execv PerlProc_execv
545 # define execvp PerlProc_execvp
546 # define getuid PerlProc_getuid
547 # define geteuid PerlProc_geteuid
548 # define getgid PerlProc_getgid
549 # define getegid PerlProc_getegid
550 # define getlogin PerlProc_getlogin
551 # define kill PerlProc_kill
552 # define killpg PerlProc_killpg
553 # define pause PerlProc_pause
554 # define popen PerlProc_popen
555 # define pclose PerlProc_pclose
556 # define pipe PerlProc_pipe
557 # define setuid PerlProc_setuid
558 # define setgid PerlProc_setgid
559 # define sleep PerlProc_sleep
560 # define times PerlProc_times
561 # define wait PerlProc_wait
562 # define setjmp PerlProc_setjmp
563 # define longjmp PerlProc_longjmp
564 # define signal PerlProc_signal
565 # define getpid PerlProc_getpid
566 # define gettimeofday PerlProc_gettimeofday
567 # define htonl PerlSock_htonl
568 # define htons PerlSock_htons
569 # define ntohl PerlSock_ntohl
570 # define ntohs PerlSock_ntohs
571 # define accept PerlSock_accept
572 # define bind PerlSock_bind
573 # define connect PerlSock_connect
574 # define endhostent PerlSock_endhostent
575 # define endnetent PerlSock_endnetent
576 # define endprotoent PerlSock_endprotoent
577 # define endservent PerlSock_endservent
578 # define gethostbyaddr PerlSock_gethostbyaddr
579 # define gethostbyname PerlSock_gethostbyname
580 # define gethostent PerlSock_gethostent
581 # define gethostname PerlSock_gethostname
582 # define getnetbyaddr PerlSock_getnetbyaddr
583 # define getnetbyname PerlSock_getnetbyname
584 # define getnetent PerlSock_getnetent
585 # define getpeername PerlSock_getpeername
586 # define getprotobyname PerlSock_getprotobyname
587 # define getprotobynumber PerlSock_getprotobynumber
588 # define getprotoent PerlSock_getprotoent
589 # define getservbyname PerlSock_getservbyname
590 # define getservbyport PerlSock_getservbyport
591 # define getservent PerlSock_getservent
592 # define getsockname PerlSock_getsockname
593 # define getsockopt PerlSock_getsockopt
594 # define inet_addr PerlSock_inet_addr
595 # define inet_ntoa PerlSock_inet_ntoa
596 # define listen PerlSock_listen
597 # define recv PerlSock_recv
598 # define recvfrom PerlSock_recvfrom
599 # define select PerlSock_select
600 # define send PerlSock_send
601 # define sendto PerlSock_sendto
602 # define sethostent PerlSock_sethostent
603 # define setnetent PerlSock_setnetent
604 # define setprotoent PerlSock_setprotoent
605 # define setservent PerlSock_setservent
606 # define setsockopt PerlSock_setsockopt
607 # define shutdown PerlSock_shutdown
608 # define socket PerlSock_socket
609 # define socketpair PerlSock_socketpair
610 # endif /* NETWARE && USE_STDIO */
612 # ifdef USE_SOCKETS_AS_HANDLES
618 # define fd_set Perl_fd_set
619 # define FD_SET(n,p) PERL_FD_SET(n,p)
620 # define FD_CLR(n,p) PERL_FD_CLR(n,p)
621 # define FD_ISSET(n,p) PERL_FD_ISSET(n,p)
622 # define FD_ZERO(p) PERL_FD_ZERO(p)
623 # endif /* USE_SOCKETS_AS_HANDLES */
625 # endif /* NO_XSLOCKS */
626 #endif /* PERL_IMPLICIT_SYS && !PERL_CORE */
628 #endif /* _INC_PERL_XSUB_H */ /* include guard */
632 * c-indentation-style: bsd
634 * indent-tabs-mode: t
637 * ex: set ts=8 sts=4 sw=4 noet: