XSUB.h

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