This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix up Larry's copyright statements to my best knowledge.
[perl5.git] / XSUB.h
1 /*    XSUB.h
2  *
3  *    Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999,
4  *    2000, 2001, 2002, 2003, by Larry Wall and others
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
11 #ifndef _INC_PERL_XSUB_H
12 #define _INC_PERL_XSUB_H 1
13
14 /* first, some documentation for xsubpp-generated items */
15
16 /*
17 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
18
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>.
22
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">.
27
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++">.
32
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.
37
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">.
41
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">.
45
46 =for apidoc Am|SV*|ST|int ix
47 Used to access elements on the XSUB's stack.
48
49 =for apidoc AmU||XS
50 Macro to declare an XSUB and its C parameter list.  This is handled by
51 C<xsubpp>.
52
53 =for apidoc Ams||dAX
54 Sets up the C<ax> variable.
55 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
56
57 =for apidoc Ams||dITEMS
58 Sets up the C<items> variable.
59 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
60
61 =for apidoc Ams||dXSARGS
62 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
63 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
64 This is usually handled automatically by C<xsubpp>.
65
66 =for apidoc Ams||dXSI32
67 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
68 handled automatically by C<xsubpp>.
69
70 =cut
71 */
72
73 #define ST(off) PL_stack_base[ax + (off)]
74
75 #if defined(__CYGWIN__) && defined(USE_DYNAMIC_LOADING)
76 #  define XS(name) __declspec(dllexport) void name(pTHX_ CV* cv)
77 #else
78 #  define XS(name) void name(pTHX_ CV* cv)
79 #endif
80
81 #define dAX I32 ax = MARK - PL_stack_base + 1
82
83 #define dITEMS I32 items = SP - MARK
84
85 #define dXSARGS                         \
86         dSP; dMARK;                     \
87         dAX; dITEMS
88
89 #define dXSTARG SV * targ = ((PL_op->op_private & OPpENTERSUB_HASTARG) \
90                              ? PAD_SV(PL_op->op_targ) : sv_newmortal())
91
92 /* Should be used before final PUSHi etc. if not in PPCODE section. */
93 #define XSprePUSH (sp = PL_stack_base + ax - 1)
94
95 #define XSANY CvXSUBANY(cv)
96
97 #define dXSI32 I32 ix = XSANY.any_i32
98
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)
105 #define XSINTERFACE_FUNC(ret,cv,f)     ((XSINTERFACE_CVT(ret,))(f))
106 #define XSINTERFACE_FUNC_SET(cv,f)      \
107                 CvXSUBANY(cv).any_dptr = (void (*) (pTHX_ void*))(f)
108
109 /* Simple macros to put new mortal values onto the stack.   */
110 /* Typically used to return values from XS functions.       */
111
112 /*
113 =head1 Stack Manipulation Macros
114
115 =for apidoc Am|void|XST_mIV|int pos|IV iv
116 Place an integer into the specified position C<pos> on the stack.  The
117 value is stored in a new mortal SV.
118
119 =for apidoc Am|void|XST_mNV|int pos|NV nv
120 Place a double into the specified position C<pos> on the stack.  The value
121 is stored in a new mortal SV.
122
123 =for apidoc Am|void|XST_mPV|int pos|char* str
124 Place a copy of a string into the specified position C<pos> on the stack. 
125 The value is stored in a new mortal SV.
126
127 =for apidoc Am|void|XST_mNO|int pos
128 Place C<&PL_sv_no> into the specified position C<pos> on the
129 stack.
130
131 =for apidoc Am|void|XST_mYES|int pos
132 Place C<&PL_sv_yes> into the specified position C<pos> on the
133 stack.
134
135 =for apidoc Am|void|XST_mUNDEF|int pos
136 Place C<&PL_sv_undef> into the specified position C<pos> on the
137 stack.
138
139 =for apidoc Am|void|XSRETURN|int nitems
140 Return from XSUB, indicating number of items on the stack.  This is usually
141 handled by C<xsubpp>.
142
143 =for apidoc Am|void|XSRETURN_IV|IV iv
144 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
145
146 =for apidoc Am|void|XSRETURN_NV|NV nv
147 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
148
149 =for apidoc Am|void|XSRETURN_PV|char* str
150 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
151
152 =for apidoc Ams||XSRETURN_NO
153 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
154
155 =for apidoc Ams||XSRETURN_YES
156 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
157
158 =for apidoc Ams||XSRETURN_UNDEF
159 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
160
161 =for apidoc Ams||XSRETURN_EMPTY
162 Return an empty list from an XSUB immediately.
163
164 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
165
166 =for apidoc AmU||newXSproto
167 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
168 the subs.
169
170 =for apidoc AmU||XS_VERSION
171 The version identifier for an XS module.  This is usually
172 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
173
174 =for apidoc Ams||XS_VERSION_BOOTCHECK
175 Macro to verify that a PM module's $VERSION variable matches the XS
176 module's C<XS_VERSION> variable.  This is usually handled automatically by
177 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
178
179 =cut
180 */
181
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)))
185 #define XST_mPVN(i,v,n)  (ST(i) = sv_2mortal(newSVpvn(v,n)))
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)
189
190 #define XSRETURN(off)                                   \
191     STMT_START {                                        \
192         PL_stack_sp = PL_stack_base + ax + ((off) - 1); \
193         return;                                         \
194     } STMT_END
195
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
199 #define XSRETURN_PVN(v,n) STMT_START { XST_mPVN(0,v,n);  XSRETURN(1); } STMT_END
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
204
205 #define newXSproto(a,b,c,d)     sv_setpv((SV*)newXS(a,b,c), d)
206
207 #ifdef XS_VERSION
208 #  define XS_VERSION_BOOTCHECK \
209     STMT_START {                                                        \
210         SV *tmpsv; STRLEN n_a;                                          \
211         char *vn = Nullch, *module = SvPV(ST(0),n_a);                   \
212         if (items >= 2)  /* version supplied as bootstrap arg */        \
213             tmpsv = ST(1);                                              \
214         else {                                                          \
215             /* XXX GV_ADDWARN */                                        \
216             tmpsv = get_sv(Perl_form(aTHX_ "%s::%s", module,            \
217                                 vn = "XS_VERSION"), FALSE);             \
218             if (!tmpsv || !SvOK(tmpsv))                                 \
219                 tmpsv = get_sv(Perl_form(aTHX_ "%s::%s", module,        \
220                                     vn = "VERSION"), FALSE);            \
221         }                                                               \
222         if (tmpsv && (!SvOK(tmpsv) || strNE(XS_VERSION, SvPV(tmpsv, n_a))))     \
223             Perl_croak(aTHX_ "%s object version %s does not match %s%s%s%s %"SVf,\
224                   module, XS_VERSION,                                   \
225                   vn ? "$" : "", vn ? module : "", vn ? "::" : "",      \
226                   vn ? vn : "bootstrap parameter", tmpsv);              \
227     } STMT_END
228 #else
229 #  define XS_VERSION_BOOTCHECK
230 #endif
231
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
275 #if 1           /* for compatibility */
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
304 #  define VTBL_amagic           &PL_vtbl_amagic
305 #  define VTBL_amagicelem       &PL_vtbl_amagicelem
306 #endif
307
308 #include "perlapi.h"
309
310 #if defined(PERL_IMPLICIT_CONTEXT) && !defined(PERL_NO_GET_CONTEXT) && !defined(PERL_CORE)
311 #  undef aTHX
312 #  undef aTHX_
313 #  define aTHX          PERL_GET_THX
314 #  define aTHX_         aTHX,
315 #endif
316
317 #if defined(PERL_IMPLICIT_SYS) && !defined(PERL_CORE)
318 #  ifndef NO_XSLOCKS
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
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
343 /* Following symbols were giving redefinition errors while building extensions - sgp 17th Oct 2000 */
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
372 #    undef  socketpair
373
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
385 #    define uname               PerlEnv_uname
386 #    define stdin               PerlSIO_stdin
387 #    define stdout              PerlSIO_stdout
388 #    define stderr              PerlSIO_stderr
389 #    define fopen               PerlSIO_fopen
390 #    define fclose              PerlSIO_fclose
391 #    define feof                PerlSIO_feof
392 #    define ferror              PerlSIO_ferror
393 #    define clearerr            PerlSIO_clearerr
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
404 #    define setbuf              PerlSIO_setbuf
405 #    define setvbuf             PerlSIO_setvbuf
406 #    define setlinebuf          PerlSIO_setlinebuf
407 #    define stdoutf             PerlSIO_stdoutf
408 #    define vfprintf            PerlSIO_vprintf
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
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
425 #    define link                PerlLIO_link
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
433 #    define stat(buf,sb)        PerlLIO_stat(buf,sb)
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
467 #    define getpid              PerlProc_getpid
468 #    define gettimeofday        PerlProc_gettimeofday
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
512 #       endif   /* NETWARE && USE_STDIO */
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
527 #  endif  /* NO_XSLOCKS */
528 #endif  /* PERL_IMPLICIT_SYS && !PERL_CORE */
529
530 #endif /* _INC_PERL_XSUB_H */           /* include guard */