This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Missed the =head1 additions.
[perl5.git] / XSUB.h
1 #ifndef _INC_PERL_XSUB_H
2 #define _INC_PERL_XSUB_H 1
3
4 /* first, some documentation for xsubpp-generated items */
5
6 /*
7 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
8
9 =for apidoc Amn|char*|CLASS
10 Variable which is setup by C<xsubpp> to indicate the 
11 class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.
12
13 =for apidoc Amn|(whatever)|RETVAL
14 Variable which is setup by C<xsubpp> to hold the return value for an 
15 XSUB. This is always the proper type for the XSUB. See 
16 L<perlxs/"The RETVAL Variable">.
17
18 =for apidoc Amn|(whatever)|THIS
19 Variable which is setup by C<xsubpp> to designate the object in a C++ 
20 XSUB.  This is always the proper type for the C++ object.  See C<CLASS> and 
21 L<perlxs/"Using XS With C++">.
22
23 =for apidoc Amn|I32|ax
24 Variable which is setup by C<xsubpp> to indicate the stack base offset,
25 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros.  The C<dMARK> macro
26 must be called prior to setup the C<MARK> variable.
27
28 =for apidoc Amn|I32|items
29 Variable which is setup by C<xsubpp> to indicate the number of 
30 items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.
31
32 =for apidoc Amn|I32|ix
33 Variable which is setup by C<xsubpp> to indicate which of an 
34 XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.
35
36 =for apidoc Am|SV*|ST|int ix
37 Used to access elements on the XSUB's stack.
38
39 =for apidoc AmU||XS
40 Macro to declare an XSUB and its C parameter list.  This is handled by
41 C<xsubpp>.
42
43 =for apidoc Ams||dAX
44 Sets up the C<ax> variable.
45 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
46
47 =for apidoc Ams||dITEMS
48 Sets up the C<items> variable.
49 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
50
51 =for apidoc Ams||dXSARGS
52 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
53 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
54 This is usually handled automatically by C<xsubpp>.
55
56 =for apidoc Ams||dXSI32
57 Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
58 handled automatically by C<xsubpp>.
59
60 =cut
61 */
62
63 #define ST(off) PL_stack_base[ax + (off)]
64
65 #if defined(__CYGWIN__) && defined(USE_DYNAMIC_LOADING)
66 #  define XS(name) __declspec(dllexport) void name(pTHX_ CV* cv)
67 #else
68 #  define XS(name) void name(pTHX_ CV* cv)
69 #endif
70
71 #define dAX I32 ax = MARK - PL_stack_base + 1
72
73 #define dITEMS I32 items = SP - MARK
74
75 #define dXSARGS                         \
76         dSP; dMARK;                     \
77         dAX; dITEMS
78
79 #define dXSTARG SV * targ = ((PL_op->op_private & OPpENTERSUB_HASTARG) \
80                              ? PAD_SV(PL_op->op_targ) : sv_newmortal())
81
82 /* Should be used before final PUSHi etc. if not in PPCODE section. */
83 #define XSprePUSH (sp = PL_stack_base + ax - 1)
84
85 #define XSANY CvXSUBANY(cv)
86
87 #define dXSI32 I32 ix = XSANY.any_i32
88
89 #ifdef __cplusplus
90 #  define XSINTERFACE_CVT(ret,name) ret (*name)(...)
91 #else
92 #  define XSINTERFACE_CVT(ret,name) ret (*name)()
93 #endif
94 #define dXSFUNCTION(ret)                XSINTERFACE_CVT(ret,XSFUNCTION)
95 #define XSINTERFACE_FUNC(ret,cv,f)     ((XSINTERFACE_CVT(ret,))(f))
96 #define XSINTERFACE_FUNC_SET(cv,f)      \
97                 CvXSUBANY(cv).any_dptr = (void (*) (pTHX_ void*))(f)
98
99 /* Simple macros to put new mortal values onto the stack.   */
100 /* Typically used to return values from XS functions.       */
101
102 /*
103 =head1 Stack Manipulation Macros
104
105 =for apidoc Am|void|XST_mIV|int pos|IV iv
106 Place an integer into the specified position C<pos> on the stack.  The
107 value is stored in a new mortal SV.
108
109 =for apidoc Am|void|XST_mNV|int pos|NV nv
110 Place a double into the specified position C<pos> on the stack.  The value
111 is stored in a new mortal SV.
112
113 =for apidoc Am|void|XST_mPV|int pos|char* str
114 Place a copy of a string into the specified position C<pos> on the stack. 
115 The value is stored in a new mortal SV.
116
117 =for apidoc Am|void|XST_mNO|int pos
118 Place C<&PL_sv_no> into the specified position C<pos> on the
119 stack.
120
121 =for apidoc Am|void|XST_mYES|int pos
122 Place C<&PL_sv_yes> into the specified position C<pos> on the
123 stack.
124
125 =for apidoc Am|void|XST_mUNDEF|int pos
126 Place C<&PL_sv_undef> into the specified position C<pos> on the
127 stack.
128
129 =for apidoc Am|void|XSRETURN|int nitems
130 Return from XSUB, indicating number of items on the stack.  This is usually
131 handled by C<xsubpp>.
132
133 =for apidoc Am|void|XSRETURN_IV|IV iv
134 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
135
136 =for apidoc Am|void|XSRETURN_NV|NV nv
137 Return a double from an XSUB immediately.  Uses C<XST_mNV>.
138
139 =for apidoc Am|void|XSRETURN_PV|char* str
140 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
141
142 =for apidoc Ams||XSRETURN_NO
143 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
144
145 =for apidoc Ams||XSRETURN_YES
146 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
147
148 =for apidoc Ams||XSRETURN_UNDEF
149 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
150
151 =for apidoc Ams||XSRETURN_EMPTY
152 Return an empty list from an XSUB immediately.
153
154 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
155
156 =for apidoc AmU||newXSproto
157 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
158 the subs.
159
160 =for apidoc AmU||XS_VERSION
161 The version identifier for an XS module.  This is usually
162 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
163
164 =for apidoc Ams||XS_VERSION_BOOTCHECK
165 Macro to verify that a PM module's $VERSION variable matches the XS
166 module's C<XS_VERSION> variable.  This is usually handled automatically by
167 C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
168
169 =cut
170 */
171
172 #define XST_mIV(i,v)  (ST(i) = sv_2mortal(newSViv(v))  )
173 #define XST_mNV(i,v)  (ST(i) = sv_2mortal(newSVnv(v))  )
174 #define XST_mPV(i,v)  (ST(i) = sv_2mortal(newSVpv(v,0)))
175 #define XST_mPVN(i,v,n)  (ST(i) = sv_2mortal(newSVpvn(v,n)))
176 #define XST_mNO(i)    (ST(i) = &PL_sv_no   )
177 #define XST_mYES(i)   (ST(i) = &PL_sv_yes  )
178 #define XST_mUNDEF(i) (ST(i) = &PL_sv_undef)
179
180 #define XSRETURN(off)                                   \
181     STMT_START {                                        \
182         PL_stack_sp = PL_stack_base + ax + ((off) - 1); \
183         return;                                         \
184     } STMT_END
185
186 #define XSRETURN_IV(v) STMT_START { XST_mIV(0,v);  XSRETURN(1); } STMT_END
187 #define XSRETURN_NV(v) STMT_START { XST_mNV(0,v);  XSRETURN(1); } STMT_END
188 #define XSRETURN_PV(v) STMT_START { XST_mPV(0,v);  XSRETURN(1); } STMT_END
189 #define XSRETURN_PVN(v,n) STMT_START { XST_mPVN(0,v,n);  XSRETURN(1); } STMT_END
190 #define XSRETURN_NO    STMT_START { XST_mNO(0);    XSRETURN(1); } STMT_END
191 #define XSRETURN_YES   STMT_START { XST_mYES(0);   XSRETURN(1); } STMT_END
192 #define XSRETURN_UNDEF STMT_START { XST_mUNDEF(0); XSRETURN(1); } STMT_END
193 #define XSRETURN_EMPTY STMT_START {                XSRETURN(0); } STMT_END
194
195 #define newXSproto(a,b,c,d)     sv_setpv((SV*)newXS(a,b,c), d)
196
197 #ifdef XS_VERSION
198 #  define XS_VERSION_BOOTCHECK \
199     STMT_START {                                                        \
200         SV *tmpsv; STRLEN n_a;                                          \
201         char *vn = Nullch, *module = SvPV(ST(0),n_a);                   \
202         if (items >= 2)  /* version supplied as bootstrap arg */        \
203             tmpsv = ST(1);                                              \
204         else {                                                          \
205             /* XXX GV_ADDWARN */                                        \
206             tmpsv = get_sv(Perl_form(aTHX_ "%s::%s", module,            \
207                                 vn = "XS_VERSION"), FALSE);             \
208             if (!tmpsv || !SvOK(tmpsv))                                 \
209                 tmpsv = get_sv(Perl_form(aTHX_ "%s::%s", module,        \
210                                     vn = "VERSION"), FALSE);            \
211         }                                                               \
212         if (tmpsv && (!SvOK(tmpsv) || strNE(XS_VERSION, SvPV(tmpsv, n_a))))     \
213             Perl_croak(aTHX_ "%s object version %s does not match %s%s%s%s %"SVf,\
214                   module, XS_VERSION,                                   \
215                   vn ? "$" : "", vn ? module : "", vn ? "::" : "",      \
216                   vn ? vn : "bootstrap parameter", tmpsv);              \
217     } STMT_END
218 #else
219 #  define XS_VERSION_BOOTCHECK
220 #endif
221
222 #if 1           /* for compatibility */
223 #  define VTBL_sv               &PL_vtbl_sv
224 #  define VTBL_env              &PL_vtbl_env
225 #  define VTBL_envelem          &PL_vtbl_envelem
226 #  define VTBL_sig              &PL_vtbl_sig
227 #  define VTBL_sigelem          &PL_vtbl_sigelem
228 #  define VTBL_pack             &PL_vtbl_pack
229 #  define VTBL_packelem         &PL_vtbl_packelem
230 #  define VTBL_dbline           &PL_vtbl_dbline
231 #  define VTBL_isa              &PL_vtbl_isa
232 #  define VTBL_isaelem          &PL_vtbl_isaelem
233 #  define VTBL_arylen           &PL_vtbl_arylen
234 #  define VTBL_glob             &PL_vtbl_glob
235 #  define VTBL_mglob            &PL_vtbl_mglob
236 #  define VTBL_nkeys            &PL_vtbl_nkeys
237 #  define VTBL_taint            &PL_vtbl_taint
238 #  define VTBL_substr           &PL_vtbl_substr
239 #  define VTBL_vec              &PL_vtbl_vec
240 #  define VTBL_pos              &PL_vtbl_pos
241 #  define VTBL_bm               &PL_vtbl_bm
242 #  define VTBL_fm               &PL_vtbl_fm
243 #  define VTBL_uvar             &PL_vtbl_uvar
244 #  define VTBL_defelem          &PL_vtbl_defelem
245 #  define VTBL_regexp           &PL_vtbl_regexp
246 #  define VTBL_regdata          &PL_vtbl_regdata
247 #  define VTBL_regdatum         &PL_vtbl_regdatum
248 #  ifdef USE_LOCALE_COLLATE
249 #    define VTBL_collxfrm       &PL_vtbl_collxfrm
250 #  endif
251 #  define VTBL_amagic           &PL_vtbl_amagic
252 #  define VTBL_amagicelem       &PL_vtbl_amagicelem
253 #endif
254
255 #include "perlapi.h"
256
257 #if defined(PERL_IMPLICIT_CONTEXT) && !defined(PERL_NO_GET_CONTEXT) && !defined(PERL_CORE)
258 #  undef aTHX
259 #  undef aTHX_
260 #  define aTHX          PERL_GET_THX
261 #  define aTHX_         aTHX,
262 #endif
263
264 #if defined(PERL_IMPLICIT_SYS) && !defined(PERL_CORE)
265 #  ifndef NO_XSLOCKS
266 # if defined (NETWARE) && defined (USE_STDIO)
267 #    define times               PerlProc_times
268 #    define setuid              PerlProc_setuid
269 #    define setgid              PerlProc_setgid
270 #    define getpid              PerlProc_getpid
271 #    define pause               PerlProc_pause
272 #    define exit                PerlProc_exit
273 #    define _exit               PerlProc__exit
274 # else
275 #    undef closedir
276 #    undef opendir
277 #    undef stdin
278 #    undef stdout
279 #    undef stderr
280 #    undef feof
281 #    undef ferror
282 #    undef fgetpos
283 #    undef ioctl
284 #    undef getlogin
285 #    undef setjmp
286 #    undef getc
287 #    undef ungetc
288 #    undef fileno
289
290 /* Following symbols were giving redefinition errors while building extensions - sgp 17th Oct 2000 */
291 #ifdef NETWARE
292 #       undef readdir
293 #       undef fstat
294 #       undef stat
295 #       undef longjmp
296 #       undef endhostent
297 #       undef endnetent
298 #       undef endprotoent
299 #       undef endservent
300 #       undef gethostbyaddr
301 #       undef gethostbyname
302 #       undef gethostent
303 #       undef getnetbyaddr
304 #       undef getnetbyname
305 #       undef getnetent
306 #       undef getprotobyname
307 #       undef getprotobynumber
308 #       undef getprotoent
309 #       undef getservbyname
310 #       undef getservbyport
311 #       undef getservent
312 #       undef inet_ntoa
313 #       undef sethostent
314 #       undef setnetent
315 #       undef setprotoent
316 #       undef setservent
317 #endif  /* NETWARE */
318
319 #    define mkdir               PerlDir_mkdir
320 #    define chdir               PerlDir_chdir
321 #    define rmdir               PerlDir_rmdir
322 #    define closedir            PerlDir_close
323 #    define opendir             PerlDir_open
324 #    define readdir             PerlDir_read
325 #    define rewinddir           PerlDir_rewind
326 #    define seekdir             PerlDir_seek
327 #    define telldir             PerlDir_tell
328 #    define putenv              PerlEnv_putenv
329 #    define getenv              PerlEnv_getenv
330 #    define uname               PerlEnv_uname
331 #    define stdin               PerlIO_stdin()
332 #    define stdout              PerlIO_stdout()
333 #    define stderr              PerlIO_stderr()
334 #    define fopen               PerlIO_open
335 #    define fclose              PerlIO_close
336 #    define feof                PerlIO_eof
337 #    define ferror              PerlIO_error
338 #    define fclearerr           PerlIO_clearerr
339 #    define getc                PerlIO_getc
340 #    define fputc(c, f)         PerlIO_putc(f,c)
341 #    define fputs(s, f)         PerlIO_puts(f,s)
342 #    define fflush              PerlIO_flush
343 #    define ungetc(c, f)        PerlIO_ungetc((f),(c))
344 #    define fileno              PerlIO_fileno
345 #    define fdopen              PerlIO_fdopen
346 #    define freopen             PerlIO_reopen
347 #    define fread(b,s,c,f)      PerlIO_read((f),(b),(s*c))
348 #    define fwrite(b,s,c,f)     PerlIO_write((f),(b),(s*c))
349 #    define setbuf              PerlIO_setbuf
350 #    define setvbuf             PerlIO_setvbuf
351 #    define setlinebuf          PerlIO_setlinebuf
352 #    define stdoutf             PerlIO_stdoutf
353 #    define vfprintf            PerlIO_vprintf
354 #    define ftell               PerlIO_tell
355 #    define fseek               PerlIO_seek
356 #    define fgetpos             PerlIO_getpos
357 #    define fsetpos             PerlIO_setpos
358 #    define frewind             PerlIO_rewind
359 #    define tmpfile             PerlIO_tmpfile
360 #    define access              PerlLIO_access
361 #    define chmod               PerlLIO_chmod
362 #    define chsize              PerlLIO_chsize
363 #    define close               PerlLIO_close
364 #    define dup                 PerlLIO_dup
365 #    define dup2                PerlLIO_dup2
366 #    define flock               PerlLIO_flock
367 #    define fstat               PerlLIO_fstat
368 #    define ioctl               PerlLIO_ioctl
369 #    define isatty              PerlLIO_isatty
370 #    define link                PerlLIO_link
371 #    define lseek               PerlLIO_lseek
372 #    define lstat               PerlLIO_lstat
373 #    define mktemp              PerlLIO_mktemp
374 #    define open                PerlLIO_open
375 #    define read                PerlLIO_read
376 #    define rename              PerlLIO_rename
377 #    define setmode             PerlLIO_setmode
378 #    define stat(buf,sb)        PerlLIO_stat(buf,sb)
379 #    define tmpnam              PerlLIO_tmpnam
380 #    define umask               PerlLIO_umask
381 #    define unlink              PerlLIO_unlink
382 #    define utime               PerlLIO_utime
383 #    define write               PerlLIO_write
384 #    define malloc              PerlMem_malloc
385 #    define realloc             PerlMem_realloc
386 #    define free                PerlMem_free
387 #    define abort               PerlProc_abort
388 #    define exit                PerlProc_exit
389 #    define _exit               PerlProc__exit
390 #    define execl               PerlProc_execl
391 #    define execv               PerlProc_execv
392 #    define execvp              PerlProc_execvp
393 #    define getuid              PerlProc_getuid
394 #    define geteuid             PerlProc_geteuid
395 #    define getgid              PerlProc_getgid
396 #    define getegid             PerlProc_getegid
397 #    define getlogin            PerlProc_getlogin
398 #    define kill                PerlProc_kill
399 #    define killpg              PerlProc_killpg
400 #    define pause               PerlProc_pause
401 #    define popen               PerlProc_popen
402 #    define pclose              PerlProc_pclose
403 #    define pipe                PerlProc_pipe
404 #    define setuid              PerlProc_setuid
405 #    define setgid              PerlProc_setgid
406 #    define sleep               PerlProc_sleep
407 #    define times               PerlProc_times
408 #    define wait                PerlProc_wait
409 #    define setjmp              PerlProc_setjmp
410 #    define longjmp             PerlProc_longjmp
411 #    define signal              PerlProc_signal
412 #    define getpid              PerlProc_getpid
413 #    define htonl               PerlSock_htonl
414 #    define htons               PerlSock_htons
415 #    define ntohl               PerlSock_ntohl
416 #    define ntohs               PerlSock_ntohs
417 #    define accept              PerlSock_accept
418 #    define bind                PerlSock_bind
419 #    define connect             PerlSock_connect
420 #    define endhostent          PerlSock_endhostent
421 #    define endnetent           PerlSock_endnetent
422 #    define endprotoent         PerlSock_endprotoent
423 #    define endservent          PerlSock_endservent
424 #    define gethostbyaddr       PerlSock_gethostbyaddr
425 #    define gethostbyname       PerlSock_gethostbyname
426 #    define gethostent          PerlSock_gethostent
427 #    define gethostname         PerlSock_gethostname
428 #    define getnetbyaddr        PerlSock_getnetbyaddr
429 #    define getnetbyname        PerlSock_getnetbyname
430 #    define getnetent           PerlSock_getnetent
431 #    define getpeername         PerlSock_getpeername
432 #    define getprotobyname      PerlSock_getprotobyname
433 #    define getprotobynumber    PerlSock_getprotobynumber
434 #    define getprotoent         PerlSock_getprotoent
435 #    define getservbyname       PerlSock_getservbyname
436 #    define getservbyport       PerlSock_getservbyport
437 #    define getservent          PerlSock_getservent
438 #    define getsockname         PerlSock_getsockname
439 #    define getsockopt          PerlSock_getsockopt
440 #    define inet_addr           PerlSock_inet_addr
441 #    define inet_ntoa           PerlSock_inet_ntoa
442 #    define listen              PerlSock_listen
443 #    define recv                PerlSock_recv
444 #    define recvfrom            PerlSock_recvfrom
445 #    define select              PerlSock_select
446 #    define send                PerlSock_send
447 #    define sendto              PerlSock_sendto
448 #    define sethostent          PerlSock_sethostent
449 #    define setnetent           PerlSock_setnetent
450 #    define setprotoent         PerlSock_setprotoent
451 #    define setservent          PerlSock_setservent
452 #    define setsockopt          PerlSock_setsockopt
453 #    define shutdown            PerlSock_shutdown
454 #    define socket              PerlSock_socket
455 #    define socketpair          PerlSock_socketpair
456 #       endif   /* NETWARE && USE_STDIO */
457 #  endif  /* NO_XSLOCKS */
458 #endif  /* PERL_IMPLICIT_SYS && !PERL_CORE */
459
460 #endif /* _INC_PERL_XSUB_H */           /* include guard */