This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Less malloc in magic
[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
cb1a09d0 1009=head1 API LISTING
a0d0e21e 1010
cb1a09d0
AD
1011This is a listing of functions, macros, flags, and variables that may be
1012useful to extension writers or that may be found while reading other
1013extensions.
a0d0e21e 1014
cb1a09d0 1015=over 8
a0d0e21e 1016
cb1a09d0
AD
1017=item AvFILL
1018
1019See C<av_len>.
1020
1021=item av_clear
1022
1023Clears an array, making it empty.
1024
1025 void av_clear _((AV* ar));
1026
1027=item av_extend
1028
1029Pre-extend an array. The C<key> is the index to which the array should be
1030extended.
1031
1032 void av_extend _((AV* ar, I32 key));
1033
1034=item av_fetch
1035
1036Returns the SV at the specified index in the array. The C<key> is the
1037index. If C<lval> is set then the fetch will be part of a store. Check
1038that the return value is non-null before dereferencing it to a C<SV*>.
1039
1040 SV** av_fetch _((AV* ar, I32 key, I32 lval));
1041
1042=item av_len
1043
1044Returns the highest index in the array. Returns -1 if the array is empty.
1045
1046 I32 av_len _((AV* ar));
1047
1048=item av_make
1049
5fb8527f
PP
1050Creates a new AV and populates it with a list of SVs. The SVs are copied
1051into the array, so they may be freed after the call to av_make. The new AV
1052will have a refcount of 1.
cb1a09d0
AD
1053
1054 AV* av_make _((I32 size, SV** svp));
1055
1056=item av_pop
1057
1058Pops an SV off the end of the array. Returns C<&sv_undef> if the array is
1059empty.
1060
1061 SV* av_pop _((AV* ar));
1062
1063=item av_push
1064
5fb8527f
PP
1065Pushes an SV onto the end of the array. The array will grow automatically
1066to accommodate the addition.
cb1a09d0
AD
1067
1068 void av_push _((AV* ar, SV* val));
1069
1070=item av_shift
1071
1072Shifts an SV off the beginning of the array.
1073
1074 SV* av_shift _((AV* ar));
1075
1076=item av_store
1077
1078Stores an SV in an array. The array index is specified as C<key>. The
1079return value will be null if the operation failed, otherwise it can be
1080dereferenced to get the original C<SV*>.
1081
1082 SV** av_store _((AV* ar, I32 key, SV* val));
1083
1084=item av_undef
1085
1086Undefines the array.
1087
1088 void av_undef _((AV* ar));
1089
1090=item av_unshift
1091
5fb8527f
PP
1092Unshift an SV onto the beginning of the array. The array will grow
1093automatically to accommodate the addition.
cb1a09d0
AD
1094
1095 void av_unshift _((AV* ar, I32 num));
1096
1097=item CLASS
1098
1099Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
5fb8527f
PP
1100constructor. This is always a C<char*>. See C<THIS> and
1101L<perlxs/"Using XS With C++">.
cb1a09d0
AD
1102
1103=item Copy
1104
1105The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
1106source, C<d> is the destination, C<n> is the number of items, and C<t> is
1107the type.
1108
1109 (void) Copy( s, d, n, t );
1110
1111=item croak
1112
1113This is the XSUB-writer's interface to Perl's C<die> function. Use this
1114function the same way you use the C C<printf> function. See C<warn>.
1115
1116=item CvSTASH
1117
1118Returns the stash of the CV.
1119
1120 HV * CvSTASH( SV* sv )
1121
1122=item DBsingle
1123
1124When Perl is run in debugging mode, with the B<-d> switch, this SV is a
1125boolean which indicates whether subs are being single-stepped.
5fb8527f
PP
1126Single-stepping is automatically turned on after every step. This is the C
1127variable which corresponds to Perl's $DB::single variable. See C<DBsub>.
cb1a09d0
AD
1128
1129=item DBsub
1130
1131When Perl is run in debugging mode, with the B<-d> switch, this GV contains
5fb8527f
PP
1132the SV which holds the name of the sub being debugged. This is the C
1133variable which corresponds to Perl's $DB::sub variable. See C<DBsingle>.
cb1a09d0
AD
1134The sub name can be found by
1135
1136 SvPV( GvSV( DBsub ), na )
1137
5fb8527f
PP
1138=item DBtrace
1139
1140Trace variable used when Perl is run in debugging mode, with the B<-d>
1141switch. This is the C variable which corresponds to Perl's $DB::trace
1142variable. See C<DBsingle>.
1143
cb1a09d0
AD
1144=item dMARK
1145
5fb8527f
PP
1146Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1147C<dORIGMARK>.
cb1a09d0
AD
1148
1149=item dORIGMARK
1150
1151Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1152
5fb8527f
PP
1153=item dowarn
1154
1155The C variable which corresponds to Perl's $^W warning variable.
1156
cb1a09d0
AD
1157=item dSP
1158
5fb8527f 1159Declares a stack pointer variable, C<sp>, for the XSUB. See C<SP>.
cb1a09d0
AD
1160
1161=item dXSARGS
1162
1163Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
1164usually handled automatically by C<xsubpp>. Declares the C<items> variable
1165to indicate the number of items on the stack.
1166
5fb8527f
PP
1167=item dXSI32
1168
1169Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1170handled automatically by C<xsubpp>.
1171
1172=item dXSI32
1173
1174Sets up the C<ix> variable for an XSUB which has aliases. This is usually
1175handled automatically by C<xsubpp>.
1176
cb1a09d0
AD
1177=item ENTER
1178
1179Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
1180
1181 ENTER;
1182
1183=item EXTEND
1184
1185Used to extend the argument stack for an XSUB's return values.
1186
1187 EXTEND( sp, int x );
1188
1189=item FREETMPS
1190
1191Closing bracket for temporaries on a callback. See C<SAVETMPS> and
1192L<perlcall>.
1193
1194 FREETMPS;
1195
1196=item G_ARRAY
1197
1198Used to indicate array context. See C<GIMME> and L<perlcall>.
1199
1200=item G_DISCARD
1201
1202Indicates that arguments returned from a callback should be discarded. See
1203L<perlcall>.
1204
1205=item G_EVAL
1206
1207Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
1208
1209=item GIMME
1210
1211The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_SCALAR> or
1212C<G_ARRAY> for scalar or array context.
1213
1214=item G_NOARGS
1215
1216Indicates that no arguments are being sent to a callback. See L<perlcall>.
1217
1218=item G_SCALAR
1219
1220Used to indicate scalar context. See C<GIMME> and L<perlcall>.
1221
1222=item gv_stashpv
1223
1224Returns a pointer to the stash for a specified package. If C<create> is set
1225then the package will be created if it does not already exist. If C<create>
1226is not set and the package does not exist then NULL is returned.
1227
1228 HV* gv_stashpv _((char* name, I32 create));
1229
1230=item gv_stashsv
1231
1232Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
1233
1234 HV* gv_stashsv _((SV* sv, I32 create));
1235
1236=item GvSV
1237
1238Return the SV from the GV.
1239
1240=item he_free
1241
1242Releases a hash entry from an iterator. See C<hv_iternext>.
1243
1244=item hv_clear
1245
1246Clears a hash, making it empty.
1247
1248 void hv_clear _((HV* tb));
1249
1250=item hv_delete
1251
1252Deletes a key/value pair in the hash. The value SV is removed from the hash
5fb8527f 1253and returned to the caller. The C<klen> is the length of the key. The
cb1a09d0
AD
1254C<flags> value will normally be zero; if set to G_DISCARD then null will be
1255returned.
1256
1257 SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
1258
1259=item hv_exists
1260
1261Returns a boolean indicating whether the specified hash key exists. The
5fb8527f 1262C<klen> is the length of the key.
cb1a09d0
AD
1263
1264 bool hv_exists _((HV* tb, char* key, U32 klen));
1265
1266=item hv_fetch
1267
1268Returns the SV which corresponds to the specified key in the hash. The
5fb8527f 1269C<klen> is the length of the key. If C<lval> is set then the fetch will be
cb1a09d0
AD
1270part of a store. Check that the return value is non-null before
1271dereferencing it to a C<SV*>.
1272
1273 SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
1274
1275=item hv_iterinit
1276
1277Prepares a starting point to traverse a hash table.
1278
1279 I32 hv_iterinit _((HV* tb));
1280
1281=item hv_iterkey
1282
1283Returns the key from the current position of the hash iterator. See
1284C<hv_iterinit>.
1285
1286 char* hv_iterkey _((HE* entry, I32* retlen));
1287
1288=item hv_iternext
1289
1290Returns entries from a hash iterator. See C<hv_iterinit>.
1291
1292 HE* hv_iternext _((HV* tb));
1293
1294=item hv_iternextsv
1295
1296Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1297operation.
1298
1299 SV * hv_iternextsv _((HV* hv, char** key, I32* retlen));
1300
1301=item hv_iterval
1302
1303Returns the value from the current position of the hash iterator. See
1304C<hv_iterkey>.
1305
1306 SV* hv_iterval _((HV* tb, HE* entry));
1307
1308=item hv_magic
1309
1310Adds magic to a hash. See C<sv_magic>.
1311
1312 void hv_magic _((HV* hv, GV* gv, int how));
1313
1314=item HvNAME
1315
1316Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
1317
1318 char *HvNAME (HV* stash)
1319
1320=item hv_store
1321
1322Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1323the length of the key. The C<hash> parameter is the pre-computed hash
1324value; if it is zero then Perl will compute it. The return value will be
1325null if the operation failed, otherwise it can be dereferenced to get the
1326original C<SV*>.
1327
1328 SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
1329
1330=item hv_undef
1331
1332Undefines the hash.
1333
1334 void hv_undef _((HV* tb));
1335
1336=item isALNUM
1337
1338Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
5fb8527f 1339character.
cb1a09d0
AD
1340
1341 int isALNUM (char c)
1342
1343=item isALPHA
1344
5fb8527f 1345Returns a boolean indicating whether the C C<char> is an ascii alphabetic
cb1a09d0
AD
1346character.
1347
1348 int isALPHA (char c)
1349
1350=item isDIGIT
1351
1352Returns a boolean indicating whether the C C<char> is an ascii digit.
1353
1354 int isDIGIT (char c)
1355
1356=item isLOWER
1357
1358Returns a boolean indicating whether the C C<char> is a lowercase character.
1359
1360 int isLOWER (char c)
1361
1362=item isSPACE
1363
1364Returns a boolean indicating whether the C C<char> is whitespace.
1365
1366 int isSPACE (char c)
1367
1368=item isUPPER
1369
1370Returns a boolean indicating whether the C C<char> is an uppercase character.
1371
1372 int isUPPER (char c)
1373
1374=item items
1375
1376Variable which is setup by C<xsubpp> to indicate the number of items on the
5fb8527f
PP
1377stack. See L<perlxs/"Variable-length Parameter Lists">.
1378
1379=item ix
1380
1381Variable which is setup by C<xsubpp> to indicate which of an XSUB's aliases
1382was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
cb1a09d0
AD
1383
1384=item LEAVE
1385
1386Closing bracket on a callback. See C<ENTER> and L<perlcall>.
1387
1388 LEAVE;
1389
1390=item MARK
1391
5fb8527f 1392Stack marker variable for the XSUB. See C<dMARK>.
cb1a09d0
AD
1393
1394=item mg_clear
1395
1396Clear something magical that the SV represents. See C<sv_magic>.
1397
1398 int mg_clear _((SV* sv));
1399
1400=item mg_copy
1401
1402Copies the magic from one SV to another. See C<sv_magic>.
1403
1404 int mg_copy _((SV *, SV *, char *, STRLEN));
1405
1406=item mg_find
1407
1408Finds the magic pointer for type matching the SV. See C<sv_magic>.
1409
1410 MAGIC* mg_find _((SV* sv, int type));
1411
1412=item mg_free
1413
1414Free any magic storage used by the SV. See C<sv_magic>.
1415
1416 int mg_free _((SV* sv));
1417
1418=item mg_get
1419
1420Do magic after a value is retrieved from the SV. See C<sv_magic>.
1421
1422 int mg_get _((SV* sv));
1423
1424=item mg_len
1425
1426Report on the SV's length. See C<sv_magic>.
1427
1428 U32 mg_len _((SV* sv));
1429
1430=item mg_magical
1431
1432Turns on the magical status of an SV. See C<sv_magic>.
1433
1434 void mg_magical _((SV* sv));
1435
1436=item mg_set
1437
1438Do magic after a value is assigned to the SV. See C<sv_magic>.
1439
1440 int mg_set _((SV* sv));
1441
1442=item Move
1443
1444The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
1445source, C<d> is the destination, C<n> is the number of items, and C<t> is
1446the type.
1447
1448 (void) Move( s, d, n, t );
1449
1450=item na
1451
1452A variable which may be used with C<SvPV> to tell Perl to calculate the
1453string length.
1454
1455=item New
1456
1457The XSUB-writer's interface to the C C<malloc> function.
1458
1459 void * New( x, void *ptr, int size, type )
1460
1461=item Newc
1462
1463The XSUB-writer's interface to the C C<malloc> function, with cast.
1464
1465 void * Newc( x, void *ptr, int size, type, cast )
1466
1467=item Newz
1468
1469The XSUB-writer's interface to the C C<malloc> function. The allocated
1470memory is zeroed with C<memzero>.
1471
1472 void * Newz( x, void *ptr, int size, type )
1473
1474=item newAV
1475
1476Creates a new AV. The refcount is set to 1.
1477
1478 AV* newAV _((void));
1479
1480=item newHV
1481
1482Creates a new HV. The refcount is set to 1.
1483
1484 HV* newHV _((void));
1485
1486=item newRV
1487
1488Creates an RV wrapper for an SV. The refcount for the original SV is
1489incremented.
1490
1491 SV* newRV _((SV* ref));
1492
1493=item newSV
1494
1495Creates a new SV. The C<len> parameter indicates the number of bytes of
1496pre-allocated string space the SV should have. The refcount for the new SV
1497is set to 1.
1498
1499 SV* newSV _((STRLEN len));
1500
1501=item newSViv
1502
1503Creates a new SV and copies an integer into it. The refcount for the SV is
1504set to 1.
1505
1506 SV* newSViv _((IV i));
1507
1508=item newSVnv
1509
1510Creates a new SV and copies a double into it. The refcount for the SV is
1511set to 1.
1512
1513 SV* newSVnv _((NV i));
1514
1515=item newSVpv
1516
1517Creates a new SV and copies a string into it. The refcount for the SV is
1518set to 1. If C<len> is zero then Perl will compute the length.
1519
1520 SV* newSVpv _((char* s, STRLEN len));
1521
1522=item newSVrv
1523
1524Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
5fb8527f 1525it will be upgraded to one. If C<classname> is non-null then the new SV will
cb1a09d0
AD
1526be blessed in the specified package. The new SV is returned and its
1527refcount is 1.
1528
1529 SV* newSVrv _((SV* rv, char* classname));
1530
1531=item newSVsv
1532
5fb8527f 1533Creates a new SV which is an exact duplicate of the original SV.
cb1a09d0
AD
1534
1535 SV* newSVsv _((SV* old));
1536
1537=item newXS
1538
1539Used by C<xsubpp> to hook up XSUBs as Perl subs.
1540
1541=item newXSproto
1542
1543Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1544the subs.
1545
1546=item Nullav
1547
1548Null AV pointer.
1549
1550=item Nullch
1551
1552Null character pointer.
1553
1554=item Nullcv
1555
1556Null CV pointer.
1557
1558=item Nullhv
1559
1560Null HV pointer.
1561
1562=item Nullsv
1563
1564Null SV pointer.
1565
1566=item ORIGMARK
1567
1568The original stack mark for the XSUB. See C<dORIGMARK>.
1569
1570=item perl_alloc
1571
1572Allocates a new Perl interpreter. See L<perlembed>.
1573
1574=item perl_call_argv
1575
1576Performs a callback to the specified Perl sub. See L<perlcall>.
1577
1578 I32 perl_call_argv _((char* subname, I32 flags, char** argv));
1579
1580=item perl_call_method
1581
1582Performs a callback to the specified Perl method. The blessed object must
1583be on the stack. See L<perlcall>.
1584
1585 I32 perl_call_method _((char* methname, I32 flags));
1586
1587=item perl_call_pv
1588
1589Performs a callback to the specified Perl sub. See L<perlcall>.
1590
1591 I32 perl_call_pv _((char* subname, I32 flags));
1592
1593=item perl_call_sv
1594
1595Performs a callback to the Perl sub whose name is in the SV. See
1596L<perlcall>.
1597
1598 I32 perl_call_sv _((SV* sv, I32 flags));
1599
1600=item perl_construct
1601
1602Initializes a new Perl interpreter. See L<perlembed>.
1603
1604=item perl_destruct
1605
1606Shuts down a Perl interpreter. See L<perlembed>.
1607
1608=item perl_eval_sv
1609
1610Tells Perl to C<eval> the string in the SV.
1611
1612 I32 perl_eval_sv _((SV* sv, I32 flags));
1613
1614=item perl_free
1615
1616Releases a Perl interpreter. See L<perlembed>.
1617
1618=item perl_get_av
1619
1620Returns the AV of the specified Perl array. If C<create> is set and the
1621Perl variable does not exist then it will be created. If C<create> is not
1622set and the variable does not exist then null is returned.
1623
1624 AV* perl_get_av _((char* name, I32 create));
1625
1626=item perl_get_cv
1627
1628Returns the CV of the specified Perl sub. If C<create> is set and the Perl
1629variable does not exist then it will be created. If C<create> is not
1630set and the variable does not exist then null is returned.
1631
1632 CV* perl_get_cv _((char* name, I32 create));
1633
1634=item perl_get_hv
1635
1636Returns the HV of the specified Perl hash. If C<create> is set and the Perl
1637variable does not exist then it will be created. If C<create> is not
1638set and the variable does not exist then null is returned.
1639
1640 HV* perl_get_hv _((char* name, I32 create));
1641
1642=item perl_get_sv
1643
1644Returns the SV of the specified Perl scalar. If C<create> is set and the
1645Perl variable does not exist then it will be created. If C<create> is not
1646set and the variable does not exist then null is returned.
1647
1648 SV* perl_get_sv _((char* name, I32 create));
1649
1650=item perl_parse
1651
1652Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1653
1654=item perl_require_pv
1655
1656Tells Perl to C<require> a module.
1657
1658 void perl_require_pv _((char* pv));
1659
1660=item perl_run
1661
1662Tells a Perl interpreter to run. See L<perlembed>.
1663
1664=item POPi
1665
1666Pops an integer off the stack.
1667
1668 int POPi();
1669
1670=item POPl
1671
1672Pops a long off the stack.
1673
1674 long POPl();
1675
1676=item POPp
1677
1678Pops a string off the stack.
1679
1680 char * POPp();
1681
1682=item POPn
1683
1684Pops a double off the stack.
1685
1686 double POPn();
1687
1688=item POPs
1689
1690Pops an SV off the stack.
1691
1692 SV* POPs();
1693
1694=item PUSHMARK
1695
1696Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
1697
1698 PUSHMARK(p)
1699
1700=item PUSHi
1701
1702Push an integer onto the stack. The stack must have room for this element.
1703See C<XPUSHi>.
1704
1705 PUSHi(int d)
1706
1707=item PUSHn
1708
1709Push a double onto the stack. The stack must have room for this element.
1710See C<XPUSHn>.
1711
1712 PUSHn(double d)
1713
1714=item PUSHp
1715
1716Push a string onto the stack. The stack must have room for this element.
1717The C<len> indicates the length of the string. See C<XPUSHp>.
1718
1719 PUSHp(char *c, int len )
1720
1721=item PUSHs
1722
1723Push an SV onto the stack. The stack must have room for this element. See
1724C<XPUSHs>.
1725
1726 PUSHs(sv)
1727
1728=item PUTBACK
1729
1730Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1731See C<PUSHMARK> and L<perlcall> for other uses.
1732
1733 PUTBACK;
1734
1735=item Renew
1736
1737The XSUB-writer's interface to the C C<realloc> function.
1738
1739 void * Renew( void *ptr, int size, type )
1740
1741=item Renewc
1742
1743The XSUB-writer's interface to the C C<realloc> function, with cast.
1744
1745 void * Renewc( void *ptr, int size, type, cast )
1746
1747=item RETVAL
1748
1749Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
5fb8527f
PP
1750This is always the proper type for the XSUB.
1751See L<perlxs/"The RETVAL Variable">.
cb1a09d0
AD
1752
1753=item safefree
1754
1755The XSUB-writer's interface to the C C<free> function.
1756
1757=item safemalloc
1758
1759The XSUB-writer's interface to the C C<malloc> function.
1760
1761=item saferealloc
1762
1763The XSUB-writer's interface to the C C<realloc> function.
1764
1765=item savepv
1766
1767Copy a string to a safe spot. This does not use an SV.
1768
1769 char* savepv _((char* sv));
1770
1771=item savepvn
1772
1773Copy a string to a safe spot. The C<len> indicates number of bytes to
1774copy. This does not use an SV.
1775
1776 char* savepvn _((char* sv, I32 len));
1777
1778=item SAVETMPS
1779
1780Opening bracket for temporaries on a callback. See C<FREETMPS> and
1781L<perlcall>.
1782
1783 SAVETMPS;
1784
1785=item SP
1786
1787Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1788C<SPAGAIN>.
1789
1790=item SPAGAIN
1791
1792Refetch the stack pointer. Used after a callback. See L<perlcall>.
1793
1794 SPAGAIN;
1795
1796=item ST
1797
1798Used to access elements on the XSUB's stack.
1799
1800 SV* ST(int x)
1801
1802=item strEQ
1803
1804Test two strings to see if they are equal. Returns true or false.
1805
1806 int strEQ( char *s1, char *s2 )
1807
1808=item strGE
1809
1810Test two strings to see if the first, C<s1>, is greater than or equal to the
1811second, C<s2>. Returns true or false.
1812
1813 int strGE( char *s1, char *s2 )
1814
1815=item strGT
1816
1817Test two strings to see if the first, C<s1>, is greater than the second,
1818C<s2>. Returns true or false.
1819
1820 int strGT( char *s1, char *s2 )
1821
1822=item strLE
1823
1824Test two strings to see if the first, C<s1>, is less than or equal to the
1825second, C<s2>. Returns true or false.
1826
1827 int strLE( char *s1, char *s2 )
1828
1829=item strLT
1830
1831Test two strings to see if the first, C<s1>, is less than the second,
1832C<s2>. Returns true or false.
1833
1834 int strLT( char *s1, char *s2 )
1835
1836=item strNE
1837
1838Test two strings to see if they are different. Returns true or false.
1839
1840 int strNE( char *s1, char *s2 )
1841
1842=item strnEQ
1843
1844Test two strings to see if they are equal. The C<len> parameter indicates
1845the number of bytes to compare. Returns true or false.
1846
1847 int strnEQ( char *s1, char *s2 )
1848
1849=item strnNE
1850
1851Test two strings to see if they are different. The C<len> parameter
1852indicates the number of bytes to compare. Returns true or false.
1853
1854 int strnNE( char *s1, char *s2, int len )
1855
1856=item sv_2mortal
1857
1858Marks an SV as mortal. The SV will be destroyed when the current context
1859ends.
1860
1861 SV* sv_2mortal _((SV* sv));
1862
1863=item sv_bless
1864
1865Blesses an SV into a specified package. The SV must be an RV. The package
1866must be designated by its stash (see C<gv_stashpv()>). The refcount of the
1867SV is unaffected.
1868
1869 SV* sv_bless _((SV* sv, HV* stash));
1870
1871=item sv_catpv
1872
1873Concatenates the string onto the end of the string which is in the SV.
1874
1875 void sv_catpv _((SV* sv, char* ptr));
1876
1877=item sv_catpvn
1878
1879Concatenates the string onto the end of the string which is in the SV. The
1880C<len> indicates number of bytes to copy.
1881
1882 void sv_catpvn _((SV* sv, char* ptr, STRLEN len));
1883
1884=item sv_catsv
1885
5fb8527f 1886Concatenates the string from SV C<ssv> onto the end of the string in SV
cb1a09d0
AD
1887C<dsv>.
1888
1889 void sv_catsv _((SV* dsv, SV* ssv));
1890
5fb8527f
PP
1891=item sv_cmp
1892
1893Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1894string in C<sv1> is less than, equal to, or greater than the string in
1895C<sv2>.
1896
1897 I32 sv_cmp _((SV* sv1, SV* sv2));
1898
1899=item sv_cmp
1900
1901Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
1902string in C<sv1> is less than, equal to, or greater than the string in
1903C<sv2>.
1904
1905 I32 sv_cmp _((SV* sv1, SV* sv2));
1906
cb1a09d0
AD
1907=item SvCUR
1908
1909Returns the length of the string which is in the SV. See C<SvLEN>.
1910
1911 int SvCUR (SV* sv)
1912
1913=item SvCUR_set
1914
1915Set the length of the string which is in the SV. See C<SvCUR>.
1916
1917 SvCUR_set (SV* sv, int val )
1918
5fb8527f
PP
1919=item sv_dec
1920
1921Autodecrement of the value in the SV.
1922
1923 void sv_dec _((SV* sv));
1924
1925=item sv_dec
1926
1927Autodecrement of the value in the SV.
1928
1929 void sv_dec _((SV* sv));
1930
cb1a09d0
AD
1931=item SvEND
1932
1933Returns a pointer to the last character in the string which is in the SV.
1934See C<SvCUR>. Access the character as
1935
1936 *SvEND(sv)
1937
5fb8527f
PP
1938=item sv_eq
1939
1940Returns a boolean indicating whether the strings in the two SVs are
1941identical.
1942
1943 I32 sv_eq _((SV* sv1, SV* sv2));
1944
cb1a09d0
AD
1945=item SvGROW
1946
5fb8527f
PP
1947Expands the character buffer in the SV. Calls C<sv_grow> to perform the
1948expansion if necessary. Returns a pointer to the character buffer.
cb1a09d0
AD
1949
1950 char * SvGROW( SV* sv, int len )
1951
5fb8527f
PP
1952=item sv_grow
1953
1954Expands the character buffer in the SV. This will use C<sv_unref> and will
1955upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
1956Use C<SvGROW>.
1957
1958=item sv_inc
1959
1960Autoincrement of the value in the SV.
1961
1962 void sv_inc _((SV* sv));
1963
cb1a09d0
AD
1964=item SvIOK
1965
1966Returns a boolean indicating whether the SV contains an integer.
1967
1968 int SvIOK (SV* SV)
1969
1970=item SvIOK_off
1971
1972Unsets the IV status of an SV.
1973
1974 SvIOK_off (SV* sv)
1975
1976=item SvIOK_on
1977
1978Tells an SV that it is an integer.
1979
1980 SvIOK_on (SV* sv)
1981
5fb8527f
PP
1982=item SvIOK_only
1983
1984Tells an SV that it is an integer and disables all other OK bits.
1985
1986 SvIOK_on (SV* sv)
1987
1988=item SvIOK_only
1989
1990Tells an SV that it is an integer and disables all other OK bits.
1991
1992 SvIOK_on (SV* sv)
1993
cb1a09d0
AD
1994=item SvIOKp
1995
1996Returns a boolean indicating whether the SV contains an integer. Checks the
1997B<private> setting. Use C<SvIOK>.
1998
1999 int SvIOKp (SV* SV)
2000
2001=item sv_isa
2002
2003Returns a boolean indicating whether the SV is blessed into the specified
2004class. This does not know how to check for subtype, so it doesn't work in
2005an inheritance relationship.
2006
2007 int sv_isa _((SV* sv, char* name));
2008
2009=item SvIV
2010
2011Returns the integer which is in the SV.
2012
2013 int SvIV (SV* sv)
2014
2015=item sv_isobject
2016
2017Returns a boolean indicating whether the SV is an RV pointing to a blessed
2018object. If the SV is not an RV, or if the object is not blessed, then this
2019will return false.
2020
2021 int sv_isobject _((SV* sv));
2022
2023=item SvIVX
2024
2025Returns the integer which is stored in the SV.
2026
2027 int SvIVX (SV* sv);
2028
2029=item SvLEN
2030
2031Returns the size of the string buffer in the SV. See C<SvCUR>.
2032
2033 int SvLEN (SV* sv)
2034
5fb8527f
PP
2035=item sv_len
2036
2037Returns the length of the string in the SV. Use C<SvCUR>.
2038
2039 STRLEN sv_len _((SV* sv));
2040
2041=item sv_len
2042
2043Returns the length of the string in the SV. Use C<SvCUR>.
2044
2045 STRLEN sv_len _((SV* sv));
2046
cb1a09d0
AD
2047=item sv_magic
2048
2049Adds magic to an SV.
2050
2051 void sv_magic _((SV* sv, SV* obj, int how, char* name, I32 namlen));
2052
2053=item sv_mortalcopy
2054
2055Creates a new SV which is a copy of the original SV. The new SV is marked
bbce6d69 2056as mortal. The old SV may become invalid if it was marked as a temporary.
cb1a09d0
AD
2057
2058 SV* sv_mortalcopy _((SV* oldsv));
2059
2060=item SvOK
2061
2062Returns a boolean indicating whether the value is an SV.
2063
2064 int SvOK (SV* sv)
2065
2066=item sv_newmortal
2067
2068Creates a new SV which is mortal. The refcount of the SV is set to 1.
2069
2070 SV* sv_newmortal _((void));
2071
2072=item sv_no
2073
2074This is the C<false> SV. See C<sv_yes>. Always refer to this as C<&sv_no>.
2075
2076=item SvNIOK
2077
2078Returns a boolean indicating whether the SV contains a number, integer or
2079double.
2080
2081 int SvNIOK (SV* SV)
2082
2083=item SvNIOK_off
2084
2085Unsets the NV/IV status of an SV.
2086
2087 SvNIOK_off (SV* sv)
2088
2089=item SvNIOKp
2090
2091Returns a boolean indicating whether the SV contains a number, integer or
2092double. Checks the B<private> setting. Use C<SvNIOK>.
2093
2094 int SvNIOKp (SV* SV)
2095
2096=item SvNOK
2097
2098Returns a boolean indicating whether the SV contains a double.
2099
2100 int SvNOK (SV* SV)
2101
2102=item SvNOK_off
2103
2104Unsets the NV status of an SV.
2105
2106 SvNOK_off (SV* sv)
2107
2108=item SvNOK_on
2109
2110Tells an SV that it is a double.
2111
2112 SvNOK_on (SV* sv)
2113
5fb8527f
PP
2114=item SvNOK_only
2115
2116Tells an SV that it is a double and disables all other OK bits.
2117
2118 SvNOK_on (SV* sv)
2119
2120=item SvNOK_only
2121
2122Tells an SV that it is a double and disables all other OK bits.
2123
2124 SvNOK_on (SV* sv)
2125
cb1a09d0
AD
2126=item SvNOKp
2127
2128Returns a boolean indicating whether the SV contains a double. Checks the
2129B<private> setting. Use C<SvNOK>.
2130
2131 int SvNOKp (SV* SV)
2132
2133=item SvNV
2134
2135Returns the double which is stored in the SV.
2136
2137 double SvNV (SV* sv);
2138
2139=item SvNVX
2140
2141Returns the double which is stored in the SV.
2142
2143 double SvNVX (SV* sv);
2144
2145=item SvPOK
2146
2147Returns a boolean indicating whether the SV contains a character string.
2148
2149 int SvPOK (SV* SV)
2150
2151=item SvPOK_off
2152
2153Unsets the PV status of an SV.
2154
2155 SvPOK_off (SV* sv)
2156
2157=item SvPOK_on
2158
2159Tells an SV that it is a string.
2160
2161 SvPOK_on (SV* sv)
2162
5fb8527f
PP
2163=item SvPOK_only
2164
2165Tells an SV that it is a string and disables all other OK bits.
2166
2167 SvPOK_on (SV* sv)
2168
2169=item SvPOK_only
2170
2171Tells an SV that it is a string and disables all other OK bits.
2172
2173 SvPOK_on (SV* sv)
2174
cb1a09d0
AD
2175=item SvPOKp
2176
2177Returns a boolean indicating whether the SV contains a character string.
2178Checks the B<private> setting. Use C<SvPOK>.
2179
2180 int SvPOKp (SV* SV)
2181
2182=item SvPV
2183
2184Returns a pointer to the string in the SV, or a stringified form of the SV
2185if the SV does not contain a string. If C<len> is C<na> then Perl will
2186handle the length on its own.
2187
2188 char * SvPV (SV* sv, int len )
2189
2190=item SvPVX
2191
2192Returns a pointer to the string in the SV. The SV must contain a string.
2193
2194 char * SvPVX (SV* sv)
2195
2196=item SvREFCNT
2197
2198Returns the value of the object's refcount.
2199
2200 int SvREFCNT (SV* sv);
2201
2202=item SvREFCNT_dec
2203
2204Decrements the refcount of the given SV.
2205
2206 void SvREFCNT_dec (SV* sv)
2207
2208=item SvREFCNT_inc
2209
2210Increments the refcount of the given SV.
2211
2212 void SvREFCNT_inc (SV* sv)
2213
2214=item SvROK
2215
2216Tests if the SV is an RV.
2217
2218 int SvROK (SV* sv)
2219
2220=item SvROK_off
2221
2222Unsets the RV status of an SV.
2223
2224 SvROK_off (SV* sv)
2225
2226=item SvROK_on
2227
2228Tells an SV that it is an RV.
2229
2230 SvROK_on (SV* sv)
2231
2232=item SvRV
2233
2234Dereferences an RV to return the SV.
2235
2236 SV* SvRV (SV* sv);
2237
2238=item sv_setiv
2239
2240Copies an integer into the given SV.
2241
2242 void sv_setiv _((SV* sv, IV num));
2243
2244=item sv_setnv
2245
2246Copies a double into the given SV.
2247
2248 void sv_setnv _((SV* sv, double num));
2249
2250=item sv_setpv
2251
2252Copies a string into an SV. The string must be null-terminated.
2253
2254 void sv_setpv _((SV* sv, char* ptr));
2255
2256=item sv_setpvn
2257
2258Copies a string into an SV. The C<len> parameter indicates the number of
2259bytes to be copied.
2260
2261 void sv_setpvn _((SV* sv, char* ptr, STRLEN len));
2262
2263=item sv_setref_iv
2264
5fb8527f
PP
2265Copies an integer into a new SV, optionally blessing the SV. The C<rv>
2266argument will be upgraded to an RV. That RV will be modified to point to
2267the new SV. The C<classname> argument indicates the package for the
2268blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2269will be returned and will have a refcount of 1.
cb1a09d0
AD
2270
2271 SV* sv_setref_iv _((SV *rv, char *classname, IV iv));
2272
2273=item sv_setref_nv
2274
5fb8527f
PP
2275Copies a double into a new SV, optionally blessing the SV. The C<rv>
2276argument will be upgraded to an RV. That RV will be modified to point to
2277the new SV. The C<classname> argument indicates the package for the
2278blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2279will be returned and will have a refcount of 1.
cb1a09d0
AD
2280
2281 SV* sv_setref_nv _((SV *rv, char *classname, double nv));
2282
2283=item sv_setref_pv
2284
5fb8527f
PP
2285Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
2286argument will be upgraded to an RV. That RV will be modified to point to
2287the new SV. If the C<pv> argument is NULL then C<sv_undef> will be placed
2288into the SV. The C<classname> argument indicates the package for the
2289blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
2290will be returned and will have a refcount of 1.
cb1a09d0
AD
2291
2292 SV* sv_setref_pv _((SV *rv, char *classname, void* pv));
2293
2294Do not use with integral Perl types such as HV, AV, SV, CV, because those
2295objects will become corrupted by the pointer copy process.
2296
2297Note that C<sv_setref_pvn> copies the string while this copies the pointer.
2298
2299=item sv_setref_pvn
2300
5fb8527f
PP
2301Copies a string into a new SV, optionally blessing the SV. The length of the
2302string must be specified with C<n>. The C<rv> argument will be upgraded to
2303an RV. That RV will be modified to point to the new SV. The C<classname>
cb1a09d0
AD
2304argument indicates the package for the blessing. Set C<classname> to
2305C<Nullch> to avoid the blessing. The new SV will be returned and will have
2306a refcount of 1.
2307
2308 SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
2309
2310Note that C<sv_setref_pv> copies the pointer while this copies the string.
2311
2312=item sv_setsv
2313
2314Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
bbce6d69 2315The source SV may be destroyed if it is mortal or temporary.
cb1a09d0
AD
2316
2317 void sv_setsv _((SV* dsv, SV* ssv));
2318
bbce6d69
PP
2319=item SvSetSV
2320
2321A wrapper around C<sv_setsv>. Safe even if C<dst==ssv>.
2322
cb1a09d0
AD
2323=item SvSTASH
2324
2325Returns the stash of the SV.
2326
2327 HV * SvSTASH (SV* sv)
2328
2329=item SVt_IV
2330
2331Integer type flag for scalars. See C<svtype>.
2332
2333=item SVt_PV
2334
2335Pointer type flag for scalars. See C<svtype>.
2336
2337=item SVt_PVAV
2338
2339Type flag for arrays. See C<svtype>.
2340
2341=item SVt_PVCV
2342
2343Type flag for code refs. See C<svtype>.
2344
2345=item SVt_PVHV
2346
2347Type flag for hashes. See C<svtype>.
2348
2349=item SVt_PVMG
2350
2351Type flag for blessed scalars. See C<svtype>.
2352
2353=item SVt_NV
2354
2355Double type flag for scalars. See C<svtype>.
2356
2357=item SvTRUE
2358
2359Returns a boolean indicating whether Perl would evaluate the SV as true or
2360false, defined or undefined.
2361
2362 int SvTRUE (SV* sv)
2363
2364=item SvTYPE
2365
2366Returns the type of the SV. See C<svtype>.
2367
2368 svtype SvTYPE (SV* sv)
2369
2370=item svtype
2371
2372An enum of flags for Perl types. These are found in the file B<sv.h> in the
2373C<svtype> enum. Test these flags with the C<SvTYPE> macro.
2374
2375=item SvUPGRADE
2376
5fb8527f
PP
2377Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to perform
2378the upgrade if necessary. See C<svtype>.
2379
2380 bool SvUPGRADE _((SV* sv, svtype mt));
2381
2382=item sv_upgrade
2383
2384Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See C<svtype>.
cb1a09d0
AD
2385
2386=item sv_undef
2387
2388This is the C<undef> SV. Always refer to this as C<&sv_undef>.
2389
5fb8527f
PP
2390=item sv_unref
2391
2392Unsets the RV status of the SV, and decrements the refcount of whatever was
2393being referenced by the RV. This can almost be thought of as a reversal of
2394C<newSVrv>. See C<SvROK_off>.
2395
2396 void sv_unref _((SV* sv));
2397
cb1a09d0
AD
2398=item sv_usepvn
2399
2400Tells an SV to use C<ptr> to find its string value. Normally the string is
5fb8527f
PP
2401stored inside the SV but sv_usepvn allows the SV to use an outside string.
2402The C<ptr> should point to memory that was allocated by C<malloc>. The
cb1a09d0
AD
2403string length, C<len>, must be supplied. This function will realloc the
2404memory pointed to by C<ptr>, so that pointer should not be freed or used by
2405the programmer after giving it to sv_usepvn.
2406
2407 void sv_usepvn _((SV* sv, char* ptr, STRLEN len));
2408
2409=item sv_yes
2410
2411This is the C<true> SV. See C<sv_no>. Always refer to this as C<&sv_yes>.
2412
2413=item THIS
2414
2415Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
2416This is always the proper type for the C++ object. See C<CLASS> and
5fb8527f 2417L<perlxs/"Using XS With C++">.
cb1a09d0
AD
2418
2419=item toLOWER
2420
2421Converts the specified character to lowercase.
2422
2423 int toLOWER (char c)
2424
2425=item toUPPER
2426
2427Converts the specified character to uppercase.
2428
2429 int toUPPER (char c)
2430
2431=item warn
2432
2433This is the XSUB-writer's interface to Perl's C<warn> function. Use this
2434function the same way you use the C C<printf> function. See C<croak()>.
2435
2436=item XPUSHi
2437
2438Push an integer onto the stack, extending the stack if necessary. See
2439C<PUSHi>.
2440
2441 XPUSHi(int d)
2442
2443=item XPUSHn
2444
2445Push a double onto the stack, extending the stack if necessary. See
2446C<PUSHn>.
2447
2448 XPUSHn(double d)
2449
2450=item XPUSHp
2451
2452Push a string onto the stack, extending the stack if necessary. The C<len>
2453indicates the length of the string. See C<PUSHp>.
2454
2455 XPUSHp(char *c, int len)
2456
2457=item XPUSHs
2458
2459Push an SV onto the stack, extending the stack if necessary. See C<PUSHs>.
2460
2461 XPUSHs(sv)
2462
5fb8527f
PP
2463=item XS
2464
2465Macro to declare an XSUB and its C parameter list. This is handled by
2466C<xsubpp>.
2467
cb1a09d0
AD
2468=item XSRETURN
2469
2470Return from XSUB, indicating number of items on the stack. This is usually
2471handled by C<xsubpp>.
2472
5fb8527f 2473 XSRETURN(int x);
cb1a09d0
AD
2474
2475=item XSRETURN_EMPTY
2476
5fb8527f 2477Return an empty list from an XSUB immediately.
cb1a09d0
AD
2478
2479 XSRETURN_EMPTY;
2480
5fb8527f
PP
2481=item XSRETURN_IV
2482
2483Return an integer from an XSUB immediately. Uses C<XST_mIV>.
2484
2485 XSRETURN_IV(IV v);
2486
cb1a09d0
AD
2487=item XSRETURN_NO
2488
5fb8527f 2489Return C<&sv_no> from an XSUB immediately. Uses C<XST_mNO>.
cb1a09d0
AD
2490
2491 XSRETURN_NO;
2492
5fb8527f
PP
2493=item XSRETURN_NV
2494
2495Return an double from an XSUB immediately. Uses C<XST_mNV>.
2496
2497 XSRETURN_NV(NV v);
2498
2499=item XSRETURN_PV
2500
2501Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2502
2503 XSRETURN_PV(char *v);
2504
cb1a09d0
AD
2505=item XSRETURN_UNDEF
2506
5fb8527f 2507Return C<&sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
cb1a09d0
AD
2508
2509 XSRETURN_UNDEF;
2510
2511=item XSRETURN_YES
2512
5fb8527f 2513Return C<&sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
cb1a09d0
AD
2514
2515 XSRETURN_YES;
2516
5fb8527f
PP
2517=item XST_mIV
2518
2519Place an integer into the specified position C<i> on the stack. The value is
2520stored in a new mortal SV.
2521
2522 XST_mIV( int i, IV v );
2523
2524=item XST_mNV
2525
2526Place a double into the specified position C<i> on the stack. The value is
2527stored in a new mortal SV.
2528
2529 XST_mNV( int i, NV v );
2530
2531=item XST_mNO
2532
2533Place C<&sv_no> into the specified position C<i> on the stack.
2534
2535 XST_mNO( int i );
2536
2537=item XST_mPV
2538
2539Place a copy of a string into the specified position C<i> on the stack. The
2540value is stored in a new mortal SV.
2541
2542 XST_mPV( int i, char *v );
2543
2544=item XST_mUNDEF
2545
2546Place C<&sv_undef> into the specified position C<i> on the stack.
2547
2548 XST_mUNDEF( int i );
2549
2550=item XST_mYES
2551
2552Place C<&sv_yes> into the specified position C<i> on the stack.
2553
2554 XST_mYES( int i );
2555
2556=item XS_VERSION
2557
2558The version identifier for an XS module. This is usually handled
2559automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
2560
2561=item XS_VERSION_BOOTCHECK
2562
2563Macro to verify that a PM module's $VERSION variable matches the XS module's
2564C<XS_VERSION> variable. This is usually handled automatically by
2565C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
2566
cb1a09d0
AD
2567=item Zero
2568
2569The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
2570destination, C<n> is the number of items, and C<t> is the type.
2571
2572 (void) Zero( d, n, t );
2573
2574=back
2575
2576=head1 AUTHOR
2577
55497cff 2578Jeff Okamoto <okamoto@corp.hp.com>
cb1a09d0
AD
2579
2580With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2581Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
55497cff 2582Bowers, Matthew Green, Tim Bunce, Spider Boardman, and Ulrich Pfeifer.
cb1a09d0 2583
55497cff 2584API Listing by Dean Roehrich <roehrich@cray.com>.
cb1a09d0
AD
2585
2586=head1 DATE
2587
55497cff 2588Version 23.1: 1996/10/19