This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
pod/perlipc.pod patch
[perl5.git] / pod / perlguts.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlguts - Perl's Internal Functions
4
5=head1 DESCRIPTION
6
7This document attempts to describe some of the internal functions of the
8Perl executable. It is far from complete and probably contains many errors.
9Please refer any questions or comments to the author below.
10
11=head1 Datatypes
12
13Perl has three typedefs that handle Perl's three main data types:
14
15 SV Scalar Value
16 AV Array Value
17 HV Hash Value
18
d1b91892 19Each typedef has specific routines that manipulate the various data types.
a0d0e21e
LW
20
21=head2 What is an "IV"?
22
23Perl uses a special typedef IV which is large enough to hold either an
24integer or a pointer.
25
d1b91892
AD
26Perl also uses two special typedefs, I32 and I16, which will always be at
27least 32-bits and 16-bits long, respectively.
a0d0e21e 28
5fb8527f 29=head2 Working with SVs
a0d0e21e
LW
30
31An SV can be created and loaded with one command. There are four types of
32values that can be loaded: an integer value (IV), a double (NV), a string,
33(PV), and another scalar (SV).
34
35The four routines are:
36
37 SV* newSViv(IV);
38 SV* newSVnv(double);
39 SV* newSVpv(char*, int);
40 SV* newSVsv(SV*);
41
5fb8527f 42To change the value of an *already-existing* SV, there are five routines:
a0d0e21e
LW
43
44 void sv_setiv(SV*, IV);
45 void sv_setnv(SV*, double);
46 void sv_setpvn(SV*, char*, int)
47 void sv_setpv(SV*, char*);
48 void sv_setsv(SV*, SV*);
49
50Notice that you can choose to specify the length of the string to be
d1b91892 51assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to
cb1a09d0 52calculate the length by using C<sv_setpv> or by specifying 0 as the second
d1b91892 53argument to C<newSVpv>. Be warned, though, that Perl will determine the
a0d0e21e
LW
54string's length by using C<strlen>, which depends on the string terminating
55with a NUL character.
56
57To access the actual value that an SV points to, you can use the macros:
58
59 SvIV(SV*)
60 SvNV(SV*)
61 SvPV(SV*, STRLEN len)
62
63which will automatically coerce the actual scalar type into an IV, double,
64or string.
65
66In the C<SvPV> macro, the length of the string returned is placed into the
67variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
68care what the length of the data is, use the global variable C<na>. Remember,
69however, that Perl allows arbitrary strings of data that may both contain
5fb8527f 70NULs and not be terminated by a NUL.
a0d0e21e
LW
71
72If you simply want to know if the scalar value is TRUE, you can use:
73
74 SvTRUE(SV*)
75
76Although Perl will automatically grow strings for you, if you need to force
77Perl to allocate more memory for your SV, you can use the macro
78
79 SvGROW(SV*, STRLEN newlen)
80
81which will determine if more memory needs to be allocated. If so, it will
82call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
83decrease, the allocated memory of an SV.
84
85If you have an SV and want to know what kind of data Perl thinks is stored
86in it, you can use the following macros to check the type of SV you have.
87
88 SvIOK(SV*)
89 SvNOK(SV*)
90 SvPOK(SV*)
91
92You can get and set the current length of the string stored in an SV with
93the following macros:
94
95 SvCUR(SV*)
96 SvCUR_set(SV*, I32 val)
97
cb1a09d0
AD
98You can also get a pointer to the end of the string stored in the SV
99with the macro:
100
101 SvEND(SV*)
102
103But note that these last three macros are valid only if C<SvPOK()> is true.
a0d0e21e 104
d1b91892
AD
105If you want to append something to the end of string stored in an C<SV*>,
106you can use the following functions:
107
108 void sv_catpv(SV*, char*);
109 void sv_catpvn(SV*, char*, int);
110 void sv_catsv(SV*, SV*);
111
112The first function calculates the length of the string to be appended by
113using C<strlen>. In the second, you specify the length of the string
114yourself. The third function extends the string stored in the first SV
115with the string stored in the second SV. It also forces the second SV to
116be interpreted as a string.
117
a0d0e21e
LW
118If you know the name of a scalar variable, you can get a pointer to its SV
119by using the following:
120
121 SV* perl_get_sv("varname", FALSE);
122
123This returns NULL if the variable does not exist.
124
d1b91892 125If you want to know if this variable (or any other SV) is actually C<defined>,
a0d0e21e
LW
126you can call:
127
128 SvOK(SV*)
129
130The scalar C<undef> value is stored in an SV instance called C<sv_undef>. Its
131address can be used whenever an C<SV*> is needed.
132
133There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean
134TRUE and FALSE values, respectively. Like C<sv_undef>, their addresses can
135be used whenever an C<SV*> is needed.
136
137Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>.
138Take this code:
139
140 SV* sv = (SV*) 0;
141 if (I-am-to-return-a-real-value) {
142 sv = sv_2mortal(newSViv(42));
143 }
144 sv_setsv(ST(0), sv);
145
146This code tries to return a new SV (which contains the value 42) if it should
147return a real value, or undef otherwise. Instead it has returned a null
148pointer which, somewhere down the line, will cause a segmentation violation,
55497cff
PP
149bus error, or just plain weird results. Change the zero to C<&sv_undef> in
150the first line and all will be well.
a0d0e21e
LW
151
152To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
55497cff 153call is not necessary. See the section on L<Mortality>.
a0d0e21e 154
d1b91892 155=head2 What's Really Stored in an SV?
a0d0e21e
LW
156
157Recall that the usual method of determining the type of scalar you have is
d1b91892
AD
158to use C<Sv*OK> macros. Since a scalar can be both a number and a string,
159usually these macros will always return TRUE and calling the C<Sv*V>
a0d0e21e
LW
160macros will do the appropriate conversion of string to integer/double or
161integer/double to string.
162
163If you I<really> need to know if you have an integer, double, or string
164pointer in an SV, you can use the following three macros instead:
165
166 SvIOKp(SV*)
167 SvNOKp(SV*)
168 SvPOKp(SV*)
169
170These will tell you if you truly have an integer, double, or string pointer
d1b91892 171stored in your SV. The "p" stands for private.
a0d0e21e 172
d1b91892 173In general, though, it's best to just use the C<Sv*V> macros.
a0d0e21e 174
5fb8527f 175=head2 Working with AVs
a0d0e21e
LW
176
177There are two ways to create and load an AV. The first method just creates
178an empty AV:
179
180 AV* newAV();
181
5fb8527f 182The second method both creates the AV and initially populates it with SVs:
a0d0e21e
LW
183
184 AV* av_make(I32 num, SV **ptr);
185
5fb8527f
PP
186The second argument points to an array containing C<num> C<SV*>s. Once the
187AV has been created, the SVs can be destroyed, if so desired.
a0d0e21e 188
5fb8527f 189Once the AV has been created, the following operations are possible on AVs:
a0d0e21e
LW
190
191 void av_push(AV*, SV*);
192 SV* av_pop(AV*);
193 SV* av_shift(AV*);
194 void av_unshift(AV*, I32 num);
195
196These should be familiar operations, with the exception of C<av_unshift>.
197This routine adds C<num> elements at the front of the array with the C<undef>
198value. You must then use C<av_store> (described below) to assign values
199to these new elements.
200
201Here are some other functions:
202
d1b91892 203 I32 av_len(AV*); /* Returns highest index value in array */
a0d0e21e
LW
204
205 SV** av_fetch(AV*, I32 key, I32 lval);
d1b91892
AD
206 /* Fetches value at key offset, but it stores an undef value
207 at the offset if lval is non-zero */
a0d0e21e
LW
208 SV** av_store(AV*, I32 key, SV* val);
209 /* Stores val at offset key */
210
5fb8527f 211Take note that C<av_fetch> and C<av_store> return C<SV**>s, not C<SV*>s.
d1b91892 212
a0d0e21e
LW
213 void av_clear(AV*);
214 /* Clear out all elements, but leave the array */
215 void av_undef(AV*);
216 /* Undefines the array, removing all elements */
cb1a09d0
AD
217 void av_extend(AV*, I32 key);
218 /* Extend the array to a total of key elements */
a0d0e21e
LW
219
220If you know the name of an array variable, you can get a pointer to its AV
221by using the following:
222
223 AV* perl_get_av("varname", FALSE);
224
225This returns NULL if the variable does not exist.
226
5fb8527f 227=head2 Working with HVs
a0d0e21e
LW
228
229To create an HV, you use the following routine:
230
231 HV* newHV();
232
5fb8527f 233Once the HV has been created, the following operations are possible on HVs:
a0d0e21e
LW
234
235 SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
236 SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
237
238The C<klen> parameter is the length of the key being passed in. The C<val>
239argument contains the SV pointer to the scalar being stored, and C<hash> is
240the pre-computed hash value (zero if you want C<hv_store> to calculate it
241for you). The C<lval> parameter indicates whether this fetch is actually a
242part of a store operation.
243
5fb8527f 244Remember that C<hv_store> and C<hv_fetch> return C<SV**>s and not just
a0d0e21e
LW
245C<SV*>. In order to access the scalar value, you must first dereference
246the return value. However, you should check to make sure that the return
247value is not NULL before dereferencing it.
248
249These two functions check if a hash table entry exists, and deletes it.
250
251 bool hv_exists(HV*, char* key, U32 klen);
d1b91892 252 SV* hv_delete(HV*, char* key, U32 klen, I32 flags);
a0d0e21e
LW
253
254And more miscellaneous functions:
255
256 void hv_clear(HV*);
257 /* Clears all entries in hash table */
258 void hv_undef(HV*);
259 /* Undefines the hash table */
260
d1b91892
AD
261Perl keeps the actual data in linked list of structures with a typedef of HE.
262These contain the actual key and value pointers (plus extra administrative
263overhead). The key is a string pointer; the value is an C<SV*>. However,
264once you have an C<HE*>, to get the actual key and value, use the routines
265specified below.
266
a0d0e21e
LW
267 I32 hv_iterinit(HV*);
268 /* Prepares starting point to traverse hash table */
269 HE* hv_iternext(HV*);
270 /* Get the next entry, and return a pointer to a
271 structure that has both the key and value */
272 char* hv_iterkey(HE* entry, I32* retlen);
273 /* Get the key from an HE structure and also return
274 the length of the key string */
cb1a09d0 275 SV* hv_iterval(HV*, HE* entry);
a0d0e21e
LW
276 /* Return a SV pointer to the value of the HE
277 structure */
cb1a09d0 278 SV* hv_iternextsv(HV*, char** key, I32* retlen);
d1b91892
AD
279 /* This convenience routine combines hv_iternext,
280 hv_iterkey, and hv_iterval. The key and retlen
281 arguments are return values for the key and its
282 length. The value is returned in the SV* argument */
a0d0e21e
LW
283
284If you know the name of a hash variable, you can get a pointer to its HV
285by using the following:
286
287 HV* perl_get_hv("varname", FALSE);
288
289This returns NULL if the variable does not exist.
290
291The hash algorithm, for those who are interested, is:
292
293 i = klen;
294 hash = 0;
295 s = key;
296 while (i--)
297 hash = hash * 33 + *s++;
298
299=head2 References
300
d1b91892
AD
301References are a special type of scalar that point to other data types
302(including references).
a0d0e21e
LW
303
304To create a reference, use the following command:
305
cb1a09d0 306 SV* newRV((SV*) thing);
a0d0e21e 307
d1b91892
AD
308The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. Once
309you have a reference, you can use the following macro to dereference the
310reference:
a0d0e21e
LW
311
312 SvRV(SV*)
313
314then call the appropriate routines, casting the returned C<SV*> to either an
d1b91892 315C<AV*> or C<HV*>, if required.
a0d0e21e 316
d1b91892 317To determine if an SV is a reference, you can use the following macro:
a0d0e21e
LW
318
319 SvROK(SV*)
320
d1b91892
AD
321To actually discover what the reference refers to, you must use the following
322macro and then check the value returned.
323
324 SvTYPE(SvRV(SV*))
325
326The most useful types that will be returned are:
327
328 SVt_IV Scalar
329 SVt_NV Scalar
330 SVt_PV Scalar
331 SVt_PVAV Array
332 SVt_PVHV Hash
333 SVt_PVCV Code
334 SVt_PVMG Blessed Scalar
335
cb1a09d0
AD
336=head2 Blessed References and Class Objects
337
338References are also used to support object-oriented programming. In the
339OO lexicon, an object is simply a reference that has been blessed into a
340package (or class). Once blessed, the programmer may now use the reference
341to access the various methods in the class.
342
343A reference can be blessed into a package with the following function:
344
345 SV* sv_bless(SV* sv, HV* stash);
346
347The C<sv> argument must be a reference. The C<stash> argument specifies
55497cff 348which class the reference will belong to. See the section on L<Stashes>
cb1a09d0
AD
349for information on converting class names into stashes.
350
351/* Still under construction */
352
353Upgrades rv to reference if not already one. Creates new SV for rv to
354point to.
355If classname is non-null, the SV is blessed into the specified class.
356SV is returned.
357
358 SV* newSVrv(SV* rv, char* classname);
359
360Copies integer or double into an SV whose reference is rv. SV is blessed
361if classname is non-null.
362
363 SV* sv_setref_iv(SV* rv, char* classname, IV iv);
364 SV* sv_setref_nv(SV* rv, char* classname, NV iv);
365
366Copies pointer (I<not a string!>) into an SV whose reference is rv.
367SV is blessed if classname is non-null.
368
369 SV* sv_setref_pv(SV* rv, char* classname, PV iv);
370
371Copies string into an SV whose reference is rv.
372Set length to 0 to let Perl calculate the string length.
373SV is blessed if classname is non-null.
374
375 SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
376
377 int sv_isa(SV* sv, char* name);
378 int sv_isobject(SV* sv);
379
380=head1 Creating New Variables
381
382To create a new Perl variable, which can be accessed from your Perl script,
383use the following routines, depending on the variable type.
384
385 SV* perl_get_sv("varname", TRUE);
386 AV* perl_get_av("varname", TRUE);
387 HV* perl_get_hv("varname", TRUE);
388
389Notice the use of TRUE as the second parameter. The new variable can now
390be set, using the routines appropriate to the data type.
391
392There are additional bits that may be OR'ed with the TRUE argument to enable
393certain extra features. Those bits are:
394
395 0x02 Marks the variable as multiply defined, thus preventing the
5fb8527f 396 "Identifier <varname> used only once: possible typo" warning.
cb1a09d0
AD
397 0x04 Issues a "Had to create <varname> unexpectedly" warning if
398 the variable didn't actually exist. This is useful if
399 you expected the variable to already exist and want to propagate
400 this warning back to the user.
401
402If the C<varname> argument does not contain a package specifier, it is
403created in the current package.
404
5fb8527f 405=head1 XSUBs and the Argument Stack
a0d0e21e
LW
406
407The XSUB mechanism is a simple way for Perl programs to access C subroutines.
408An XSUB routine will have a stack that contains the arguments from the Perl
409program, and a way to map from the Perl data structures to a C equivalent.
410
411The stack arguments are accessible through the C<ST(n)> macro, which returns
412the C<n>'th stack argument. Argument 0 is the first argument passed in the
413Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
414an C<SV*> is used.
415
416Most of the time, output from the C routine can be handled through use of
417the RETVAL and OUTPUT directives. However, there are some cases where the
418argument stack is not already long enough to handle all the return values.
419An example is the POSIX tzname() call, which takes no arguments, but returns
420two, the local timezone's standard and summer time abbreviations.
421
422To handle this situation, the PPCODE directive is used and the stack is
423extended using the macro:
424
425 EXTEND(sp, num);
426
427where C<sp> is the stack pointer, and C<num> is the number of elements the
428stack should be extended by.
429
430Now that there is room on the stack, values can be pushed on it using the
5fb8527f 431macros to push IVs, doubles, strings, and SV pointers respectively:
a0d0e21e
LW
432
433 PUSHi(IV)
434 PUSHn(double)
435 PUSHp(char*, I32)
436 PUSHs(SV*)
437
438And now the Perl program calling C<tzname>, the two values will be assigned
439as in:
440
441 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
442
443An alternate (and possibly simpler) method to pushing values on the stack is
444to use the macros:
445
446 XPUSHi(IV)
447 XPUSHn(double)
448 XPUSHp(char*, I32)
449 XPUSHs(SV*)
450
55497cff
PP
451These macros automatically adjust the stack for you, if needed. Thus, you
452do not need to call C<EXTEND> to extend the stack.
a0d0e21e 453
8e07c86e 454For more information, consult L<perlxs>.
d1b91892 455
55497cff
PP
456=head1 Localizing Changes
457
458Perl has a very handy construction
459
460 {
461 local $var = 2;
462 ...
463 }
464
465This construction is I<approximately> equivalent to
466
467 {
468 my $oldvar = $var;
469 $var = 2;
470 ...
471 $var = $oldvar;
472 }
473
474The biggest difference is that the first construction would would
475reinstate the initial value of $var, irrespective of how control exits
476the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
477more efficient as well.
478
479There is a way to achieve a similar task from C via Perl API: create a
480I<pseudo-block>, and arrange for some changes to be automatically
481undone at the end of it, either explicit, or via a non-local exit (via
482die()). A I<block>-like construct is created by a pair of
483C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a
484Scalar">). Such a construct may be created specially for some
485important localized task, or an existing one (like boundaries of
486enclosing Perl subroutine/block, or an existing pair for freeing TMPs)
487may be used. (In the second case the overhead of additional
488localization must be almost negligible.) Note that any XSUB is
489automatically enclosed in an C<ENTER>/C<LEAVE> pair.
490
491Inside such a I<pseudo-block> the following service is available:
492
493=over
494
495=item C<SAVEINT(int i)>
496
497=item C<SAVEIV(IV i)>
498
499=item C<SAVEI16(I16 i)>
500
501=item C<SAVEI32(I32 i)>
502
503=item C<SAVELONG(long i)>
504
505These macros arrange things to restore the value of integer variable
506C<i> at the end of enclosing I<pseudo-block>.
507
508=item C<SAVESPTR(p)>
509
510=item C<SAVEPPTR(s)>
511
512These macros arrange things to restore the value of pointers C<s> and
513C<p>. C<p> must be a pointer of a type which survives conversion to
514C<SV*> and back, C<s> should be able to survive conversion to C<char*>
515and back.
516
517=item C<SAVEFREESV(SV *sv)>
518
519The refcount of C<sv> would be decremented at the end of
520I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
521used instead.
522
523=item C<SAVEFREEOP(OP *op)>
524
525The C<OP *> is op_free()ed at the end of I<pseudo-block>.
526
527=item C<SAVEFREEPV(p)>
528
529The chunk of memory which is pointed to by C<p> is Safefree()ed at the
530end of I<pseudo-block>.
531
532=item C<SAVECLEARSV(SV *sv)>
533
534Clears a slot in the current scratchpad which corresponds to C<sv> at
535the end of I<pseudo-block>.
536
537=item C<SAVEDELETE(HV *hv, char *key, I32 length)>
a0d0e21e 538
55497cff
PP
539The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
540string pointed to by C<key> is Safefree()ed. If one has a I<key> in
541short-lived storage, the corresponding string may be reallocated like
542this:
a0d0e21e 543
55497cff 544 SAVEDELETE(defstash, savepv(tmpbuf), strlen(tmpbuf));
d1b91892 545
55497cff
PP
546=item C<SAVEDESTRUCTOR(f,p)>
547
548At the end of I<pseudo-block> the function C<f> is called with the
549only argument (of type C<void*>) C<p>.
550
551=item C<SAVESTACK_POS()>
552
553The current offset on the Perl internal stack (cf. C<SP>) is restored
554at the end of I<pseudo-block>.
555
556=back
557
558The following API list contains functions, thus one needs to
559provide pointers to the modifiable data explicitly (either C pointers,
560or Perlish C<GV *>s):
561
562=over
563
564=item C<SV* save_scalar(GV *gv)>
565
566Equivalent to Perl code C<local $gv>.
567
568=item C<AV* save_ary(GV *gv)>
569
570=item C<HV* save_hash(GV *gv)>
571
572Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
573
574=item C<void save_item(SV *item)>
575
576Duplicates the current value of C<SV>, on the exit from the current
577C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
578using the stored value.
579
580=item C<void save_list(SV **sarg, I32 maxsarg)>
581
582A variant of C<save_item> which takes multiple arguments via an array
583C<sarg> of C<SV*> of length C<maxsarg>.
584
585=item C<SV* save_svref(SV **sptr)>
586
587Similar to C<save_scalar>, but will reinstate a C<SV *>.
588
589=item C<void save_aptr(AV **aptr)>
590
591=item C<void save_hptr(HV **hptr)>
592
593Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
594
595=item C<void save_nogv(GV *gv)>
596
597Will postpone destruction of a I<stub> glob.
598
599=back
600
601=head1 Mortality
a0d0e21e 602
55497cff
PP
603Perl uses an reference count-driven garbage collection mechanism. SV's,
604AV's, or HV's (xV for short in the following) start their life with a
605reference count of 1. If the reference count of an xV ever drops to 0,
606then they will be destroyed and their memory made available for reuse.
607
608This normally doesn't happen at the Perl level unless a variable is
609undef'ed. At the internal level, however, reference counts can be
610manipulated with the following macros:
611
612 int SvREFCNT(SV* sv);
613 void SvREFCNT_inc(SV* sv);
614 void SvREFCNT_dec(SV* sv);
615
616However, there is one other function which manipulates the reference
617count of its argument. The C<newRV> function, as you should recall,
618creates a reference to the specified argument. As a side effect, it
619increments the argument's reference count, which is ok in most
620circumstances. But imagine you want to return a reference from an XS
621function. You create a new SV which initially has a reference count
622of 1. Then you call C<newRV>, passing the just-created SV. This returns
623the reference as a new SV, but the reference count of the SV you passed
624to C<newRV> has been incremented to 2. Now you return the reference and
625forget about the SV. But Perl hasn't! Whenever the returned reference
626is destroyed, the reference count of the original SV is decreased to 1
627and nothing happens. The SV will hang around without any way to access
628it until Perl itself terminates. This is a memory leak.
629
630The correct procedure, then, is to call C<SvREFCNT_dec> on the SV after
631C<newRV> has returned. Then, if and when the reference is destroyed,
632the reference count of the SV will go to 0 and also be destroyed, stopping
633any memory leak.
634
635There are some convenience functions available that can help with this
636process. These functions introduce the concept of "mortality". An xV
637that is mortal has had its reference count marked to be decremented,
638but not actually decremented, until the "current context" is left.
639Generally the "current context" means a single Perl statement, such as
640a call to an XSUB function.
641
642"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
643However, if you mortalize a variable twice, the reference count will
644later be decremented twice.
645
646You should be careful about creating mortal variables. Strange things
647can happen if you make the same value mortal within multiple contexts,
648or if you make a variable mortal multiple times. Doing the latter can
649cause a variable to become invalid prematurely.
a0d0e21e
LW
650
651To create a mortal variable, use the functions:
652
653 SV* sv_newmortal()
654 SV* sv_2mortal(SV*)
655 SV* sv_mortalcopy(SV*)
656
657The first call creates a mortal SV, the second converts an existing SV to
bbce6d69
PP
658a mortal SV, the third creates a mortal copy of an existing SV (possibly
659destroying it in the process).
a0d0e21e 660
5fb8527f 661The mortal routines are not just for SVs -- AVs and HVs can be made mortal
a0d0e21e
LW
662by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or
663C<sv_mortalcopy> routines.
664
55497cff 665I<From Ilya:>
d1b91892
AD
666Beware that the sv_2mortal() call is eventually equivalent to
667svREFCNT_dec(). A value can happily be mortal in two different contexts,
668and it will be svREFCNT_dec()ed twice, once on exit from these
669contexts. It can also be mortal twice in the same context. This means
670that you should be very careful to make a value mortal exactly as many
671times as it is needed. The value that go to the Perl stack I<should>
672be mortal.
a0d0e21e 673
a0d0e21e 674
cb1a09d0 675=head1 Stashes
a0d0e21e
LW
676
677A stash is a hash table (associative array) that contains all of the
678different objects that are contained within a package. Each key of the
d1b91892
AD
679stash is a symbol name (shared by all the different types of objects
680that have the same name), and each value in the hash table is called a
681GV (for Glob Value). This GV in turn contains references to the various
682objects of that name, including (but not limited to) the following:
cb1a09d0 683
a0d0e21e
LW
684 Scalar Value
685 Array Value
686 Hash Value
687 File Handle
688 Directory Handle
689 Format
690 Subroutine
691
d1b91892
AD
692Perl stores various stashes in a separate GV structure (for global
693variable) but represents them with an HV structure. The keys in this
5fb8527f 694larger GV are the various package names; the values are the C<GV*>s
d1b91892
AD
695which are stashes. It may help to think of a stash purely as an HV,
696and that the term "GV" means the global variable hash.
a0d0e21e 697
d1b91892 698To get the stash pointer for a particular package, use the function:
a0d0e21e
LW
699
700 HV* gv_stashpv(char* name, I32 create)
701 HV* gv_stashsv(SV*, I32 create)
702
703The first function takes a literal string, the second uses the string stored
d1b91892 704in the SV. Remember that a stash is just a hash table, so you get back an
cb1a09d0 705C<HV*>. The C<create> flag will create a new package if it is set.
a0d0e21e
LW
706
707The name that C<gv_stash*v> wants is the name of the package whose symbol table
708you want. The default package is called C<main>. If you have multiply nested
d1b91892
AD
709packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
710language itself.
a0d0e21e
LW
711
712Alternately, if you have an SV that is a blessed reference, you can find
713out the stash pointer by using:
714
715 HV* SvSTASH(SvRV(SV*));
716
717then use the following to get the package name itself:
718
719 char* HvNAME(HV* stash);
720
721If you need to return a blessed value to your Perl script, you can use the
722following function:
723
724 SV* sv_bless(SV*, HV* stash)
725
726where the first argument, an C<SV*>, must be a reference, and the second
727argument is a stash. The returned C<SV*> can now be used in the same way
728as any other SV.
729
d1b91892
AD
730For more information on references and blessings, consult L<perlref>.
731
a0d0e21e
LW
732=head1 Magic
733
d1b91892
AD
734[This section still under construction. Ignore everything here. Post no
735bills. Everything not permitted is forbidden.]
736
d1b91892
AD
737Any SV may be magical, that is, it has special features that a normal
738SV does not have. These features are stored in the SV structure in a
5fb8527f 739linked list of C<struct magic>s, typedef'ed to C<MAGIC>.
d1b91892
AD
740
741 struct magic {
742 MAGIC* mg_moremagic;
743 MGVTBL* mg_virtual;
744 U16 mg_private;
745 char mg_type;
746 U8 mg_flags;
747 SV* mg_obj;
748 char* mg_ptr;
749 I32 mg_len;
750 };
751
752Note this is current as of patchlevel 0, and could change at any time.
753
754=head2 Assigning Magic
755
756Perl adds magic to an SV using the sv_magic function:
757
758 void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
759
760The C<sv> argument is a pointer to the SV that is to acquire a new magical
761feature.
762
763If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
764set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
765it to the beginning of the linked list of magical features. Any prior
766entry of the same type of magic is deleted. Note that this can be
5fb8527f 767overridden, and multiple instances of the same type of magic can be
d1b91892
AD
768associated with an SV.
769
770The C<name> and C<namlem> arguments are used to associate a string with
771the magic, typically the name of a variable. C<namlem> is stored in the
55497cff 772C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
d1b91892
AD
773copy of the name is stored in C<mg_ptr> field.
774
775The sv_magic function uses C<how> to determine which, if any, predefined
776"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
cb1a09d0
AD
777See the "Magic Virtual Table" section below. The C<how> argument is also
778stored in the C<mg_type> field.
d1b91892
AD
779
780The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
781structure. If it is not the same as the C<sv> argument, the reference
782count of the C<obj> object is incremented. If it is the same, or if
783the C<how> argument is "#", or if it is a null pointer, then C<obj> is
784merely stored, without the reference count being incremented.
785
cb1a09d0
AD
786There is also a function to add magic to an C<HV>:
787
788 void hv_magic(HV *hv, GV *gv, int how);
789
790This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
791
792To remove the magic from an SV, call the function sv_unmagic:
793
794 void sv_unmagic(SV *sv, int type);
795
796The C<type> argument should be equal to the C<how> value when the C<SV>
797was initially made magical.
798
d1b91892
AD
799=head2 Magic Virtual Tables
800
801The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
802C<MGVTBL>, which is a structure of function pointers and stands for
803"Magic Virtual Table" to handle the various operations that might be
804applied to that variable.
805
806The C<MGVTBL> has five pointers to the following routine types:
807
808 int (*svt_get)(SV* sv, MAGIC* mg);
809 int (*svt_set)(SV* sv, MAGIC* mg);
810 U32 (*svt_len)(SV* sv, MAGIC* mg);
811 int (*svt_clear)(SV* sv, MAGIC* mg);
812 int (*svt_free)(SV* sv, MAGIC* mg);
813
814This MGVTBL structure is set at compile-time in C<perl.h> and there are
815currently 19 types (or 21 with overloading turned on). These different
816structures contain pointers to various routines that perform additional
817actions depending on which function is being called.
818
819 Function pointer Action taken
820 ---------------- ------------
821 svt_get Do something after the value of the SV is retrieved.
822 svt_set Do something after the SV is assigned a value.
823 svt_len Report on the SV's length.
824 svt_clear Clear something the SV represents.
825 svt_free Free any extra storage associated with the SV.
826
827For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
828to an C<mg_type> of '\0') contains:
829
830 { magic_get, magic_set, magic_len, 0, 0 }
831
832Thus, when an SV is determined to be magical and of type '\0', if a get
833operation is being performed, the routine C<magic_get> is called. All
834the various routines for the various magical types begin with C<magic_>.
835
836The current kinds of Magic Virtual Tables are:
837
838 mg_type MGVTBL Type of magicalness
839 ------- ------ -------------------
840 \0 vtbl_sv Regexp???
841 A vtbl_amagic Operator Overloading
842 a vtbl_amagicelem Operator Overloading
843 c 0 Used in Operator Overloading
844 B vtbl_bm Boyer-Moore???
845 E vtbl_env %ENV hash
846 e vtbl_envelem %ENV hash element
847 g vtbl_mglob Regexp /g flag???
848 I vtbl_isa @ISA array
849 i vtbl_isaelem @ISA array element
850 L 0 (but sets RMAGICAL) Perl Module/Debugger???
851 l vtbl_dbline Debugger?
bbce6d69 852 o vtbl_collxfrm Locale Collation
d1b91892
AD
853 P vtbl_pack Tied Array or Hash
854 p vtbl_packelem Tied Array or Hash element
855 q vtbl_packelem Tied Scalar or Handle
856 S vtbl_sig Signal Hash
857 s vtbl_sigelem Signal Hash element
858 t vtbl_taint Taintedness
859 U vtbl_uvar ???
860 v vtbl_vec Vector
861 x vtbl_substr Substring???
862 * vtbl_glob GV???
863 # vtbl_arylen Array Length
864 . vtbl_pos $. scalar variable
865 ~ Reserved for extensions, but multiple extensions may clash
866
867When an upper-case and lower-case letter both exist in the table, then the
868upper-case letter is used to represent some kind of composite type (a list
869or a hash), and the lower-case letter is used to represent an element of
870that composite type.
871
872=head2 Finding Magic
873
874 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
875
876This routine returns a pointer to the C<MAGIC> structure stored in the SV.
877If the SV does not have that magical feature, C<NULL> is returned. Also,
878if the SV is not of type SVt_PVMG, Perl may core-dump.
879
880 int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
881
882This routine checks to see what types of magic C<sv> has. If the mg_type
883field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
884the mg_type field is changed to be the lower-case letter.
a0d0e21e 885
5fb8527f 886=head1 Double-Typed SVs
a0d0e21e
LW
887
888Scalar variables normally contain only one type of value, an integer,
889double, pointer, or reference. Perl will automatically convert the
890actual scalar data from the stored type into the requested type.
891
892Some scalar variables contain more than one type of scalar data. For
893example, the variable C<$!> contains either the numeric value of C<errno>
d1b91892 894or its string equivalent from either C<strerror> or C<sys_errlist[]>.
a0d0e21e
LW
895
896To force multiple data values into an SV, you must do two things: use the
897C<sv_set*v> routines to add the additional scalar type, then set a flag
898so that Perl will believe it contains more than one type of data. The
899four macros to set the flags are:
900
901 SvIOK_on
902 SvNOK_on
903 SvPOK_on
904 SvROK_on
905
906The particular macro you must use depends on which C<sv_set*v> routine
907you called first. This is because every C<sv_set*v> routine turns on
908only the bit for the particular type of data being set, and turns off
909all the rest.
910
911For example, to create a new Perl variable called "dberror" that contains
912both the numeric and descriptive string error values, you could use the
913following code:
914
915 extern int dberror;
916 extern char *dberror_list;
917
918 SV* sv = perl_get_sv("dberror", TRUE);
919 sv_setiv(sv, (IV) dberror);
920 sv_setpv(sv, dberror_list[dberror]);
921 SvIOK_on(sv);
922
923If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
924macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
925
926=head1 Calling Perl Routines from within C Programs
927
928There are four routines that can be used to call a Perl subroutine from
929within a C program. These four are:
930
931 I32 perl_call_sv(SV*, I32);
932 I32 perl_call_pv(char*, I32);
933 I32 perl_call_method(char*, I32);
934 I32 perl_call_argv(char*, I32, register char**);
935
d1b91892
AD
936The routine most often used is C<perl_call_sv>. The C<SV*> argument
937contains either the name of the Perl subroutine to be called, or a
938reference to the subroutine. The second argument consists of flags
939that control the context in which the subroutine is called, whether
940or not the subroutine is being passed arguments, how errors should be
941trapped, and how to treat return values.
a0d0e21e
LW
942
943All four routines return the number of arguments that the subroutine returned
944on the Perl stack.
945
d1b91892
AD
946When using any of these routines (except C<perl_call_argv>), the programmer
947must manipulate the Perl stack. These include the following macros and
948functions:
a0d0e21e
LW
949
950 dSP
951 PUSHMARK()
952 PUTBACK
953 SPAGAIN
954 ENTER
955 SAVETMPS
956 FREETMPS
957 LEAVE
958 XPUSH*()
cb1a09d0 959 POP*()
a0d0e21e
LW
960
961For more information, consult L<perlcall>.
962
963=head1 Memory Allocation
964
d1b91892
AD
965It is strongly suggested that you use the version of malloc that is distributed
966with Perl. It keeps pools of various sizes of unallocated memory in order to
967more quickly satisfy allocation requests.
968However, on some platforms, it may cause spurious malloc or free errors.
969
970 New(x, pointer, number, type);
971 Newc(x, pointer, number, type, cast);
972 Newz(x, pointer, number, type);
973
974These three macros are used to initially allocate memory. The first argument
975C<x> was a "magic cookie" that was used to keep track of who called the macro,
976to help when debugging memory problems. However, the current code makes no
977use of this feature (Larry has switched to using a run-time memory checker),
978so this argument can be any number.
979
980The second argument C<pointer> will point to the newly allocated memory.
981The third and fourth arguments C<number> and C<type> specify how many of
982the specified type of data structure should be allocated. The argument
983C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
984should be used if the C<pointer> argument is different from the C<type>
985argument.
986
987Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
988to zero out all the newly allocated memory.
989
990 Renew(pointer, number, type);
991 Renewc(pointer, number, type, cast);
992 Safefree(pointer)
993
994These three macros are used to change a memory buffer size or to free a
995piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
996match those of C<New> and C<Newc> with the exception of not needing the
997"magic cookie" argument.
998
999 Move(source, dest, number, type);
1000 Copy(source, dest, number, type);
1001 Zero(dest, number, type);
1002
1003These three macros are used to move, copy, or zero out previously allocated
1004memory. The C<source> and C<dest> arguments point to the source and
1005destination starting points. Perl will move, copy, or zero out C<number>
1006instances of the size of the C<type> data structure (using the C<sizeof>
1007function).
a0d0e21e 1008
ce3d39e2
IZ
1009=head1 Scratchpads
1010
1011=head2 Putting a C value on Perl stack
1012
1013A lot of opcodes (this is an elementary operation in the internal perl
1014stack machine) put an SV* on the stack. However, as an optimization
1015the corresponding SV is (usually) not recreated each time. The opcodes
1016reuse specially assigned SVs (I<target>s) which are (as a corollary)
1017not constantly freed/created.
1018
1019Each of the targets is created only once (but see
1020L<Scratchpads and recursion> below), and when an opcode needs to put
1021an integer, a double, or a string on stack, it just sets the
1022corresponding parts of its I<target> and puts the I<target> on stack.
1023
1024The macro to put this target on stack is C<PUSHTARG>, and it is
1025directly used in some opcodes, as well as indirectly in zillions of
1026others, which use it via C<(X)PUSH[pni]>.
1027
1028=head2 Scratchpads
1029
1030The question remains on when the SVs which are I<target>s for opcodes
1031are created. The answer is that they are created when the current unit
1032- a subroutine or a file (for opcodes for statements outside of
1033subroutines) - is compiled. During this time a special anonymous Perl
1034array is created, which is called a scratchpad for the current
1035unit.
1036
1037Scratchpad keeps SVs which are lexicals for the current unit and are
1038targets for opcodes. One can deduce that an SV lives on a scratchpad
1039by looking on its flags: lexicals have C<SVs_PADMY> set, and
1040I<target>s have C<SVs_PADTMP> set.
1041
1042The correspondence between OPs and I<target>s is not 1-to-1. Different
1043OPs in the compile tree of the unit can use the same target, if this
1044would not conflict with the expected life of the temporary.
1045
1046=head2 Scratchpads and recursions
1047
1048In fact it is not 100% true that a compiled unit contains a pointer to
1049the scratchpad AV. In fact it contains a pointer to an AV of
1050(initially) one element, and this element is the scratchpad AV. Why do
1051we need an extra level of indirection?
1052
1053The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1054these can create several execution pointers going into the same
1055subroutine. For the subroutine-child not write over the temporaries
1056for the subroutine-parent (lifespan of which covers the call to the
1057child), the parent and the child should have different
1058scratchpads. (I<And> the lexicals should be separate anyway!)
1059
1060So each subroutine is born with an array of scratchpads (of length
10611). On each entry to the subroutine it is checked that the current
1062depth of the recursion is not more than the length of this array, and
1063if it is, new scratchpad is created and pushed into the array.
1064
1065The I<target>s on this scratchpad are C<undef>s, but they are already
1066marked with correct flags.
1067
cb1a09d0 1068=head1 API LISTING
a0d0e21e 1069
cb1a09d0
AD
1070This is a listing of functions, macros, flags, and variables that may be
1071useful to extension writers or that may be found while reading other
1072extensions.
a0d0e21e 1073
cb1a09d0 1074=over 8
a0d0e21e 1075
cb1a09d0
AD
1076=item AvFILL
1077
1078See C<av_len>.
1079
1080=item av_clear
1081
1082Clears an array, making it empty.
1083
1084 void av_clear _((AV* ar));
1085
1086=item av_extend
1087
1088Pre-extend an array. The C<key> is the index to which the array should be
1089extended.
1090
1091 void av_extend _((AV* ar, I32 key));
1092
1093=item av_fetch
1094
1095Returns the SV at the specified index in the array. The C<key> is the
1096index. If C<lval> is set then the fetch will be part of a store. Check
1097that the return value is non-null before dereferencing it to a C<SV*>.
1098
1099 SV** av_fetch _((AV* ar, I32 key, I32 lval));
1100
1101=item av_len
1102
1103Returns the highest index in the array. Returns -1 if the array is empty.
1104
1105 I32 av_len _((AV* ar));
1106
1107=item av_make
1108
5fb8527f
PP
1109Creates a new AV and populates it with a list of SVs. The SVs are copied
1110into the array, so they may be freed after the call to av_make. The new AV
1111will have a refcount of 1.
cb1a09d0
AD
1112
1113 AV* av_make _((I32 size, SV** svp));
1114
1115=item av_pop
1116
1117Pops an SV off the end of the array. Returns C<&sv_undef> if the array is
1118empty.
1119
1120 SV* av_pop _((AV* ar));
1121
1122=item av_push
1123
5fb8527f
PP
1124Pushes an SV onto the end of the array. The array will grow automatically
1125to accommodate the addition.
cb1a09d0
AD
1126
1127 void av_push _((AV* ar, SV* val));
1128
1129=item av_shift
1130
1131Shifts an SV off the beginning of the array.
1132
1133 SV* av_shift _((AV* ar));
1134
1135=item av_store
1136
1137Stores an SV in an array. The array index is specified as C<key>. The
1138return value will be null if the operation failed, otherwise it can be
1139dereferenced to get the original C<SV*>.
1140
1141 SV** av_store _((AV* ar, I32 key, SV* val));
1142
1143=item av_undef
1144
1145Undefines the array.
1146
1147 void av_undef _((AV* ar));
1148
1149=item av_unshift
1150
5fb8527f
PP
1151Unshift an SV onto the beginning of the array. The array will grow
1152automatically to accommodate the addition.
cb1a09d0
AD
1153
1154 void av_unshift _((AV* ar, I32 num));
1155
1156=item CLASS
1157
1158Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
5fb8527f
PP
1159constructor. This is always a C<char*>. See C<THIS> and
1160L<perlxs/"Using XS With C++">.
cb1a09d0
AD
1161
1162=item Copy
1163
1164The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
1165source, C<d> is the destination, C<n> is the number of items, and C<t> is
1166the type.
1167
1168 (void) Copy( s, d, n, t );
1169
1170=item croak
1171
1172This is the XSUB-writer's interface to Perl's C<die> function. Use this
1173function the same way you use the C C<printf> function. See C<warn>.
1174
1175=item CvSTASH
1176
1177Returns the stash of the CV.
1178
1179 HV * CvSTASH( SV* sv )
1180
1181=item DBsingle
1182
1183When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1184boolean which indicates whether subs are being single-stepped.
5fb8527f
PP
1185Single-stepping is automatically turned on after every step. This is the C
1186variable which corresponds to Perl's $DB::single variable. See C<DBsub>.
cb1a09d0
AD
1187
1188=item DBsub
1189
1190When Perl is run in debugging mode, with the B<-d> switch, this GV contains
5fb8527f
PP
1191the SV which holds the name of the sub being debugged. This is the C
1192variable which corresponds to Perl's $DB::sub variable. See C<DBsingle>.
cb1a09d0
AD
1193The sub name can be found by
1194
1195 SvPV( GvSV( DBsub ), na )
1196
5fb8527f
PP
1197=item DBtrace
1198
1199Trace variable used when Perl is run in debugging mode, with the B<-d>
1200switch. This is the C variable which corresponds to Perl's $DB::trace
1201variable. See C<DBsingle>.
1202
cb1a09d0
AD
1203=item dMARK
1204
5fb8527f
PP
1205Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1206C<dORIGMARK>.
cb1a09d0
AD
1207
1208=item dORIGMARK
1209
1210Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1211
5fb8527f
PP
1212=item dowarn
1213
1214The C variable which corresponds to Perl's $^W warning variable.
1215
cb1a09d0
AD
1216=item dSP
1217
5fb8527f 1218Declares a stack pointer variable, C<sp>, for the XSUB. See C<SP>.
cb1a09d0
AD
1219
1220=item dXSARGS
1221
1222Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
1223usually handled automatically by C<xsubpp>. Declares the C<items> variable
1224to indicate the number of items on the stack.
1225
5fb8527f
PP
1226=item dXSI32
1227
1228Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1229handled automatically by C<xsubpp>.
1230
1231=item dXSI32
1232
1233Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1234handled automatically by C<xsubpp>.
1235
cb1a09d0
AD
1236=item ENTER
1237
1238Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
1239
1240 ENTER;
1241
1242=item EXTEND
1243
1244Used to extend the argument stack for an XSUB's return values.
1245
1246 EXTEND( sp, int x );
1247
1248=item FREETMPS
1249
1250Closing bracket for temporaries on a callback. See C<SAVETMPS> and
1251L<perlcall>.
1252
1253 FREETMPS;
1254
1255=item G_ARRAY
1256
1257Used to indicate array context. See C<GIMME> and L<perlcall>.
1258
1259=item G_DISCARD
1260
1261Indicates that arguments returned from a callback should be discarded. See
1262L<perlcall>.
1263
1264=item G_EVAL
1265
1266Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
1267
1268=item GIMME
1269
1270The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_SCALAR> or
1271C<G_ARRAY> for scalar or array context.
1272
1273=item G_NOARGS
1274
1275Indicates that no arguments are being sent to a callback. See L<perlcall>.
1276
1277=item G_SCALAR
1278
1279Used to indicate scalar context. See C<GIMME> and L<perlcall>.
1280
1281=item gv_stashpv
1282
1283Returns a pointer to the stash for a specified package. If C<create> is set
1284then the package will be created if it does not already exist. If C<create>
1285is not set and the package does not exist then NULL is returned.
1286
1287 HV* gv_stashpv _((char* name, I32 create));
1288
1289=item gv_stashsv
1290
1291Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
1292
1293 HV* gv_stashsv _((SV* sv, I32 create));
1294
1295=item GvSV
1296
1297Return the SV from the GV.
1298
1299=item he_free
1300
1301Releases a hash entry from an iterator. See C<hv_iternext>.
1302
1303=item hv_clear
1304
1305Clears a hash, making it empty.
1306
1307 void hv_clear _((HV* tb));
1308
1309=item hv_delete
1310
1311Deletes a key/value pair in the hash. The value SV is removed from the hash
5fb8527f 1312and returned to the caller. The C<klen> is the length of the key. The
cb1a09d0
AD
1313C<flags> value will normally be zero; if set to G_DISCARD then null will be
1314returned.
1315
1316 SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
1317
1318=item hv_exists
1319
1320Returns a boolean indicating whether the specified hash key exists. The
5fb8527f 1321C<klen> is the length of the key.
cb1a09d0
AD
1322
1323 bool hv_exists _((HV* tb, char* key, U32 klen));
1324
1325=item hv_fetch
1326
1327Returns the SV which corresponds to the specified key in the hash. The
5fb8527f 1328C<klen> is the length of the key. If C<lval> is set then the fetch will be
cb1a09d0
AD
1329part of a store. Check that the return value is non-null before
1330dereferencing it to a C<SV*>.
1331
1332 SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
1333
1334=item hv_iterinit
1335
1336Prepares a starting point to traverse a hash table.
1337
1338 I32 hv_iterinit _((HV* tb));
1339
1340=item hv_iterkey
1341
1342Returns the key from the current position of the hash iterator. See
1343C<hv_iterinit>.
1344
1345 char* hv_iterkey _((HE* entry, I32* retlen));
1346
1347=item hv_iternext
1348
1349Returns entries from a hash iterator. See C<hv_iterinit>.
1350
1351 HE* hv_iternext _((HV* tb));
1352
1353=item hv_iternextsv
1354
1355Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1356operation.
1357
1358 SV * hv_iternextsv _((HV* hv, char** key, I32* retlen));
1359
1360=item hv_iterval
1361
1362Returns the value from the current position of the hash iterator. See
1363C<hv_iterkey>.
1364
1365 SV* hv_iterval _((HV* tb, HE* entry));
1366
1367=item hv_magic
1368
1369Adds magic to a hash. See C<sv_magic>.
1370
1371 void hv_magic _((HV* hv, GV* gv, int how));
1372
1373=item HvNAME
1374
1375Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
1376
1377 char *HvNAME (HV* stash)
1378
1379=item hv_store
1380
1381Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1382the length of the key. The C<hash> parameter is the pre-computed hash
1383value; if it is zero then Perl will compute it. The return value will be
1384null if the operation failed, otherwise it can be dereferenced to get the
1385original C<SV*>.
1386
1387 SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
1388
1389=item hv_undef
1390
1391Undefines the hash.
1392
1393 void hv_undef _((HV* tb));
1394
1395=item isALNUM
1396
1397Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
5fb8527f 1398character.
cb1a09d0
AD
1399
1400 int isALNUM (char c)
1401
1402=item isALPHA
1403
5fb8527f 1404Returns a boolean indicating whether the C C<char> is an ascii alphabetic
cb1a09d0
AD
1405character.
1406
1407 int isALPHA (char c)
1408
1409=item isDIGIT
1410
1411Returns a boolean indicating whether the C C<char> is an ascii digit.
1412
1413 int isDIGIT (char c)
1414
1415=item isLOWER
1416
1417Returns a boolean indicating whether the C C<char> is a lowercase character.
1418
1419 int isLOWER (char c)
1420
1421=item isSPACE
1422
1423Returns a boolean indicating whether the C C<char> is whitespace.
1424
1425 int isSPACE (char c)
1426
1427=item isUPPER
1428
1429Returns a boolean indicating whether the C C<char> is an uppercase character.
1430
1431 int isUPPER (char c)
1432
1433=item items
1434
1435Variable which is setup by C<xsubpp> to indicate the number of items on the
5fb8527f
PP
1436stack. See L<perlxs/"Variable-length Parameter Lists">.
1437
1438=item ix
1439
1440Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
1441was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
cb1a09d0
AD
1442
1443=item LEAVE
1444
1445Closing bracket on a callback. See C<ENTER> and L<perlcall>.
1446
1447 LEAVE;
1448
1449=item MARK
1450
5fb8527f 1451Stack marker variable for the XSUB. See C<dMARK>.
cb1a09d0
AD
1452
1453=item mg_clear
1454
1455Clear something magical that the SV represents. See C<sv_magic>.
1456
1457 int mg_clear _((SV* sv));
1458
1459=item mg_copy
1460
1461Copies the magic from one SV to another. See C<sv_magic>.
1462
1463 int mg_copy _((SV *, SV *, char *, STRLEN));
1464
1465=item mg_find
1466
1467Finds the magic pointer for type matching the SV. See C<sv_magic>.
1468
1469 MAGIC* mg_find _((SV* sv, int type));
1470
1471=item mg_free
1472
1473Free any magic storage used by the SV. See C<sv_magic>.
1474
1475 int mg_free _((SV* sv));
1476
1477=item mg_get
1478
1479Do magic after a value is retrieved from the SV. See C<sv_magic>.
1480
1481 int mg_get _((SV* sv));
1482
1483=item mg_len
1484
1485Report on the SV's length. See C<sv_magic>.
1486
1487 U32 mg_len _((SV* sv));
1488
1489=item mg_magical
1490
1491Turns on the magical status of an SV. See C<sv_magic>.
1492
1493 void mg_magical _((SV* sv));
1494
1495=item mg_set
1496
1497Do magic after a value is assigned to the SV. See C<sv_magic>.
1498
1499 int mg_set _((SV* sv));
1500
1501=item Move
1502
1503The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
1504source, C<d> is the destination, C<n> is the number of items, and C<t> is
1505the type.
1506
1507 (void) Move( s, d, n, t );
1508
1509=item na
1510
1511A variable which may be used with C<SvPV> to tell Perl to calculate the
1512string length.
1513
1514=item New
1515
1516The XSUB-writer's interface to the C C<malloc> function.
1517
1518 void * New( x, void *ptr, int size, type )
1519
1520=item Newc
1521
1522The XSUB-writer's interface to the C C<malloc> function, with cast.
1523
1524 void * Newc( x, void *ptr, int size, type, cast )
1525
1526=item Newz
1527
1528The XSUB-writer's interface to the C C<malloc> function. The allocated
1529memory is zeroed with C<memzero>.
1530
1531 void * Newz( x, void *ptr, int size, type )
1532
1533=item newAV
1534
1535Creates a new AV. The refcount is set to 1.
1536
1537 AV* newAV _((void));
1538
1539=item newHV
1540
1541Creates a new HV. The refcount is set to 1.
1542
1543 HV* newHV _((void));
1544
1545=item newRV
1546
1547Creates an RV wrapper for an SV. The refcount for the original SV is
1548incremented.
1549
1550 SV* newRV _((SV* ref));
1551
1552=item newSV
1553
1554Creates a new SV. The C<len> parameter indicates the number of bytes of
1555pre-allocated string space the SV should have. The refcount for the new SV
1556is set to 1.
1557
1558 SV* newSV _((STRLEN len));
1559
1560=item newSViv
1561
1562Creates a new SV and copies an integer into it. The refcount for the SV is
1563set to 1.
1564
1565 SV* newSViv _((IV i));
1566
1567=item newSVnv
1568
1569Creates a new SV and copies a double into it. The refcount for the SV is
1570set to 1.
1571
1572 SV* newSVnv _((NV i));
1573
1574=item newSVpv
1575
1576Creates a new SV and copies a string into it. The refcount for the SV is
1577set to 1. If C<len> is zero then Perl will compute the length.
1578
1579 SV* newSVpv _((char* s, STRLEN len));
1580
1581=item newSVrv
1582
1583Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
5fb8527f 1584it will be upgraded to one. If C<classname> is non-null then the new SV will
cb1a09d0
AD
1585be blessed in the specified package. The new SV is returned and its
1586refcount is 1.
1587
1588 SV* newSVrv _((SV* rv, char* classname));
1589
1590=item newSVsv
1591
5fb8527f 1592Creates a new SV which is an exact duplicate of the original SV.
cb1a09d0
AD
1593
1594 SV* newSVsv _((SV* old));
1595
1596=item newXS
1597
1598Used by C<xsubpp> to hook up XSUBs as Perl subs.
1599
1600=item newXSproto
1601
1602Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1603the subs.
1604
1605=item Nullav
1606
1607Null AV pointer.
1608
1609=item Nullch
1610
1611Null character pointer.
1612
1613=item Nullcv
1614
1615Null CV pointer.
1616
1617=item Nullhv
1618
1619Null HV pointer.
1620
1621=item Nullsv
1622
1623Null SV pointer.
1624
1625=item ORIGMARK
1626
1627The original stack mark for the XSUB. See C<dORIGMARK>.
1628
1629=item perl_alloc
1630
1631Allocates a new Perl interpreter. See L<perlembed>.
1632
1633=item perl_call_argv
1634
1635Performs a callback to the specified Perl sub. See L<perlcall>.
1636
1637 I32 perl_call_argv _((char* subname, I32 flags, char** argv));
1638
1639=item perl_call_method
1640
1641Performs a callback to the specified Perl method. The blessed object must
1642be on the stack. See L<perlcall>.
1643
1644 I32 perl_call_method _((char* methname, I32 flags));
1645
1646=item perl_call_pv
1647
1648Performs a callback to the specified Perl sub. See L<perlcall>.
1649
1650 I32 perl_call_pv _((char* subname, I32 flags));
1651
1652=item perl_call_sv
1653
1654Performs a callback to the Perl sub whose name is in the SV. See
1655L<perlcall>.
1656
1657 I32 perl_call_sv _((SV* sv, I32 flags));
1658
1659=item perl_construct
1660
1661Initializes a new Perl interpreter. See L<perlembed>.
1662
1663=item perl_destruct
1664
1665Shuts down a Perl interpreter. See L<perlembed>.
1666
1667=item perl_eval_sv
1668
1669Tells Perl to C<eval> the string in the SV.
1670
1671 I32 perl_eval_sv _((SV* sv, I32 flags));
1672
1673=item perl_free
1674
1675Releases a Perl interpreter. See L<perlembed>.
1676
1677=item perl_get_av
1678
1679Returns the AV of the specified Perl array. If C<create> is set and the
1680Perl variable does not exist then it will be created. If C<create> is not
1681set and the variable does not exist then null is returned.
1682
1683 AV* perl_get_av _((char* name, I32 create));
1684
1685=item perl_get_cv
1686
1687Returns the CV of the specified Perl sub. If C<create> is set and the Perl
1688variable does not exist then it will be created. If C<create> is not
1689set and the variable does not exist then null is returned.
1690
1691 CV* perl_get_cv _((char* name, I32 create));
1692
1693=item perl_get_hv
1694
1695Returns the HV of the specified Perl hash. If C<create> is set and the Perl
1696variable does not exist then it will be created. If C<create> is not
1697set and the variable does not exist then null is returned.
1698
1699 HV* perl_get_hv _((char* name, I32 create));
1700
1701=item perl_get_sv
1702
1703Returns the SV of the specified Perl scalar. If C<create> is set and the
1704Perl variable does not exist then it will be created. If C<create> is not
1705set and the variable does not exist then null is returned.
1706
1707 SV* perl_get_sv _((char* name, I32 create));
1708
1709=item perl_parse
1710
1711Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1712
1713=item perl_require_pv
1714
1715Tells Perl to C<require> a module.
1716
1717 void perl_require_pv _((char* pv));
1718
1719=item perl_run
1720
1721Tells a Perl interpreter to run. See L<perlembed>.
1722
1723=item POPi
1724
1725Pops an integer off the stack.
1726
1727 int POPi();
1728
1729=item POPl
1730
1731Pops a long off the stack.
1732
1733 long POPl();
1734
1735=item POPp
1736
1737Pops a string off the stack.
1738
1739 char * POPp();
1740
1741=item POPn
1742
1743Pops a double off the stack.
1744
1745 double POPn();
1746
1747=item POPs
1748
1749Pops an SV off the stack.
1750
1751 SV* POPs();
1752
1753=item PUSHMARK
1754
1755Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
1756
1757 PUSHMARK(p)
1758
1759=item PUSHi
1760
1761Push an integer onto the stack. The stack must have room for this element.
1762See C<XPUSHi>.
1763
1764 PUSHi(int d)
1765
1766=item PUSHn
1767
1768Push a double onto the stack. The stack must have room for this element.
1769See C<XPUSHn>.
1770
1771 PUSHn(double d)
1772
1773=item PUSHp
1774
1775Push a string onto the stack. The stack must have room for this element.
1776The C<len> indicates the length of the string. See C<XPUSHp>.
1777
1778 PUSHp(char *c, int len )
1779
1780=item PUSHs
1781
1782Push an SV onto the stack. The stack must have room for this element. See
1783C<XPUSHs>.
1784
1785 PUSHs(sv)
1786
1787=item PUTBACK
1788
1789Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1790See C<PUSHMARK> and L<perlcall> for other uses.
1791
1792 PUTBACK;
1793
1794=item Renew
1795
1796The XSUB-writer's interface to the C C<realloc> function.
1797
1798 void * Renew( void *ptr, int size, type )
1799
1800=item Renewc
1801
1802The XSUB-writer's interface to the C C<realloc> function, with cast.
1803
1804 void * Renewc( void *ptr, int size, type, cast )
1805
1806=item RETVAL
1807
1808Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
5fb8527f
PP
1809This is always the proper type for the XSUB.
1810See L<perlxs/"The RETVAL Variable">.
cb1a09d0
AD
1811
1812=item safefree
1813
1814The XSUB-writer's interface to the C C<free> function.
1815
1816=item safemalloc
1817
1818The XSUB-writer's interface to the C C<malloc> function.
1819
1820=item saferealloc
1821
1822The XSUB-writer's interface to the C C<realloc> function.
1823
1824=item savepv
1825
1826Copy a string to a safe spot. This does not use an SV.
1827
1828 char* savepv _((char* sv));
1829
1830=item savepvn
1831
1832Copy a string to a safe spot. The C<len> indicates number of bytes to
1833copy. This does not use an SV.
1834
1835 char* savepvn _((char* sv, I32 len));
1836
1837=item SAVETMPS
1838
1839Opening bracket for temporaries on a callback. See C<FREETMPS> and
1840L<perlcall>.
1841
1842 SAVETMPS;
1843
1844=item SP
1845
1846Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1847C<SPAGAIN>.
1848
1849=item SPAGAIN
1850
1851Refetch the stack pointer. Used after a callback. See L<perlcall>.
1852
1853 SPAGAIN;
1854
1855=item ST
1856
1857Used to access elements on the XSUB's stack.
1858
1859 SV* ST(int x)
1860
1861=item strEQ
1862
1863Test two strings to see if they are equal. Returns true or false.
1864
1865 int strEQ( char *s1, char *s2 )
1866
1867=item strGE
1868
1869Test two strings to see if the first, C<s1>, is greater than or equal to the
1870second, C<s2>. Returns true or false.
1871
1872 int strGE( char *s1, char *s2 )
1873
1874=item strGT
1875
1876Test two strings to see if the first, C<s1>, is greater than the second,
1877C<s2>. Returns true or false.
1878
1879 int strGT( char *s1, char *s2 )
1880
1881=item strLE
1882
1883Test two strings to see if the first, C<s1>, is less than or equal to the
1884second, C<s2>. Returns true or false.
1885
1886 int strLE( char *s1, char *s2 )
1887
1888=item strLT
1889
1890Test two strings to see if the first, C<s1>, is less than the second,
1891C<s2>. Returns true or false.
1892
1893 int strLT( char *s1, char *s2 )
1894
1895=item strNE
1896
1897Test two strings to see if they are different. Returns true or false.
1898
1899 int strNE( char *s1, char *s2 )
1900
1901=item strnEQ
1902
1903Test two strings to see if they are equal. The C<len> parameter indicates
1904the number of bytes to compare. Returns true or false.
1905
1906 int strnEQ( char *s1, char *s2 )
1907
1908=item strnNE
1909
1910Test two strings to see if they are different. The C<len> parameter
1911indicates the number of bytes to compare. Returns true or false.
1912
1913 int strnNE( char *s1, char *s2, int len )
1914
1915=item sv_2mortal
1916
1917Marks an SV as mortal. The SV will be destroyed when the current context
1918ends.
1919
1920 SV* sv_2mortal _((SV* sv));
1921
1922=item sv_bless
1923
1924Blesses an SV into a specified package. The SV must be an RV. The package
1925must be designated by its stash (see C<gv_stashpv()>). The refcount of the
1926SV is unaffected.
1927
1928 SV* sv_bless _((SV* sv, HV* stash));
1929
1930=item sv_catpv
1931
1932Concatenates the string onto the end of the string which is in the SV.
1933
1934 void sv_catpv _((SV* sv, char* ptr));
1935
1936=item sv_catpvn
1937
1938Concatenates the string onto the end of the string which is in the SV. The
1939C<len> indicates number of bytes to copy.
1940
1941 void sv_catpvn _((SV* sv, char* ptr, STRLEN len));
1942
1943=item sv_catsv
1944
5fb8527f 1945Concatenates the string from SV C<ssv> onto the end of the string in SV
cb1a09d0
AD
1946C<dsv>.
1947
1948 void sv_catsv _((SV* dsv, SV* ssv));
1949
5fb8527f
PP
1950=item sv_cmp
1951
1952Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1953string in C<sv1> is less than, equal to, or greater than the string in
1954C<sv2>.
1955
1956 I32 sv_cmp _((SV* sv1, SV* sv2));
1957
1958=item sv_cmp
1959
1960Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1961string in C<sv1> is less than, equal to, or greater than the string in
1962C<sv2>.
1963
1964 I32 sv_cmp _((SV* sv1, SV* sv2));
1965
cb1a09d0
AD
1966=item SvCUR
1967
1968Returns the length of the string which is in the SV. See C<SvLEN>.
1969
1970 int SvCUR (SV* sv)
1971
1972=item SvCUR_set
1973
1974Set the length of the string which is in the SV. See C<SvCUR>.
1975
1976 SvCUR_set (SV* sv, int val )
1977
5fb8527f
PP
1978=item sv_dec
1979
1980Autodecrement of the value in the SV.
1981
1982 void sv_dec _((SV* sv));
1983
1984=item sv_dec
1985
1986Autodecrement of the value in the SV.
1987
1988 void sv_dec _((SV* sv));
1989
cb1a09d0
AD
1990=item SvEND
1991
1992Returns a pointer to the last character in the string which is in the SV.
1993See C<SvCUR>. Access the character as
1994
1995 *SvEND(sv)
1996
5fb8527f
PP
1997=item sv_eq
1998
1999Returns a boolean indicating whether the strings in the two SVs are
2000identical.
2001
2002 I32 sv_eq _((SV* sv1, SV* sv2));
2003
cb1a09d0
AD
2004=item SvGROW
2005
5fb8527f
PP
2006Expands the character buffer in the SV. Calls C<sv_grow> to perform the
2007expansion if necessary. Returns a pointer to the character buffer.
cb1a09d0
AD
2008
2009 char * SvGROW( SV* sv, int len )
2010
5fb8527f
PP
2011=item sv_grow
2012
2013Expands the character buffer in the SV. This will use C<sv_unref> and will
2014upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
2015Use C<SvGROW>.
2016
2017=item sv_inc
2018
2019Autoincrement of the value in the SV.
2020
2021 void sv_inc _((SV* sv));
2022
cb1a09d0
AD
2023=item SvIOK
2024
2025Returns a boolean indicating whether the SV contains an integer.
2026
2027 int SvIOK (SV* SV)
2028
2029=item SvIOK_off
2030
2031Unsets the IV status of an SV.
2032
2033 SvIOK_off (SV* sv)
2034
2035=item SvIOK_on
2036
2037Tells an SV that it is an integer.
2038
2039 SvIOK_on (SV* sv)
2040
5fb8527f
PP
2041=item SvIOK_only
2042
2043Tells an SV that it is an integer and disables all other OK bits.
2044
2045 SvIOK_on (SV* sv)
2046
2047=item SvIOK_only
2048
2049Tells an SV that it is an integer and disables all other OK bits.
2050
2051 SvIOK_on (SV* sv)
2052
cb1a09d0
AD
2053=item SvIOKp
2054
2055Returns a boolean indicating whether the SV contains an integer. Checks the
2056B<private> setting. Use C<SvIOK>.
2057
2058 int SvIOKp (SV* SV)
2059
2060=item sv_isa
2061
2062Returns a boolean indicating whether the SV is blessed into the specified
2063class. This does not know how to check for subtype, so it doesn't work in
2064an inheritance relationship.
2065
2066 int sv_isa _((SV* sv, char* name));
2067
2068=item SvIV
2069
2070Returns the integer which is in the SV.
2071
2072 int SvIV (SV* sv)
2073
2074=item sv_isobject
2075
2076Returns a boolean indicating whether the SV is an RV pointing to a blessed
2077object. If the SV is not an RV, or if the object is not blessed, then this
2078will return false.
2079
2080 int sv_isobject _((SV* sv));
2081
2082=item SvIVX
2083
2084Returns the integer which is stored in the SV.
2085
2086 int SvIVX (SV* sv);
2087
2088=item SvLEN
2089
2090Returns the size of the string buffer in the SV. See C<SvCUR>.
2091
2092 int SvLEN (SV* sv)
2093
5fb8527f
PP
2094=item sv_len
2095
2096Returns the length of the string in the SV. Use C<SvCUR>.
2097
2098 STRLEN sv_len _((SV* sv));
2099
2100=item sv_len
2101
2102Returns the length of the string in the SV. Use C<SvCUR>.
2103
2104 STRLEN sv_len _((SV* sv));
2105
cb1a09d0
AD
2106=item sv_magic
2107
2108Adds magic to an SV.
2109
2110 void sv_magic _((SV* sv, SV* obj, int how, char* name, I32 namlen));
2111
2112=item sv_mortalcopy
2113
2114Creates a new SV which is a copy of the original SV. The new SV is marked
bbce6d69 2115as mortal. The old SV may become invalid if it was marked as a temporary.
cb1a09d0
AD
2116
2117 SV* sv_mortalcopy _((SV* oldsv));
2118
2119=item SvOK
2120
2121Returns a boolean indicating whether the value is an SV.
2122
2123 int SvOK (SV* sv)
2124
2125=item sv_newmortal
2126
2127Creates a new SV which is mortal. The refcount of the SV is set to 1.
2128
2129 SV* sv_newmortal _((void));
2130
2131=item sv_no
2132
2133This is the C<false> SV. See C<sv_yes>. Always refer to this as C<&sv_no>.
2134
2135=item SvNIOK
2136
2137Returns a boolean indicating whether the SV contains a number, integer or
2138double.
2139
2140 int SvNIOK (SV* SV)
2141
2142=item SvNIOK_off
2143
2144Unsets the NV/IV status of an SV.
2145
2146 SvNIOK_off (SV* sv)
2147
2148=item SvNIOKp
2149
2150Returns a boolean indicating whether the SV contains a number, integer or
2151double. Checks the B<private> setting. Use C<SvNIOK>.
2152
2153 int SvNIOKp (SV* SV)
2154
2155=item SvNOK
2156
2157Returns a boolean indicating whether the SV contains a double.
2158
2159 int SvNOK (SV* SV)
2160
2161=item SvNOK_off
2162
2163Unsets the NV status of an SV.
2164
2165 SvNOK_off (SV* sv)
2166
2167=item SvNOK_on
2168
2169Tells an SV that it is a double.
2170
2171 SvNOK_on (SV* sv)
2172
5fb8527f
PP
2173=item SvNOK_only
2174
2175Tells an SV that it is a double and disables all other OK bits.
2176
2177 SvNOK_on (SV* sv)
2178
2179=item SvNOK_only
2180
2181Tells an SV that it is a double and disables all other OK bits.
2182
2183 SvNOK_on (SV* sv)
2184
cb1a09d0
AD
2185=item SvNOKp
2186
2187Returns a boolean indicating whether the SV contains a double. Checks the
2188B<private> setting. Use C<SvNOK>.
2189
2190 int SvNOKp (SV* SV)
2191
2192=item SvNV
2193
2194Returns the double which is stored in the SV.
2195
2196 double SvNV (SV* sv);
2197
2198=item SvNVX
2199
2200Returns the double which is stored in the SV.
2201
2202 double SvNVX (SV* sv);
2203
2204=item SvPOK
2205
2206Returns a boolean indicating whether the SV contains a character string.
2207
2208 int SvPOK (SV* SV)
2209
2210=item SvPOK_off
2211
2212Unsets the PV status of an SV.
2213
2214 SvPOK_off (SV* sv)
2215
2216=item SvPOK_on
2217
2218Tells an SV that it is a string.
2219
2220 SvPOK_on (SV* sv)
2221
5fb8527f
PP
2222=item SvPOK_only
2223
2224Tells an SV that it is a string and disables all other OK bits.
2225
2226 SvPOK_on (SV* sv)
2227
2228=item SvPOK_only
2229
2230Tells an SV that it is a string and disables all other OK bits.
2231
2232 SvPOK_on (SV* sv)
2233
cb1a09d0
AD
2234=item SvPOKp
2235
2236Returns a boolean indicating whether the SV contains a character string.
2237Checks the B<private> setting. Use C<SvPOK>.
2238
2239 int SvPOKp (SV* SV)
2240
2241=item SvPV
2242
2243Returns a pointer to the string in the SV, or a stringified form of the SV
2244if the SV does not contain a string. If C<len> is C<na> then Perl will
2245handle the length on its own.
2246
2247 char * SvPV (SV* sv, int len )
2248
2249=item SvPVX
2250
2251Returns a pointer to the string in the SV. The SV must contain a string.
2252
2253 char * SvPVX (SV* sv)
2254
2255=item SvREFCNT
2256
2257Returns the value of the object's refcount.
2258
2259 int SvREFCNT (SV* sv);
2260
2261=item SvREFCNT_dec
2262
2263Decrements the refcount of the given SV.
2264
2265 void SvREFCNT_dec (SV* sv)
2266
2267=item SvREFCNT_inc
2268
2269Increments the refcount of the given SV.
2270
2271 void SvREFCNT_inc (SV* sv)
2272
2273=item SvROK
2274
2275Tests if the SV is an RV.
2276
2277 int SvROK (SV* sv)
2278
2279=item SvROK_off
2280
2281Unsets the RV status of an SV.
2282
2283 SvROK_off (SV* sv)
2284
2285=item SvROK_on
2286
2287Tells an SV that it is an RV.
2288
2289 SvROK_on (SV* sv)
2290
2291=item SvRV
2292
2293Dereferences an RV to return the SV.
2294
2295 SV* SvRV (SV* sv);
2296
2297=item sv_setiv
2298
2299Copies an integer into the given SV.
2300
2301 void sv_setiv _((SV* sv, IV num));
2302
2303=item sv_setnv
2304
2305Copies a double into the given SV.
2306
2307 void sv_setnv _((SV* sv, double num));
2308
2309=item sv_setpv
2310
2311Copies a string into an SV. The string must be null-terminated.
2312
2313 void sv_setpv _((SV* sv, char* ptr));
2314
2315=item sv_setpvn
2316
2317Copies a string into an SV. The C<len> parameter indicates the number of
2318bytes to be copied.
2319
2320 void sv_setpvn _((SV* sv, char* ptr, STRLEN len));
2321
2322=item sv_setref_iv
2323
5fb8527f
PP
2324Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2325argument will be upgraded to an RV. That RV will be modified to point to
2326the new SV. The C<classname> argument indicates the package for the
2327blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2328will be returned and will have a refcount of 1.
cb1a09d0
AD
2329
2330 SV* sv_setref_iv _((SV *rv, char *classname, IV iv));
2331
2332=item sv_setref_nv
2333
5fb8527f
PP
2334Copies a double into a new SV, optionally blessing the SV. The C<rv>
2335argument will be upgraded to an RV. That RV will be modified to point to
2336the new SV. The C<classname> argument indicates the package for the
2337blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2338will be returned and will have a refcount of 1.
cb1a09d0
AD
2339
2340 SV* sv_setref_nv _((SV *rv, char *classname, double nv));
2341
2342=item sv_setref_pv
2343
5fb8527f
PP
2344Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
2345argument will be upgraded to an RV. That RV will be modified to point to
2346the new SV. If the C<pv> argument is NULL then C<sv_undef> will be placed
2347into the SV. The C<classname> argument indicates the package for the
2348blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2349will be returned and will have a refcount of 1.
cb1a09d0
AD
2350
2351 SV* sv_setref_pv _((SV *rv, char *classname, void* pv));
2352
2353Do not use with integral Perl types such as HV, AV, SV, CV, because those
2354objects will become corrupted by the pointer copy process.
2355
2356Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2357
2358=item sv_setref_pvn
2359
5fb8527f
PP
2360Copies a string into a new SV, optionally blessing the SV. The length of the
2361string must be specified with C<n>. The C<rv> argument will be upgraded to
2362an RV. That RV will be modified to point to the new SV. The C<classname>
cb1a09d0
AD
2363argument indicates the package for the blessing. Set C<classname> to
2364C<Nullch> to avoid the blessing. The new SV will be returned and will have
2365a refcount of 1.
2366
2367 SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
2368
2369Note that C<sv_setref_pv> copies the pointer while this copies the string.
2370
2371=item sv_setsv
2372
2373Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
bbce6d69 2374The source SV may be destroyed if it is mortal or temporary.
cb1a09d0
AD
2375
2376 void sv_setsv _((SV* dsv, SV* ssv));
2377
bbce6d69
PP
2378=item SvSetSV
2379
2380A wrapper around C<sv_setsv>. Safe even if C<dst==ssv>.
2381
cb1a09d0
AD
2382=item SvSTASH
2383
2384Returns the stash of the SV.
2385
2386 HV * SvSTASH (SV* sv)
2387
2388=item SVt_IV
2389
2390Integer type flag for scalars. See C<svtype>.
2391
2392=item SVt_PV
2393
2394Pointer type flag for scalars. See C<svtype>.
2395
2396=item SVt_PVAV
2397
2398Type flag for arrays. See C<svtype>.
2399
2400=item SVt_PVCV
2401
2402Type flag for code refs. See C<svtype>.
2403
2404=item SVt_PVHV
2405
2406Type flag for hashes. See C<svtype>.
2407
2408=item SVt_PVMG
2409
2410Type flag for blessed scalars. See C<svtype>.
2411
2412=item SVt_NV
2413
2414Double type flag for scalars. See C<svtype>.
2415
2416=item SvTRUE
2417
2418Returns a boolean indicating whether Perl would evaluate the SV as true or
2419false, defined or undefined.
2420
2421 int SvTRUE (SV* sv)
2422
2423=item SvTYPE
2424
2425Returns the type of the SV. See C<svtype>.
2426
2427 svtype SvTYPE (SV* sv)
2428
2429=item svtype
2430
2431An enum of flags for Perl types. These are found in the file B<sv.h> in the
2432C<svtype> enum. Test these flags with the C<SvTYPE> macro.
2433
2434=item SvUPGRADE
2435
5fb8527f
PP
2436Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
2437the upgrade if necessary. See C<svtype>.
2438
2439 bool SvUPGRADE _((SV* sv, svtype mt));
2440
2441=item sv_upgrade
2442
2443Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
cb1a09d0
AD
2444
2445=item sv_undef
2446
2447This is the C<undef> SV. Always refer to this as C<&sv_undef>.
2448
5fb8527f
PP
2449=item sv_unref
2450
2451Unsets the RV status of the SV, and decrements the refcount of whatever was
2452being referenced by the RV. This can almost be thought of as a reversal of
2453C<newSVrv>. See C<SvROK_off>.
2454
2455 void sv_unref _((SV* sv));
2456
cb1a09d0
AD
2457=item sv_usepvn
2458
2459Tells an SV to use C<ptr> to find its string value. Normally the string is
5fb8527f
PP
2460stored inside the SV but sv_usepvn allows the SV to use an outside string.
2461The C<ptr> should point to memory that was allocated by C<malloc>. The
cb1a09d0
AD
2462string length, C<len>, must be supplied. This function will realloc the
2463memory pointed to by C<ptr>, so that pointer should not be freed or used by
2464the programmer after giving it to sv_usepvn.
2465
2466 void sv_usepvn _((SV* sv, char* ptr, STRLEN len));
2467
2468=item sv_yes
2469
2470This is the C<true> SV. See C<sv_no>. Always refer to this as C<&sv_yes>.
2471
2472=item THIS
2473
2474Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
2475This is always the proper type for the C++ object. See C<CLASS> and
5fb8527f 2476L<perlxs/"Using XS With C++">.
cb1a09d0
AD
2477
2478=item toLOWER
2479
2480Converts the specified character to lowercase.
2481
2482 int toLOWER (char c)
2483
2484=item toUPPER
2485
2486Converts the specified character to uppercase.
2487
2488 int toUPPER (char c)
2489
2490=item warn
2491
2492This is the XSUB-writer's interface to Perl's C<warn> function. Use this
2493function the same way you use the C C<printf> function. See C<croak()>.
2494
2495=item XPUSHi
2496
2497Push an integer onto the stack, extending the stack if necessary. See
2498C<PUSHi>.
2499
2500 XPUSHi(int d)
2501
2502=item XPUSHn
2503
2504Push a double onto the stack, extending the stack if necessary. See
2505C<PUSHn>.
2506
2507 XPUSHn(double d)
2508
2509=item XPUSHp
2510
2511Push a string onto the stack, extending the stack if necessary. The C<len>
2512indicates the length of the string. See C<PUSHp>.
2513
2514 XPUSHp(char *c, int len)
2515
2516=item XPUSHs
2517
2518Push an SV onto the stack, extending the stack if necessary. See C<PUSHs>.
2519
2520 XPUSHs(sv)
2521
5fb8527f
PP
2522=item XS
2523
2524Macro to declare an XSUB and its C parameter list. This is handled by
2525C<xsubpp>.
2526
cb1a09d0
AD
2527=item XSRETURN
2528
2529Return from XSUB, indicating number of items on the stack. This is usually
2530handled by C<xsubpp>.
2531
5fb8527f 2532 XSRETURN(int x);
cb1a09d0
AD
2533
2534=item XSRETURN_EMPTY
2535
5fb8527f 2536Return an empty list from an XSUB immediately.
cb1a09d0
AD
2537
2538 XSRETURN_EMPTY;
2539
5fb8527f
PP
2540=item XSRETURN_IV
2541
2542Return an integer from an XSUB immediately. Uses C<XST_mIV>.
2543
2544 XSRETURN_IV(IV v);
2545
cb1a09d0
AD
2546=item XSRETURN_NO
2547
5fb8527f 2548Return C<&sv_no> from an XSUB immediately. Uses C<XST_mNO>.
cb1a09d0
AD
2549
2550 XSRETURN_NO;
2551
5fb8527f
PP
2552=item XSRETURN_NV
2553
2554Return an double from an XSUB immediately. Uses C<XST_mNV>.
2555
2556 XSRETURN_NV(NV v);
2557
2558=item XSRETURN_PV
2559
2560Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2561
2562 XSRETURN_PV(char *v);
2563
cb1a09d0
AD
2564=item XSRETURN_UNDEF
2565
5fb8527f 2566Return C<&sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
cb1a09d0
AD
2567
2568 XSRETURN_UNDEF;
2569
2570=item XSRETURN_YES
2571
5fb8527f 2572Return C<&sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
cb1a09d0
AD
2573
2574 XSRETURN_YES;
2575
5fb8527f
PP
2576=item XST_mIV
2577
2578Place an integer into the specified position C<i> on the stack. The value is
2579stored in a new mortal SV.
2580
2581 XST_mIV( int i, IV v );
2582
2583=item XST_mNV
2584
2585Place a double into the specified position C<i> on the stack. The value is
2586stored in a new mortal SV.
2587
2588 XST_mNV( int i, NV v );
2589
2590=item XST_mNO
2591
2592Place C<&sv_no> into the specified position C<i> on the stack.
2593
2594 XST_mNO( int i );
2595
2596=item XST_mPV
2597
2598Place a copy of a string into the specified position C<i> on the stack. The
2599value is stored in a new mortal SV.
2600
2601 XST_mPV( int i, char *v );
2602
2603=item XST_mUNDEF
2604
2605Place C<&sv_undef> into the specified position C<i> on the stack.
2606
2607 XST_mUNDEF( int i );
2608
2609=item XST_mYES
2610
2611Place C<&sv_yes> into the specified position C<i> on the stack.
2612
2613 XST_mYES( int i );
2614
2615=item XS_VERSION
2616
2617The version identifier for an XS module. This is usually handled
2618automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
2619
2620=item XS_VERSION_BOOTCHECK
2621
2622Macro to verify that a PM module's $VERSION variable matches the XS module's
2623C<XS_VERSION> variable. This is usually handled automatically by
2624C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
2625
cb1a09d0
AD
2626=item Zero
2627
2628The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
2629destination, C<n> is the number of items, and C<t> is the type.
2630
2631 (void) Zero( d, n, t );
2632
2633=back
2634
2635=head1 AUTHOR
2636
55497cff 2637Jeff Okamoto <okamoto@corp.hp.com>
cb1a09d0
AD
2638
2639With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2640Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
55497cff 2641Bowers, Matthew Green, Tim Bunce, Spider Boardman, and Ulrich Pfeifer.
cb1a09d0 2642
55497cff 2643API Listing by Dean Roehrich <roehrich@cray.com>.
cb1a09d0
AD
2644
2645=head1 DATE
2646
55497cff 2647Version 23.1: 1996/10/19