This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Superparanoia.
[perl5.git] / XSUB.h
CommitLineData
eb1102fc
NIS
1/* XSUB.h
2 *
4bb101f2
JH
3 * Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999,
4 * 2000, 2001, 2002, 2003, by Larry Wall and others
eb1102fc
NIS
5 *
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.
8 *
9 */
10
b4ba0ab9
GS
11#ifndef _INC_PERL_XSUB_H
12#define _INC_PERL_XSUB_H 1
13
954c1994
GS
14/* first, some documentation for xsubpp-generated items */
15
16/*
ccfc67b7
JH
17=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
18
954c1994
GS
19=for apidoc Amn|char*|CLASS
20Variable which is setup by C<xsubpp> to indicate the
21class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
22
23=for apidoc Amn|(whatever)|RETVAL
24Variable which is setup by C<xsubpp> to hold the return value for an
25XSUB. This is always the proper type for the XSUB. See
26L<perlxs/"The RETVAL Variable">.
27
28=for apidoc Amn|(whatever)|THIS
29Variable which is setup by C<xsubpp> to designate the object in a C++
30XSUB. This is always the proper type for the C++ object. See C<CLASS> and
31L<perlxs/"Using XS With C++">.
32
9f2ea798
DM
33=for apidoc Amn|I32|ax
34Variable which is setup by C<xsubpp> to indicate the stack base offset,
35used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
36must be called prior to setup the C<MARK> variable.
37
954c1994
GS
38=for apidoc Amn|I32|items
39Variable which is setup by C<xsubpp> to indicate the number of
40items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
41
42=for apidoc Amn|I32|ix
43Variable which is setup by C<xsubpp> to indicate which of an
44XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
45
46=for apidoc Am|SV*|ST|int ix
47Used to access elements on the XSUB's stack.
48
49=for apidoc AmU||XS
50Macro to declare an XSUB and its C parameter list. This is handled by
51C<xsubpp>.
52
9f2ea798
DM
53=for apidoc Ams||dAX
54Sets up the C<ax> variable.
55This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
56
57=for apidoc Ams||dITEMS
58Sets up the C<items> variable.
59This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
60
954c1994 61=for apidoc Ams||dXSARGS
9f2ea798
DM
62Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
63Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
64This is usually handled automatically by C<xsubpp>.
954c1994
GS
65
66=for apidoc Ams||dXSI32
67Sets up the C<ix> variable for an XSUB which has aliases. This is usually
68handled automatically by C<xsubpp>.
69
70=cut
71*/
72
3280af22 73#define ST(off) PL_stack_base[ax + (off)]
a0d0e21e 74
d308986b 75#if defined(__CYGWIN__) && defined(USE_DYNAMIC_LOADING)
acfe0abc 76# define XS(name) __declspec(dllexport) void name(pTHX_ CV* cv)
cea2e8a9 77#else
acfe0abc 78# define XS(name) void name(pTHX_ CV* cv)
a0d0e21e
LW
79#endif
80
349b520e 81#define dAX I32 ax = MARK - PL_stack_base + 1
9f2ea798
DM
82
83#define dITEMS I32 items = SP - MARK
84
a0d0e21e 85#define dXSARGS \
3c78fafa 86 dSP; dMARK; \
9f2ea798 87 dAX; dITEMS
a0d0e21e 88
8a7fc0dc
GS
89#define dXSTARG SV * targ = ((PL_op->op_private & OPpENTERSUB_HASTARG) \
90 ? PAD_SV(PL_op->op_targ) : sv_newmortal())
91
b26a54d0
GS
92/* Should be used before final PUSHi etc. if not in PPCODE section. */
93#define XSprePUSH (sp = PL_stack_base + ax - 1)
94
a0d0e21e
LW
95#define XSANY CvXSUBANY(cv)
96
97#define dXSI32 I32 ix = XSANY.any_i32
98
cfc02341
IZ
99#ifdef __cplusplus
100# define XSINTERFACE_CVT(ret,name) ret (*name)(...)
101#else
102# define XSINTERFACE_CVT(ret,name) ret (*name)()
103#endif
104#define dXSFUNCTION(ret) XSINTERFACE_CVT(ret,XSFUNCTION)
2554589c 105#define XSINTERFACE_FUNC(ret,cv,f) ((XSINTERFACE_CVT(ret,))(f))
cfc02341 106#define XSINTERFACE_FUNC_SET(cv,f) \
a12c3db7 107 CvXSUBANY(cv).any_dxptr = (void (*) (pTHX_ void*))(f)
cfc02341 108
748a9306
LW
109/* Simple macros to put new mortal values onto the stack. */
110/* Typically used to return values from XS functions. */
954c1994
GS
111
112/*
ccfc67b7
JH
113=head1 Stack Manipulation Macros
114
954c1994
GS
115=for apidoc Am|void|XST_mIV|int pos|IV iv
116Place an integer into the specified position C<pos> on the stack. The
117value is stored in a new mortal SV.
118
119=for apidoc Am|void|XST_mNV|int pos|NV nv
120Place a double into the specified position C<pos> on the stack. The value
121is stored in a new mortal SV.
122
123=for apidoc Am|void|XST_mPV|int pos|char* str
124Place a copy of a string into the specified position C<pos> on the stack.
125The value is stored in a new mortal SV.
126
127=for apidoc Am|void|XST_mNO|int pos
128Place C<&PL_sv_no> into the specified position C<pos> on the
129stack.
130
131=for apidoc Am|void|XST_mYES|int pos
132Place C<&PL_sv_yes> into the specified position C<pos> on the
133stack.
134
135=for apidoc Am|void|XST_mUNDEF|int pos
136Place C<&PL_sv_undef> into the specified position C<pos> on the
137stack.
138
139=for apidoc Am|void|XSRETURN|int nitems
140Return from XSUB, indicating number of items on the stack. This is usually
141handled by C<xsubpp>.
142
143=for apidoc Am|void|XSRETURN_IV|IV iv
144Return an integer from an XSUB immediately. Uses C<XST_mIV>.
145
146=for apidoc Am|void|XSRETURN_NV|NV nv
d1be9408 147Return a double from an XSUB immediately. Uses C<XST_mNV>.
954c1994
GS
148
149=for apidoc Am|void|XSRETURN_PV|char* str
150Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
151
152=for apidoc Ams||XSRETURN_NO
153Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
154
155=for apidoc Ams||XSRETURN_YES
156Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
157
158=for apidoc Ams||XSRETURN_UNDEF
159Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
160
161=for apidoc Ams||XSRETURN_EMPTY
162Return an empty list from an XSUB immediately.
163
ccfc67b7
JH
164=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
165
954c1994
GS
166=for apidoc AmU||newXSproto
167Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
168the subs.
169
170=for apidoc AmU||XS_VERSION
171The version identifier for an XS module. This is usually
172handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
173
174=for apidoc Ams||XS_VERSION_BOOTCHECK
175Macro to verify that a PM module's $VERSION variable matches the XS
176module's C<XS_VERSION> variable. This is usually handled automatically by
177C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
178
179=cut
180*/
181
4633a7c4
LW
182#define XST_mIV(i,v) (ST(i) = sv_2mortal(newSViv(v)) )
183#define XST_mNV(i,v) (ST(i) = sv_2mortal(newSVnv(v)) )
184#define XST_mPV(i,v) (ST(i) = sv_2mortal(newSVpv(v,0)))
79cb57f6 185#define XST_mPVN(i,v,n) (ST(i) = sv_2mortal(newSVpvn(v,n)))
3280af22
NIS
186#define XST_mNO(i) (ST(i) = &PL_sv_no )
187#define XST_mYES(i) (ST(i) = &PL_sv_yes )
188#define XST_mUNDEF(i) (ST(i) = &PL_sv_undef)
954c1994
GS
189
190#define XSRETURN(off) \
191 STMT_START { \
192 PL_stack_sp = PL_stack_base + ax + ((off) - 1); \
193 return; \
194 } STMT_END
195
80b92232
PP
196#define XSRETURN_IV(v) STMT_START { XST_mIV(0,v); XSRETURN(1); } STMT_END
197#define XSRETURN_NV(v) STMT_START { XST_mNV(0,v); XSRETURN(1); } STMT_END
198#define XSRETURN_PV(v) STMT_START { XST_mPV(0,v); XSRETURN(1); } STMT_END
954c1994 199#define XSRETURN_PVN(v,n) STMT_START { XST_mPVN(0,v,n); XSRETURN(1); } STMT_END
80b92232
PP
200#define XSRETURN_NO STMT_START { XST_mNO(0); XSRETURN(1); } STMT_END
201#define XSRETURN_YES STMT_START { XST_mYES(0); XSRETURN(1); } STMT_END
202#define XSRETURN_UNDEF STMT_START { XST_mUNDEF(0); XSRETURN(1); } STMT_END
203#define XSRETURN_EMPTY STMT_START { XSRETURN(0); } STMT_END
382b8d97 204
37120919 205#define newXSproto(a,b,c,d) sv_setpv((SV*)newXS(a,b,c), d)
720fb644
PP
206
207#ifdef XS_VERSION
c6af7a1a 208# define XS_VERSION_BOOTCHECK \
774d564b 209 STMT_START { \
2d8e6c8d
GS
210 SV *tmpsv; STRLEN n_a; \
211 char *vn = Nullch, *module = SvPV(ST(0),n_a); \
774d564b 212 if (items >= 2) /* version supplied as bootstrap arg */ \
6b88bc9c 213 tmpsv = ST(1); \
774d564b 214 else { \
46fc3d4c 215 /* XXX GV_ADDWARN */ \
cea2e8a9 216 tmpsv = get_sv(Perl_form(aTHX_ "%s::%s", module, \
864dbfa3 217 vn = "XS_VERSION"), FALSE); \
6b88bc9c 218 if (!tmpsv || !SvOK(tmpsv)) \
cea2e8a9 219 tmpsv = get_sv(Perl_form(aTHX_ "%s::%s", module, \
864dbfa3 220 vn = "VERSION"), FALSE); \
774d564b 221 } \
2d8e6c8d 222 if (tmpsv && (!SvOK(tmpsv) || strNE(XS_VERSION, SvPV(tmpsv, n_a)))) \
894356b3 223 Perl_croak(aTHX_ "%s object version %s does not match %s%s%s%s %"SVf,\
ae66e5c8
CS
224 module, XS_VERSION, \
225 vn ? "$" : "", vn ? module : "", vn ? "::" : "", \
6b88bc9c 226 vn ? vn : "bootstrap parameter", tmpsv); \
80b92232 227 } STMT_END
720fb644 228#else
c6af7a1a 229# define XS_VERSION_BOOTCHECK
720fb644 230#endif
76e3520e 231
6a31061a
PM
232/*
233 The DBM_setFilter & DBM_ckFilter macros are only used by
234 the *DB*_File modules
235*/
236
237#define DBM_setFilter(db_type,code) \
238 { \
239 if (db_type) \
240 RETVAL = sv_mortalcopy(db_type) ; \
241 ST(0) = RETVAL ; \
242 if (db_type && (code == &PL_sv_undef)) { \
243 SvREFCNT_dec(db_type) ; \
244 db_type = NULL ; \
245 } \
246 else if (code) { \
247 if (db_type) \
248 sv_setsv(db_type, code) ; \
249 else \
250 db_type = newSVsv(code) ; \
251 } \
252 }
253
254#define DBM_ckFilter(arg,type,name) \
255 if (db->type) { \
256 if (db->filtering) { \
257 croak("recursion detected in %s", name) ; \
258 } \
259 ENTER ; \
260 SAVETMPS ; \
261 SAVEINT(db->filtering) ; \
262 db->filtering = TRUE ; \
263 SAVESPTR(DEFSV) ; \
264 DEFSV = arg ; \
265 SvTEMP_off(arg) ; \
266 PUSHMARK(SP) ; \
267 PUTBACK ; \
268 (void) perl_call_sv(db->type, G_DISCARD); \
269 SPAGAIN ; \
270 PUTBACK ; \
271 FREETMPS ; \
272 LEAVE ; \
273 }
274
51371543 275#if 1 /* for compatibility */
dc9e4912
GS
276# define VTBL_sv &PL_vtbl_sv
277# define VTBL_env &PL_vtbl_env
278# define VTBL_envelem &PL_vtbl_envelem
279# define VTBL_sig &PL_vtbl_sig
280# define VTBL_sigelem &PL_vtbl_sigelem
281# define VTBL_pack &PL_vtbl_pack
282# define VTBL_packelem &PL_vtbl_packelem
283# define VTBL_dbline &PL_vtbl_dbline
284# define VTBL_isa &PL_vtbl_isa
285# define VTBL_isaelem &PL_vtbl_isaelem
286# define VTBL_arylen &PL_vtbl_arylen
287# define VTBL_glob &PL_vtbl_glob
288# define VTBL_mglob &PL_vtbl_mglob
289# define VTBL_nkeys &PL_vtbl_nkeys
290# define VTBL_taint &PL_vtbl_taint
291# define VTBL_substr &PL_vtbl_substr
292# define VTBL_vec &PL_vtbl_vec
293# define VTBL_pos &PL_vtbl_pos
294# define VTBL_bm &PL_vtbl_bm
295# define VTBL_fm &PL_vtbl_fm
296# define VTBL_uvar &PL_vtbl_uvar
297# define VTBL_defelem &PL_vtbl_defelem
298# define VTBL_regexp &PL_vtbl_regexp
299# define VTBL_regdata &PL_vtbl_regdata
300# define VTBL_regdatum &PL_vtbl_regdatum
301# ifdef USE_LOCALE_COLLATE
302# define VTBL_collxfrm &PL_vtbl_collxfrm
303# endif
9e7bc3e8
JD
304# define VTBL_amagic &PL_vtbl_amagic
305# define VTBL_amagicelem &PL_vtbl_amagicelem
dc9e4912
GS
306#endif
307
6f4183fe 308#include "perlapi.h"
c6af7a1a 309
e8ee3774 310#if defined(PERL_IMPLICIT_CONTEXT) && !defined(PERL_NO_GET_CONTEXT) && !defined(PERL_CORE)
c5be433b
GS
311# undef aTHX
312# undef aTHX_
54aff467
GS
313# define aTHX PERL_GET_THX
314# define aTHX_ aTHX,
54aff467
GS
315#endif
316
acfe0abc 317#if defined(PERL_IMPLICIT_SYS) && !defined(PERL_CORE)
c6af7a1a 318# ifndef NO_XSLOCKS
2986a63f
JH
319# if defined (NETWARE) && defined (USE_STDIO)
320# define times PerlProc_times
321# define setuid PerlProc_setuid
322# define setgid PerlProc_setgid
323# define getpid PerlProc_getpid
324# define pause PerlProc_pause
325# define exit PerlProc_exit
326# define _exit PerlProc__exit
327# else
c6af7a1a
GS
328# undef closedir
329# undef opendir
330# undef stdin
331# undef stdout
332# undef stderr
333# undef feof
334# undef ferror
335# undef fgetpos
336# undef ioctl
337# undef getlogin
338# undef setjmp
339# undef getc
340# undef ungetc
341# undef fileno
342
cb69f87a 343/* Following symbols were giving redefinition errors while building extensions - sgp 17th Oct 2000 */
2986a63f
JH
344#ifdef NETWARE
345# undef readdir
346# undef fstat
347# undef stat
348# undef longjmp
349# undef endhostent
350# undef endnetent
351# undef endprotoent
352# undef endservent
353# undef gethostbyaddr
354# undef gethostbyname
355# undef gethostent
356# undef getnetbyaddr
357# undef getnetbyname
358# undef getnetent
359# undef getprotobyname
360# undef getprotobynumber
361# undef getprotoent
362# undef getservbyname
363# undef getservbyport
364# undef getservent
365# undef inet_ntoa
366# undef sethostent
367# undef setnetent
368# undef setprotoent
369# undef setservent
370#endif /* NETWARE */
371
1018e26f
NIS
372# undef socketpair
373
c6af7a1a
GS
374# define mkdir PerlDir_mkdir
375# define chdir PerlDir_chdir
376# define rmdir PerlDir_rmdir
377# define closedir PerlDir_close
378# define opendir PerlDir_open
379# define readdir PerlDir_read
380# define rewinddir PerlDir_rewind
381# define seekdir PerlDir_seek
382# define telldir PerlDir_tell
383# define putenv PerlEnv_putenv
384# define getenv PerlEnv_getenv
b2af26b1 385# define uname PerlEnv_uname
197357d0
GS
386# define stdin PerlSIO_stdin
387# define stdout PerlSIO_stdout
388# define stderr PerlSIO_stderr
f9415d23
NIS
389# define fopen PerlSIO_fopen
390# define fclose PerlSIO_fclose
391# define feof PerlSIO_feof
392# define ferror PerlSIO_ferror
b6d726d6 393# define clearerr PerlSIO_clearerr
f9415d23
NIS
394# define getc PerlSIO_getc
395# define fputc PerlSIO_fputc
396# define fputs PerlSIO_fputs
397# define fflush PerlSIO_fflush
398# define ungetc PerlSIO_ungetc
399# define fileno PerlSIO_fileno
400# define fdopen PerlSIO_fdopen
401# define freopen PerlSIO_freopen
402# define fread PerlSIO_fread
403# define fwrite PerlSIO_fwrite
22a46b6e
NIS
404# define setbuf PerlSIO_setbuf
405# define setvbuf PerlSIO_setvbuf
406# define setlinebuf PerlSIO_setlinebuf
1f59ddd9
GS
407# define stdoutf PerlSIO_stdoutf
408# define vfprintf PerlSIO_vprintf
f9415d23
NIS
409# define ftell PerlSIO_ftell
410# define fseek PerlSIO_fseek
411# define fgetpos PerlSIO_fgetpos
412# define fsetpos PerlSIO_fsetpos
413# define frewind PerlSIO_rewind
414# define tmpfile PerlSIO_tmpfile
c6af7a1a
GS
415# define access PerlLIO_access
416# define chmod PerlLIO_chmod
417# define chsize PerlLIO_chsize
418# define close PerlLIO_close
419# define dup PerlLIO_dup
420# define dup2 PerlLIO_dup2
421# define flock PerlLIO_flock
422# define fstat PerlLIO_fstat
423# define ioctl PerlLIO_ioctl
424# define isatty PerlLIO_isatty
6b980173 425# define link PerlLIO_link
c6af7a1a
GS
426# define lseek PerlLIO_lseek
427# define lstat PerlLIO_lstat
428# define mktemp PerlLIO_mktemp
429# define open PerlLIO_open
430# define read PerlLIO_read
431# define rename PerlLIO_rename
432# define setmode PerlLIO_setmode
4f49e16e 433# define stat(buf,sb) PerlLIO_stat(buf,sb)
c6af7a1a
GS
434# define tmpnam PerlLIO_tmpnam
435# define umask PerlLIO_umask
436# define unlink PerlLIO_unlink
437# define utime PerlLIO_utime
438# define write PerlLIO_write
439# define malloc PerlMem_malloc
440# define realloc PerlMem_realloc
441# define free PerlMem_free
442# define abort PerlProc_abort
443# define exit PerlProc_exit
444# define _exit PerlProc__exit
445# define execl PerlProc_execl
446# define execv PerlProc_execv
447# define execvp PerlProc_execvp
448# define getuid PerlProc_getuid
449# define geteuid PerlProc_geteuid
450# define getgid PerlProc_getgid
451# define getegid PerlProc_getegid
452# define getlogin PerlProc_getlogin
453# define kill PerlProc_kill
454# define killpg PerlProc_killpg
455# define pause PerlProc_pause
456# define popen PerlProc_popen
457# define pclose PerlProc_pclose
458# define pipe PerlProc_pipe
459# define setuid PerlProc_setuid
460# define setgid PerlProc_setgid
461# define sleep PerlProc_sleep
462# define times PerlProc_times
463# define wait PerlProc_wait
464# define setjmp PerlProc_setjmp
465# define longjmp PerlProc_longjmp
466# define signal PerlProc_signal
7766f137 467# define getpid PerlProc_getpid
57ab3dfe 468# define gettimeofday PerlProc_gettimeofday
c6af7a1a
GS
469# define htonl PerlSock_htonl
470# define htons PerlSock_htons
471# define ntohl PerlSock_ntohl
472# define ntohs PerlSock_ntohs
473# define accept PerlSock_accept
474# define bind PerlSock_bind
475# define connect PerlSock_connect
476# define endhostent PerlSock_endhostent
477# define endnetent PerlSock_endnetent
478# define endprotoent PerlSock_endprotoent
479# define endservent PerlSock_endservent
480# define gethostbyaddr PerlSock_gethostbyaddr
481# define gethostbyname PerlSock_gethostbyname
482# define gethostent PerlSock_gethostent
483# define gethostname PerlSock_gethostname
484# define getnetbyaddr PerlSock_getnetbyaddr
485# define getnetbyname PerlSock_getnetbyname
486# define getnetent PerlSock_getnetent
487# define getpeername PerlSock_getpeername
488# define getprotobyname PerlSock_getprotobyname
489# define getprotobynumber PerlSock_getprotobynumber
490# define getprotoent PerlSock_getprotoent
491# define getservbyname PerlSock_getservbyname
492# define getservbyport PerlSock_getservbyport
493# define getservent PerlSock_getservent
494# define getsockname PerlSock_getsockname
495# define getsockopt PerlSock_getsockopt
496# define inet_addr PerlSock_inet_addr
497# define inet_ntoa PerlSock_inet_ntoa
498# define listen PerlSock_listen
499# define recv PerlSock_recv
500# define recvfrom PerlSock_recvfrom
501# define select PerlSock_select
502# define send PerlSock_send
503# define sendto PerlSock_sendto
504# define sethostent PerlSock_sethostent
505# define setnetent PerlSock_setnetent
506# define setprotoent PerlSock_setprotoent
507# define setservent PerlSock_setservent
508# define setsockopt PerlSock_setsockopt
509# define shutdown PerlSock_shutdown
510# define socket PerlSock_socket
511# define socketpair PerlSock_socketpair
2986a63f 512# endif /* NETWARE && USE_STDIO */
21c5e947
JH
513
514# ifdef USE_SOCKETS_AS_HANDLES
515# undef fd_set
516# undef FD_SET
517# undef FD_CLR
518# undef FD_ISSET
519# undef FD_ZERO
520# define fd_set Perl_fd_set
521# define FD_SET(n,p) PERL_FD_SET(n,p)
522# define FD_CLR(n,p) PERL_FD_CLR(n,p)
523# define FD_ISSET(n,p) PERL_FD_ISSET(n,p)
524# define FD_ZERO(p) PERL_FD_ZERO(p)
525# endif /* USE_SOCKETS_AS_HANDLES */
526
c6af7a1a 527# endif /* NO_XSLOCKS */
acfe0abc 528#endif /* PERL_IMPLICIT_SYS && !PERL_CORE */
b4ba0ab9 529
cfeeb022 530#endif /* _INC_PERL_XSUB_H */ /* include guard */