source: trunk/third/perl/XSUB.h @ 20075

Revision 20075, 17.4 KB checked in by zacheiss, 21 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r20074, which included commits to RCS files with non-trunk default branches.
Line 
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
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
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
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
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
61=for apidoc Ams||dXSARGS
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>.
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
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_dxptr = (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
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_UV|IV uv
147Return an integer from an XSUB immediately.  Uses C<XST_mUV>.
148
149=for apidoc Am|void|XSRETURN_NV|NV nv
150Return a double from an XSUB immediately.  Uses C<XST_mNV>.
151
152=for apidoc Am|void|XSRETURN_PV|char* str
153Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
154
155=for apidoc Ams||XSRETURN_NO
156Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
157
158=for apidoc Ams||XSRETURN_YES
159Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
160
161=for apidoc Ams||XSRETURN_UNDEF
162Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
163
164=for apidoc Ams||XSRETURN_EMPTY
165Return an empty list from an XSUB immediately.
166
167=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
168
169=for apidoc AmU||newXSproto
170Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
171the subs.
172
173=for apidoc AmU||XS_VERSION
174The version identifier for an XS module.  This is usually
175handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
176
177=for apidoc Ams||XS_VERSION_BOOTCHECK
178Macro to verify that a PM module's $VERSION variable matches the XS
179module's C<XS_VERSION> variable.  This is usually handled automatically by
180C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
181
182=cut
183*/
184
185#define XST_mIV(i,v)  (ST(i) = sv_2mortal(newSViv(v))  )
186#define XST_mUV(i,v)  (ST(i) = sv_2mortal(newSVuv(v))  )
187#define XST_mNV(i,v)  (ST(i) = sv_2mortal(newSVnv(v))  )
188#define XST_mPV(i,v)  (ST(i) = sv_2mortal(newSVpv(v,0)))
189#define XST_mPVN(i,v,n)  (ST(i) = sv_2mortal(newSVpvn(v,n)))
190#define XST_mNO(i)    (ST(i) = &PL_sv_no   )
191#define XST_mYES(i)   (ST(i) = &PL_sv_yes  )
192#define XST_mUNDEF(i) (ST(i) = &PL_sv_undef)
193
194#define XSRETURN(off)                                   \
195    STMT_START {                                        \
196        IV tmpXSoff = (off);                            \
197        PL_stack_sp = PL_stack_base + ax + (tmpXSoff - 1);      \
198        return;                                         \
199    } STMT_END
200
201#define XSRETURN_IV(v) STMT_START { XST_mIV(0,v);  XSRETURN(1); } STMT_END
202#define XSRETURN_UV(v) STMT_START { XST_mUV(0,v);  XSRETURN(1); } STMT_END
203#define XSRETURN_NV(v) STMT_START { XST_mNV(0,v);  XSRETURN(1); } STMT_END
204#define XSRETURN_PV(v) STMT_START { XST_mPV(0,v);  XSRETURN(1); } STMT_END
205#define XSRETURN_PVN(v,n) STMT_START { XST_mPVN(0,v,n);  XSRETURN(1); } STMT_END
206#define XSRETURN_NO    STMT_START { XST_mNO(0);    XSRETURN(1); } STMT_END
207#define XSRETURN_YES   STMT_START { XST_mYES(0);   XSRETURN(1); } STMT_END
208#define XSRETURN_UNDEF STMT_START { XST_mUNDEF(0); XSRETURN(1); } STMT_END
209#define XSRETURN_EMPTY STMT_START {                XSRETURN(0); } STMT_END
210
211#define newXSproto(a,b,c,d)     sv_setpv((SV*)newXS(a,b,c), d)
212
213#ifdef XS_VERSION
214#  define XS_VERSION_BOOTCHECK \
215    STMT_START {                                                        \
216        SV *_sv; STRLEN n_a;                                            \
217        char *vn = Nullch, *module = SvPV(ST(0),n_a);                   \
218        if (items >= 2)  /* version supplied as bootstrap arg */        \
219            _sv = ST(1);                                                \
220        else {                                                          \
221            /* XXX GV_ADDWARN */                                        \
222            _sv = get_sv(Perl_form(aTHX_ "%s::%s", module,              \
223                                vn = "XS_VERSION"), FALSE);             \
224            if (!_sv || !SvOK(_sv))                                     \
225                _sv = get_sv(Perl_form(aTHX_ "%s::%s", module,  \
226                                    vn = "VERSION"), FALSE);            \
227        }                                                               \
228        if (_sv && (!SvOK(_sv) || strNE(XS_VERSION, SvPV(_sv, n_a))))   \
229            Perl_croak(aTHX_ "%s object version %s does not match %s%s%s%s %"SVf,\
230                  module, XS_VERSION,                                   \
231                  vn ? "$" : "", vn ? module : "", vn ? "::" : "",      \
232                  vn ? vn : "bootstrap parameter", _sv);                \
233    } STMT_END
234#else
235#  define XS_VERSION_BOOTCHECK
236#endif
237
238/*
239   The DBM_setFilter & DBM_ckFilter macros are only used by
240   the *DB*_File modules
241*/
242
243#define DBM_setFilter(db_type,code)                             \
244        {                                                       \
245            if (db_type)                                        \
246                RETVAL = sv_mortalcopy(db_type) ;               \
247            ST(0) = RETVAL ;                                    \
248            if (db_type && (code == &PL_sv_undef)) {            \
249                SvREFCNT_dec(db_type) ;                         \
250                db_type = NULL ;                                \
251            }                                                   \
252            else if (code) {                                    \
253                if (db_type)                                    \
254                    sv_setsv(db_type, code) ;                   \
255                else                                            \
256                    db_type = newSVsv(code) ;                   \
257            }                                                   \
258        }
259
260#define DBM_ckFilter(arg,type,name)                             \
261        if (db->type) {                                         \
262            if (db->filtering) {                                \
263                croak("recursion detected in %s", name) ;       \
264            }                                                   \
265            ENTER ;                                             \
266            SAVETMPS ;                                          \
267            SAVEINT(db->filtering) ;                            \
268            db->filtering = TRUE ;                              \
269            SAVESPTR(DEFSV) ;                                   \
270            if (name[7] == 's')                                 \
271                arg = newSVsv(arg);                             \
272            DEFSV = arg ;                                       \
273            SvTEMP_off(arg) ;                                   \
274            PUSHMARK(SP) ;                                      \
275            PUTBACK ;                                           \
276            (void) perl_call_sv(db->type, G_DISCARD);           \
277            SPAGAIN ;                                           \
278            PUTBACK ;                                           \
279            FREETMPS ;                                          \
280            LEAVE ;                                             \
281            if (name[7] == 's'){                                \
282                arg = sv_2mortal(arg);                          \
283            }                                                   \
284            SvOKp(arg);                                         \
285        }
286
287#if 1           /* for compatibility */
288#  define VTBL_sv               &PL_vtbl_sv
289#  define VTBL_env              &PL_vtbl_env
290#  define VTBL_envelem          &PL_vtbl_envelem
291#  define VTBL_sig              &PL_vtbl_sig
292#  define VTBL_sigelem          &PL_vtbl_sigelem
293#  define VTBL_pack             &PL_vtbl_pack
294#  define VTBL_packelem         &PL_vtbl_packelem
295#  define VTBL_dbline           &PL_vtbl_dbline
296#  define VTBL_isa              &PL_vtbl_isa
297#  define VTBL_isaelem          &PL_vtbl_isaelem
298#  define VTBL_arylen           &PL_vtbl_arylen
299#  define VTBL_glob             &PL_vtbl_glob
300#  define VTBL_mglob            &PL_vtbl_mglob
301#  define VTBL_nkeys            &PL_vtbl_nkeys
302#  define VTBL_taint            &PL_vtbl_taint
303#  define VTBL_substr           &PL_vtbl_substr
304#  define VTBL_vec              &PL_vtbl_vec
305#  define VTBL_pos              &PL_vtbl_pos
306#  define VTBL_bm               &PL_vtbl_bm
307#  define VTBL_fm               &PL_vtbl_fm
308#  define VTBL_uvar             &PL_vtbl_uvar
309#  define VTBL_defelem          &PL_vtbl_defelem
310#  define VTBL_regexp           &PL_vtbl_regexp
311#  define VTBL_regdata          &PL_vtbl_regdata
312#  define VTBL_regdatum         &PL_vtbl_regdatum
313#  ifdef USE_LOCALE_COLLATE
314#    define VTBL_collxfrm       &PL_vtbl_collxfrm
315#  endif
316#  define VTBL_amagic           &PL_vtbl_amagic
317#  define VTBL_amagicelem       &PL_vtbl_amagicelem
318#endif
319
320#include "perlapi.h"
321
322#if defined(PERL_IMPLICIT_CONTEXT) && !defined(PERL_NO_GET_CONTEXT) && !defined(PERL_CORE)
323#  undef aTHX
324#  undef aTHX_
325#  define aTHX          PERL_GET_THX
326#  define aTHX_         aTHX,
327#endif
328
329#if defined(PERL_IMPLICIT_SYS) && !defined(PERL_CORE)
330#  ifndef NO_XSLOCKS
331# if defined (NETWARE) && defined (USE_STDIO)
332#    define times               PerlProc_times
333#    define setuid              PerlProc_setuid
334#    define setgid              PerlProc_setgid
335#    define getpid              PerlProc_getpid
336#    define pause               PerlProc_pause
337#    define exit                PerlProc_exit
338#    define _exit               PerlProc__exit
339# else
340#    undef closedir
341#    undef opendir
342#    undef stdin
343#    undef stdout
344#    undef stderr
345#    undef feof
346#    undef ferror
347#    undef fgetpos
348#    undef ioctl
349#    undef getlogin
350#    undef setjmp
351#    undef getc
352#    undef ungetc
353#    undef fileno
354
355/* Following symbols were giving redefinition errors while building extensions - sgp 17th Oct 2000 */
356#ifdef NETWARE
357#       undef readdir
358#       undef fstat
359#       undef stat
360#       undef longjmp
361#       undef endhostent
362#       undef endnetent
363#       undef endprotoent
364#       undef endservent
365#       undef gethostbyaddr
366#       undef gethostbyname
367#       undef gethostent
368#       undef getnetbyaddr
369#       undef getnetbyname
370#       undef getnetent
371#       undef getprotobyname
372#       undef getprotobynumber
373#       undef getprotoent
374#       undef getservbyname
375#       undef getservbyport
376#       undef getservent
377#       undef inet_ntoa
378#       undef sethostent
379#       undef setnetent
380#       undef setprotoent
381#       undef setservent
382#endif  /* NETWARE */
383
384#    undef  socketpair
385
386#    define mkdir               PerlDir_mkdir
387#    define chdir               PerlDir_chdir
388#    define rmdir               PerlDir_rmdir
389#    define closedir            PerlDir_close
390#    define opendir             PerlDir_open
391#    define readdir             PerlDir_read
392#    define rewinddir           PerlDir_rewind
393#    define seekdir             PerlDir_seek
394#    define telldir             PerlDir_tell
395#    define putenv              PerlEnv_putenv
396#    define getenv              PerlEnv_getenv
397#    define uname               PerlEnv_uname
398#    define stdin               PerlSIO_stdin
399#    define stdout              PerlSIO_stdout
400#    define stderr              PerlSIO_stderr
401#    define fopen               PerlSIO_fopen
402#    define fclose              PerlSIO_fclose
403#    define feof                PerlSIO_feof
404#    define ferror              PerlSIO_ferror
405#    define clearerr            PerlSIO_clearerr
406#    define getc                PerlSIO_getc
407#    define fputc               PerlSIO_fputc
408#    define fputs               PerlSIO_fputs
409#    define fflush              PerlSIO_fflush
410#    define ungetc              PerlSIO_ungetc
411#    define fileno              PerlSIO_fileno
412#    define fdopen              PerlSIO_fdopen
413#    define freopen             PerlSIO_freopen
414#    define fread               PerlSIO_fread
415#    define fwrite              PerlSIO_fwrite
416#    define setbuf              PerlSIO_setbuf
417#    define setvbuf             PerlSIO_setvbuf
418#    define setlinebuf          PerlSIO_setlinebuf
419#    define stdoutf             PerlSIO_stdoutf
420#    define vfprintf            PerlSIO_vprintf
421#    define ftell               PerlSIO_ftell
422#    define fseek               PerlSIO_fseek
423#    define fgetpos             PerlSIO_fgetpos
424#    define fsetpos             PerlSIO_fsetpos
425#    define frewind             PerlSIO_rewind
426#    define tmpfile             PerlSIO_tmpfile
427#    define access              PerlLIO_access
428#    define chmod               PerlLIO_chmod
429#    define chsize              PerlLIO_chsize
430#    define close               PerlLIO_close
431#    define dup                 PerlLIO_dup
432#    define dup2                PerlLIO_dup2
433#    define flock               PerlLIO_flock
434#    define fstat               PerlLIO_fstat
435#    define ioctl               PerlLIO_ioctl
436#    define isatty              PerlLIO_isatty
437#    define link                PerlLIO_link
438#    define lseek               PerlLIO_lseek
439#    define lstat               PerlLIO_lstat
440#    define mktemp              PerlLIO_mktemp
441#    define open                PerlLIO_open
442#    define read                PerlLIO_read
443#    define rename              PerlLIO_rename
444#    define setmode             PerlLIO_setmode
445#    define stat(buf,sb)        PerlLIO_stat(buf,sb)
446#    define tmpnam              PerlLIO_tmpnam
447#    define umask               PerlLIO_umask
448#    define unlink              PerlLIO_unlink
449#    define utime               PerlLIO_utime
450#    define write               PerlLIO_write
451#    define malloc              PerlMem_malloc
452#    define realloc             PerlMem_realloc
453#    define free                PerlMem_free
454#    define abort               PerlProc_abort
455#    define exit                PerlProc_exit
456#    define _exit               PerlProc__exit
457#    define execl               PerlProc_execl
458#    define execv               PerlProc_execv
459#    define execvp              PerlProc_execvp
460#    define getuid              PerlProc_getuid
461#    define geteuid             PerlProc_geteuid
462#    define getgid              PerlProc_getgid
463#    define getegid             PerlProc_getegid
464#    define getlogin            PerlProc_getlogin
465#    define kill                PerlProc_kill
466#    define killpg              PerlProc_killpg
467#    define pause               PerlProc_pause
468#    define popen               PerlProc_popen
469#    define pclose              PerlProc_pclose
470#    define pipe                PerlProc_pipe
471#    define setuid              PerlProc_setuid
472#    define setgid              PerlProc_setgid
473#    define sleep               PerlProc_sleep
474#    define times               PerlProc_times
475#    define wait                PerlProc_wait
476#    define setjmp              PerlProc_setjmp
477#    define longjmp             PerlProc_longjmp
478#    define signal              PerlProc_signal
479#    define getpid              PerlProc_getpid
480#    define gettimeofday        PerlProc_gettimeofday
481#    define htonl               PerlSock_htonl
482#    define htons               PerlSock_htons
483#    define ntohl               PerlSock_ntohl
484#    define ntohs               PerlSock_ntohs
485#    define accept              PerlSock_accept
486#    define bind                PerlSock_bind
487#    define connect             PerlSock_connect
488#    define endhostent          PerlSock_endhostent
489#    define endnetent           PerlSock_endnetent
490#    define endprotoent         PerlSock_endprotoent
491#    define endservent          PerlSock_endservent
492#    define gethostbyaddr       PerlSock_gethostbyaddr
493#    define gethostbyname       PerlSock_gethostbyname
494#    define gethostent          PerlSock_gethostent
495#    define gethostname         PerlSock_gethostname
496#    define getnetbyaddr        PerlSock_getnetbyaddr
497#    define getnetbyname        PerlSock_getnetbyname
498#    define getnetent           PerlSock_getnetent
499#    define getpeername         PerlSock_getpeername
500#    define getprotobyname      PerlSock_getprotobyname
501#    define getprotobynumber    PerlSock_getprotobynumber
502#    define getprotoent         PerlSock_getprotoent
503#    define getservbyname       PerlSock_getservbyname
504#    define getservbyport       PerlSock_getservbyport
505#    define getservent          PerlSock_getservent
506#    define getsockname         PerlSock_getsockname
507#    define getsockopt          PerlSock_getsockopt
508#    define inet_addr           PerlSock_inet_addr
509#    define inet_ntoa           PerlSock_inet_ntoa
510#    define listen              PerlSock_listen
511#    define recv                PerlSock_recv
512#    define recvfrom            PerlSock_recvfrom
513#    define select              PerlSock_select
514#    define send                PerlSock_send
515#    define sendto              PerlSock_sendto
516#    define sethostent          PerlSock_sethostent
517#    define setnetent           PerlSock_setnetent
518#    define setprotoent         PerlSock_setprotoent
519#    define setservent          PerlSock_setservent
520#    define setsockopt          PerlSock_setsockopt
521#    define shutdown            PerlSock_shutdown
522#    define socket              PerlSock_socket
523#    define socketpair          PerlSock_socketpair
524#       endif   /* NETWARE && USE_STDIO */
525
526#    ifdef USE_SOCKETS_AS_HANDLES
527#      undef fd_set
528#      undef FD_SET
529#      undef FD_CLR
530#      undef FD_ISSET
531#      undef FD_ZERO
532#      define fd_set            Perl_fd_set
533#      define FD_SET(n,p)       PERL_FD_SET(n,p)
534#      define FD_CLR(n,p)       PERL_FD_CLR(n,p)
535#      define FD_ISSET(n,p)     PERL_FD_ISSET(n,p)
536#      define FD_ZERO(p)        PERL_FD_ZERO(p)
537#    endif      /* USE_SOCKETS_AS_HANDLES */
538
539#  endif  /* NO_XSLOCKS */
540#endif  /* PERL_IMPLICIT_SYS && !PERL_CORE */
541
542#endif /* _INC_PERL_XSUB_H */           /* include guard */
Note: See TracBrowser for help on using the repository browser.