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_sigelem &PL_vtbl_sigelem
371 # define VTBL_pack &PL_vtbl_pack
372 # define VTBL_packelem &PL_vtbl_packelem
373 # define VTBL_dbline &PL_vtbl_dbline
374 # define VTBL_isa &PL_vtbl_isa
375 # define VTBL_isaelem &PL_vtbl_isaelem
376 # define VTBL_arylen &PL_vtbl_arylen
377 # define VTBL_glob &PL_vtbl_glob
378 # define VTBL_mglob &PL_vtbl_mglob
379 # define VTBL_nkeys &PL_vtbl_nkeys
380 # define VTBL_taint &PL_vtbl_taint
381 # define VTBL_substr &PL_vtbl_substr
382 # define VTBL_vec &PL_vtbl_vec
383 # define VTBL_pos &PL_vtbl_pos
384 # define VTBL_bm &PL_vtbl_bm
385 # define VTBL_fm &PL_vtbl_fm
386 # define VTBL_uvar &PL_vtbl_uvar
387 # define VTBL_defelem &PL_vtbl_defelem
388 # define VTBL_regexp &PL_vtbl_regexp
389 # define VTBL_regdata &PL_vtbl_regdata
390 # define VTBL_regdatum &PL_vtbl_regdatum
391 # ifdef USE_LOCALE_COLLATE
392 # define VTBL_collxfrm &PL_vtbl_collxfrm
394 # define VTBL_amagic &PL_vtbl_amagic
395 # define VTBL_amagicelem &PL_vtbl_amagicelem
400 #if defined(PERL_IMPLICIT_CONTEXT) && !defined(PERL_NO_GET_CONTEXT) && !defined(PERL_CORE)
403 # define aTHX PERL_GET_THX
407 #if defined(PERL_IMPLICIT_SYS) && !defined(PERL_CORE)
409 # if defined (NETWARE) && defined (USE_STDIO)
410 # define times PerlProc_times
411 # define setuid PerlProc_setuid
412 # define setgid PerlProc_setgid
413 # define getpid PerlProc_getpid
414 # define pause PerlProc_pause
415 # define exit PerlProc_exit
416 # define _exit PerlProc__exit
433 /* Following symbols were giving redefinition errors while building extensions - sgp 17th Oct 2000 */
443 # undef gethostbyaddr
444 # undef gethostbyname
449 # undef getprotobyname
450 # undef getprotobynumber
452 # undef getservbyname
453 # undef getservbyport
462 /* to avoid warnings: "xyz" redefined */
470 # define mkdir PerlDir_mkdir
471 # define chdir PerlDir_chdir
472 # define rmdir PerlDir_rmdir
473 # define closedir PerlDir_close
474 # define opendir PerlDir_open
475 # define readdir PerlDir_read
476 # define rewinddir PerlDir_rewind
477 # define seekdir PerlDir_seek
478 # define telldir PerlDir_tell
479 # define putenv PerlEnv_putenv
480 # define getenv PerlEnv_getenv
481 # define uname PerlEnv_uname
482 # define stdin PerlSIO_stdin
483 # define stdout PerlSIO_stdout
484 # define stderr PerlSIO_stderr
485 # define fopen PerlSIO_fopen
486 # define fclose PerlSIO_fclose
487 # define feof PerlSIO_feof
488 # define ferror PerlSIO_ferror
489 # define clearerr PerlSIO_clearerr
490 # define getc PerlSIO_getc
491 # define fgets PerlSIO_fgets
492 # define fputc PerlSIO_fputc
493 # define fputs PerlSIO_fputs
494 # define fflush PerlSIO_fflush
495 # define ungetc PerlSIO_ungetc
496 # define fileno PerlSIO_fileno
497 # define fdopen PerlSIO_fdopen
498 # define freopen PerlSIO_freopen
499 # define fread PerlSIO_fread
500 # define fwrite PerlSIO_fwrite
501 # define setbuf PerlSIO_setbuf
502 # define setvbuf PerlSIO_setvbuf
503 # define setlinebuf PerlSIO_setlinebuf
504 # define stdoutf PerlSIO_stdoutf
505 # define vfprintf PerlSIO_vprintf
506 # define ftell PerlSIO_ftell
507 # define fseek PerlSIO_fseek
508 # define fgetpos PerlSIO_fgetpos
509 # define fsetpos PerlSIO_fsetpos
510 # define frewind PerlSIO_rewind
511 # define tmpfile PerlSIO_tmpfile
512 # define access PerlLIO_access
513 # define chmod PerlLIO_chmod
514 # define chsize PerlLIO_chsize
515 # define close PerlLIO_close
516 # define dup PerlLIO_dup
517 # define dup2 PerlLIO_dup2
518 # define flock PerlLIO_flock
519 # define fstat PerlLIO_fstat
520 # define ioctl PerlLIO_ioctl
521 # define isatty PerlLIO_isatty
522 # define link PerlLIO_link
523 # define lseek PerlLIO_lseek
524 # define lstat PerlLIO_lstat
525 # define mktemp PerlLIO_mktemp
526 # define open PerlLIO_open
527 # define read PerlLIO_read
528 # define rename PerlLIO_rename
529 # define setmode PerlLIO_setmode
530 # define stat(buf,sb) PerlLIO_stat(buf,sb)
531 # define tmpnam PerlLIO_tmpnam
532 # define umask PerlLIO_umask
533 # define unlink PerlLIO_unlink
534 # define utime PerlLIO_utime
535 # define write PerlLIO_write
536 # define malloc PerlMem_malloc
537 # define realloc PerlMem_realloc
538 # define free PerlMem_free
539 # define abort PerlProc_abort
540 # define exit PerlProc_exit
541 # define _exit PerlProc__exit
542 # define execl PerlProc_execl
543 # define execv PerlProc_execv
544 # define execvp PerlProc_execvp
545 # define getuid PerlProc_getuid
546 # define geteuid PerlProc_geteuid
547 # define getgid PerlProc_getgid
548 # define getegid PerlProc_getegid
549 # define getlogin PerlProc_getlogin
550 # define kill PerlProc_kill
551 # define killpg PerlProc_killpg
552 # define pause PerlProc_pause
553 # define popen PerlProc_popen
554 # define pclose PerlProc_pclose
555 # define pipe PerlProc_pipe
556 # define setuid PerlProc_setuid
557 # define setgid PerlProc_setgid
558 # define sleep PerlProc_sleep
559 # define times PerlProc_times
560 # define wait PerlProc_wait
561 # define setjmp PerlProc_setjmp
562 # define longjmp PerlProc_longjmp
563 # define signal PerlProc_signal
564 # define getpid PerlProc_getpid
565 # define gettimeofday PerlProc_gettimeofday
566 # define htonl PerlSock_htonl
567 # define htons PerlSock_htons
568 # define ntohl PerlSock_ntohl
569 # define ntohs PerlSock_ntohs
570 # define accept PerlSock_accept
571 # define bind PerlSock_bind
572 # define connect PerlSock_connect
573 # define endhostent PerlSock_endhostent
574 # define endnetent PerlSock_endnetent
575 # define endprotoent PerlSock_endprotoent
576 # define endservent PerlSock_endservent
577 # define gethostbyaddr PerlSock_gethostbyaddr
578 # define gethostbyname PerlSock_gethostbyname
579 # define gethostent PerlSock_gethostent
580 # define gethostname PerlSock_gethostname
581 # define getnetbyaddr PerlSock_getnetbyaddr
582 # define getnetbyname PerlSock_getnetbyname
583 # define getnetent PerlSock_getnetent
584 # define getpeername PerlSock_getpeername
585 # define getprotobyname PerlSock_getprotobyname
586 # define getprotobynumber PerlSock_getprotobynumber
587 # define getprotoent PerlSock_getprotoent
588 # define getservbyname PerlSock_getservbyname
589 # define getservbyport PerlSock_getservbyport
590 # define getservent PerlSock_getservent
591 # define getsockname PerlSock_getsockname
592 # define getsockopt PerlSock_getsockopt
593 # define inet_addr PerlSock_inet_addr
594 # define inet_ntoa PerlSock_inet_ntoa
595 # define listen PerlSock_listen
596 # define recv PerlSock_recv
597 # define recvfrom PerlSock_recvfrom
598 # define select PerlSock_select
599 # define send PerlSock_send
600 # define sendto PerlSock_sendto
601 # define sethostent PerlSock_sethostent
602 # define setnetent PerlSock_setnetent
603 # define setprotoent PerlSock_setprotoent
604 # define setservent PerlSock_setservent
605 # define setsockopt PerlSock_setsockopt
606 # define shutdown PerlSock_shutdown
607 # define socket PerlSock_socket
608 # define socketpair PerlSock_socketpair
609 # endif /* NETWARE && USE_STDIO */
611 # ifdef USE_SOCKETS_AS_HANDLES
617 # define fd_set Perl_fd_set
618 # define FD_SET(n,p) PERL_FD_SET(n,p)
619 # define FD_CLR(n,p) PERL_FD_CLR(n,p)
620 # define FD_ISSET(n,p) PERL_FD_ISSET(n,p)
621 # define FD_ZERO(p) PERL_FD_ZERO(p)
622 # endif /* USE_SOCKETS_AS_HANDLES */
624 # endif /* NO_XSLOCKS */
625 #endif /* PERL_IMPLICIT_SYS && !PERL_CORE */
627 #endif /* _INC_PERL_XSUB_H */ /* include guard */
631 * c-indentation-style: bsd
633 * indent-tabs-mode: t
636 * ex: set ts=8 sts=4 sw=4 noet: