This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 5.003_06: pod/perldiag.pod
[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
LW
28
29=head2 Working with SV's
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
8e449b39 42To change the value of an I<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
70NUL's and not be terminated by a NUL.
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,
149or just weird results. Change the zero to C<&sv_undef> in the first line and
150all will be well.
151
152To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
153call is not necessary. See the section on B<MORTALITY>.
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
LW
174
175=head2 Working with AV's
176
177There are two ways to create and load an AV. The first method just creates
178an empty AV:
179
180 AV* newAV();
181
182The second method both creates the AV and initially populates it with SV's:
183
184 AV* av_make(I32 num, SV **ptr);
185
d1b91892
AD
186The second argument points to an array containing C<num> C<SV*>'s. Once the
187AV has been created, the SV's can be destroyed, if so desired.
a0d0e21e
LW
188
189Once the AV has been created, the following operations are possible on AV's:
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
cb1a09d0 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
227=head2 Working with HV's
228
229To create an HV, you use the following routine:
230
231 HV* newHV();
232
233Once the HV has been created, the following operations are possible on HV's:
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
244Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
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
348which class the reference will belong to. See the section on L<Stashes>
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
396 "Indentifier <varname> used only once: possible typo" warning.
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
d1b91892 405=head1 XSUB's 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
431macros to push IV's, doubles, strings, and SV pointers respectively:
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
451These macros automatically adjust the stack for you, if needed.
452
8e07c86e 453For more information, consult L<perlxs>.
d1b91892 454
a0d0e21e
LW
455=head1 Mortality
456
457In Perl, values are normally "immortal" -- that is, they are not freed unless
458explicitly done so (via the Perl C<undef> call or other routines in Perl
459itself).
460
d1b91892 461Add cruft about reference counts.
cb1a09d0
AD
462 int SvREFCNT(SV* sv);
463 void SvREFCNT_inc(SV* sv);
464 void SvREFCNT_dec(SV* sv);
d1b91892 465
a0d0e21e
LW
466In the above example with C<tzname>, we needed to create two new SV's to push
467onto the argument stack, that being the two strings. However, we don't want
468these new SV's to stick around forever because they will eventually be
469copied into the SV's that hold the two scalar variables.
470
471An SV (or AV or HV) that is "mortal" acts in all ways as a normal "immortal"
472SV, AV, or HV, but is only valid in the "current context". When the Perl
473interpreter leaves the current context, the mortal SV, AV, or HV is
474automatically freed. Generally the "current context" means a single
475Perl statement.
476
477To create a mortal variable, use the functions:
478
479 SV* sv_newmortal()
480 SV* sv_2mortal(SV*)
481 SV* sv_mortalcopy(SV*)
482
483The first call creates a mortal SV, the second converts an existing SV to
484a mortal SV, the third creates a mortal copy of an existing SV.
485
486The mortal routines are not just for SV's -- AV's and HV's can be made mortal
487by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or
488C<sv_mortalcopy> routines.
489
cb1a09d0 490>From Ilya:
d1b91892
AD
491Beware that the sv_2mortal() call is eventually equivalent to
492svREFCNT_dec(). A value can happily be mortal in two different contexts,
493and it will be svREFCNT_dec()ed twice, once on exit from these
494contexts. It can also be mortal twice in the same context. This means
495that you should be very careful to make a value mortal exactly as many
496times as it is needed. The value that go to the Perl stack I<should>
497be mortal.
a0d0e21e 498
d1b91892
AD
499You should be careful about creating mortal variables. It is possible for
500strange things to happen should you make the same value mortal within
501multiple contexts.
a0d0e21e 502
cb1a09d0 503=head1 Stashes
a0d0e21e
LW
504
505A stash is a hash table (associative array) that contains all of the
506different objects that are contained within a package. Each key of the
d1b91892
AD
507stash is a symbol name (shared by all the different types of objects
508that have the same name), and each value in the hash table is called a
509GV (for Glob Value). This GV in turn contains references to the various
510objects of that name, including (but not limited to) the following:
cb1a09d0 511
a0d0e21e
LW
512 Scalar Value
513 Array Value
514 Hash Value
515 File Handle
516 Directory Handle
517 Format
518 Subroutine
519
d1b91892
AD
520Perl stores various stashes in a separate GV structure (for global
521variable) but represents them with an HV structure. The keys in this
522larger GV are the various package names; the values are the C<GV*>'s
523which are stashes. It may help to think of a stash purely as an HV,
524and that the term "GV" means the global variable hash.
a0d0e21e 525
d1b91892 526To get the stash pointer for a particular package, use the function:
a0d0e21e
LW
527
528 HV* gv_stashpv(char* name, I32 create)
529 HV* gv_stashsv(SV*, I32 create)
530
531The first function takes a literal string, the second uses the string stored
d1b91892 532in the SV. Remember that a stash is just a hash table, so you get back an
cb1a09d0 533C<HV*>. The C<create> flag will create a new package if it is set.
a0d0e21e
LW
534
535The name that C<gv_stash*v> wants is the name of the package whose symbol table
536you want. The default package is called C<main>. If you have multiply nested
d1b91892
AD
537packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
538language itself.
a0d0e21e
LW
539
540Alternately, if you have an SV that is a blessed reference, you can find
541out the stash pointer by using:
542
543 HV* SvSTASH(SvRV(SV*));
544
545then use the following to get the package name itself:
546
547 char* HvNAME(HV* stash);
548
549If you need to return a blessed value to your Perl script, you can use the
550following function:
551
552 SV* sv_bless(SV*, HV* stash)
553
554where the first argument, an C<SV*>, must be a reference, and the second
555argument is a stash. The returned C<SV*> can now be used in the same way
556as any other SV.
557
d1b91892
AD
558For more information on references and blessings, consult L<perlref>.
559
a0d0e21e
LW
560=head1 Magic
561
d1b91892
AD
562[This section still under construction. Ignore everything here. Post no
563bills. Everything not permitted is forbidden.]
564
565# Version 6, 1995/1/27
566
567Any SV may be magical, that is, it has special features that a normal
568SV does not have. These features are stored in the SV structure in a
569linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
570
571 struct magic {
572 MAGIC* mg_moremagic;
573 MGVTBL* mg_virtual;
574 U16 mg_private;
575 char mg_type;
576 U8 mg_flags;
577 SV* mg_obj;
578 char* mg_ptr;
579 I32 mg_len;
580 };
581
582Note this is current as of patchlevel 0, and could change at any time.
583
584=head2 Assigning Magic
585
586Perl adds magic to an SV using the sv_magic function:
587
588 void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen);
589
590The C<sv> argument is a pointer to the SV that is to acquire a new magical
591feature.
592
593If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
594set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
595it to the beginning of the linked list of magical features. Any prior
596entry of the same type of magic is deleted. Note that this can be
597overriden, and multiple instances of the same type of magic can be
598associated with an SV.
599
600The C<name> and C<namlem> arguments are used to associate a string with
601the magic, typically the name of a variable. C<namlem> is stored in the
602C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
603copy of the name is stored in C<mg_ptr> field.
604
605The sv_magic function uses C<how> to determine which, if any, predefined
606"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
cb1a09d0
AD
607See the "Magic Virtual Table" section below. The C<how> argument is also
608stored in the C<mg_type> field.
d1b91892
AD
609
610The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
611structure. If it is not the same as the C<sv> argument, the reference
612count of the C<obj> object is incremented. If it is the same, or if
613the C<how> argument is "#", or if it is a null pointer, then C<obj> is
614merely stored, without the reference count being incremented.
615
cb1a09d0
AD
616There is also a function to add magic to an C<HV>:
617
618 void hv_magic(HV *hv, GV *gv, int how);
619
620This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
621
622To remove the magic from an SV, call the function sv_unmagic:
623
624 void sv_unmagic(SV *sv, int type);
625
626The C<type> argument should be equal to the C<how> value when the C<SV>
627was initially made magical.
628
d1b91892
AD
629=head2 Magic Virtual Tables
630
631The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
632C<MGVTBL>, which is a structure of function pointers and stands for
633"Magic Virtual Table" to handle the various operations that might be
634applied to that variable.
635
636The C<MGVTBL> has five pointers to the following routine types:
637
638 int (*svt_get)(SV* sv, MAGIC* mg);
639 int (*svt_set)(SV* sv, MAGIC* mg);
640 U32 (*svt_len)(SV* sv, MAGIC* mg);
641 int (*svt_clear)(SV* sv, MAGIC* mg);
642 int (*svt_free)(SV* sv, MAGIC* mg);
643
644This MGVTBL structure is set at compile-time in C<perl.h> and there are
645currently 19 types (or 21 with overloading turned on). These different
646structures contain pointers to various routines that perform additional
647actions depending on which function is being called.
648
649 Function pointer Action taken
650 ---------------- ------------
651 svt_get Do something after the value of the SV is retrieved.
652 svt_set Do something after the SV is assigned a value.
653 svt_len Report on the SV's length.
654 svt_clear Clear something the SV represents.
655 svt_free Free any extra storage associated with the SV.
656
657For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
658to an C<mg_type> of '\0') contains:
659
660 { magic_get, magic_set, magic_len, 0, 0 }
661
662Thus, when an SV is determined to be magical and of type '\0', if a get
663operation is being performed, the routine C<magic_get> is called. All
664the various routines for the various magical types begin with C<magic_>.
665
666The current kinds of Magic Virtual Tables are:
667
668 mg_type MGVTBL Type of magicalness
669 ------- ------ -------------------
670 \0 vtbl_sv Regexp???
671 A vtbl_amagic Operator Overloading
672 a vtbl_amagicelem Operator Overloading
673 c 0 Used in Operator Overloading
674 B vtbl_bm Boyer-Moore???
675 E vtbl_env %ENV hash
676 e vtbl_envelem %ENV hash element
677 g vtbl_mglob Regexp /g flag???
678 I vtbl_isa @ISA array
679 i vtbl_isaelem @ISA array element
680 L 0 (but sets RMAGICAL) Perl Module/Debugger???
681 l vtbl_dbline Debugger?
682 P vtbl_pack Tied Array or Hash
683 p vtbl_packelem Tied Array or Hash element
684 q vtbl_packelem Tied Scalar or Handle
685 S vtbl_sig Signal Hash
686 s vtbl_sigelem Signal Hash element
687 t vtbl_taint Taintedness
688 U vtbl_uvar ???
689 v vtbl_vec Vector
690 x vtbl_substr Substring???
691 * vtbl_glob GV???
692 # vtbl_arylen Array Length
693 . vtbl_pos $. scalar variable
694 ~ Reserved for extensions, but multiple extensions may clash
695
696When an upper-case and lower-case letter both exist in the table, then the
697upper-case letter is used to represent some kind of composite type (a list
698or a hash), and the lower-case letter is used to represent an element of
699that composite type.
700
701=head2 Finding Magic
702
703 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
704
705This routine returns a pointer to the C<MAGIC> structure stored in the SV.
706If the SV does not have that magical feature, C<NULL> is returned. Also,
707if the SV is not of type SVt_PVMG, Perl may core-dump.
708
709 int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen);
710
711This routine checks to see what types of magic C<sv> has. If the mg_type
712field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
713the mg_type field is changed to be the lower-case letter.
a0d0e21e
LW
714
715=head1 Double-Typed SV's
716
717Scalar variables normally contain only one type of value, an integer,
718double, pointer, or reference. Perl will automatically convert the
719actual scalar data from the stored type into the requested type.
720
721Some scalar variables contain more than one type of scalar data. For
722example, the variable C<$!> contains either the numeric value of C<errno>
d1b91892 723or its string equivalent from either C<strerror> or C<sys_errlist[]>.
a0d0e21e
LW
724
725To force multiple data values into an SV, you must do two things: use the
726C<sv_set*v> routines to add the additional scalar type, then set a flag
727so that Perl will believe it contains more than one type of data. The
728four macros to set the flags are:
729
730 SvIOK_on
731 SvNOK_on
732 SvPOK_on
733 SvROK_on
734
735The particular macro you must use depends on which C<sv_set*v> routine
736you called first. This is because every C<sv_set*v> routine turns on
737only the bit for the particular type of data being set, and turns off
738all the rest.
739
740For example, to create a new Perl variable called "dberror" that contains
741both the numeric and descriptive string error values, you could use the
742following code:
743
744 extern int dberror;
745 extern char *dberror_list;
746
747 SV* sv = perl_get_sv("dberror", TRUE);
748 sv_setiv(sv, (IV) dberror);
749 sv_setpv(sv, dberror_list[dberror]);
750 SvIOK_on(sv);
751
752If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
753macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
754
755=head1 Calling Perl Routines from within C Programs
756
757There are four routines that can be used to call a Perl subroutine from
758within a C program. These four are:
759
760 I32 perl_call_sv(SV*, I32);
761 I32 perl_call_pv(char*, I32);
762 I32 perl_call_method(char*, I32);
763 I32 perl_call_argv(char*, I32, register char**);
764
d1b91892
AD
765The routine most often used is C<perl_call_sv>. The C<SV*> argument
766contains either the name of the Perl subroutine to be called, or a
767reference to the subroutine. The second argument consists of flags
768that control the context in which the subroutine is called, whether
769or not the subroutine is being passed arguments, how errors should be
770trapped, and how to treat return values.
a0d0e21e
LW
771
772All four routines return the number of arguments that the subroutine returned
773on the Perl stack.
774
d1b91892
AD
775When using any of these routines (except C<perl_call_argv>), the programmer
776must manipulate the Perl stack. These include the following macros and
777functions:
a0d0e21e
LW
778
779 dSP
780 PUSHMARK()
781 PUTBACK
782 SPAGAIN
783 ENTER
784 SAVETMPS
785 FREETMPS
786 LEAVE
787 XPUSH*()
cb1a09d0 788 POP*()
a0d0e21e
LW
789
790For more information, consult L<perlcall>.
791
792=head1 Memory Allocation
793
d1b91892
AD
794It is strongly suggested that you use the version of malloc that is distributed
795with Perl. It keeps pools of various sizes of unallocated memory in order to
796more quickly satisfy allocation requests.
797However, on some platforms, it may cause spurious malloc or free errors.
798
799 New(x, pointer, number, type);
800 Newc(x, pointer, number, type, cast);
801 Newz(x, pointer, number, type);
802
803These three macros are used to initially allocate memory. The first argument
804C<x> was a "magic cookie" that was used to keep track of who called the macro,
805to help when debugging memory problems. However, the current code makes no
806use of this feature (Larry has switched to using a run-time memory checker),
807so this argument can be any number.
808
809The second argument C<pointer> will point to the newly allocated memory.
810The third and fourth arguments C<number> and C<type> specify how many of
811the specified type of data structure should be allocated. The argument
812C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
813should be used if the C<pointer> argument is different from the C<type>
814argument.
815
816Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
817to zero out all the newly allocated memory.
818
819 Renew(pointer, number, type);
820 Renewc(pointer, number, type, cast);
821 Safefree(pointer)
822
823These three macros are used to change a memory buffer size or to free a
824piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
825match those of C<New> and C<Newc> with the exception of not needing the
826"magic cookie" argument.
827
828 Move(source, dest, number, type);
829 Copy(source, dest, number, type);
830 Zero(dest, number, type);
831
832These three macros are used to move, copy, or zero out previously allocated
833memory. The C<source> and C<dest> arguments point to the source and
834destination starting points. Perl will move, copy, or zero out C<number>
835instances of the size of the C<type> data structure (using the C<sizeof>
836function).
a0d0e21e 837
cb1a09d0 838=head1 API LISTING
a0d0e21e 839
cb1a09d0
AD
840This is a listing of functions, macros, flags, and variables that may be
841useful to extension writers or that may be found while reading other
842extensions.
a0d0e21e 843
cb1a09d0 844=over 8
a0d0e21e 845
cb1a09d0
AD
846=item AvFILL
847
848See C<av_len>.
849
850=item av_clear
851
852Clears an array, making it empty.
853
854 void av_clear _((AV* ar));
855
856=item av_extend
857
858Pre-extend an array. The C<key> is the index to which the array should be
859extended.
860
861 void av_extend _((AV* ar, I32 key));
862
863=item av_fetch
864
865Returns the SV at the specified index in the array. The C<key> is the
866index. If C<lval> is set then the fetch will be part of a store. Check
867that the return value is non-null before dereferencing it to a C<SV*>.
868
869 SV** av_fetch _((AV* ar, I32 key, I32 lval));
870
871=item av_len
872
873Returns the highest index in the array. Returns -1 if the array is empty.
874
875 I32 av_len _((AV* ar));
876
877=item av_make
878
879Creats a new AV and populates it with a list of SVs. The SVs are copied
880into the array, so they may be freed after the call to av_make.
881
882 AV* av_make _((I32 size, SV** svp));
883
884=item av_pop
885
886Pops an SV off the end of the array. Returns C<&sv_undef> if the array is
887empty.
888
889 SV* av_pop _((AV* ar));
890
891=item av_push
892
893Pushes an SV onto the end of the array.
894
895 void av_push _((AV* ar, SV* val));
896
897=item av_shift
898
899Shifts an SV off the beginning of the array.
900
901 SV* av_shift _((AV* ar));
902
903=item av_store
904
905Stores an SV in an array. The array index is specified as C<key>. The
906return value will be null if the operation failed, otherwise it can be
907dereferenced to get the original C<SV*>.
908
909 SV** av_store _((AV* ar, I32 key, SV* val));
910
911=item av_undef
912
913Undefines the array.
914
915 void av_undef _((AV* ar));
916
917=item av_unshift
918
919Unshift an SV onto the beginning of the array.
920
921 void av_unshift _((AV* ar, I32 num));
922
923=item CLASS
924
925Variable which is setup by C<xsubpp> to indicate the class name for a C++ XS
926constructor. This is always a C<char*>. See C<THIS> and L<perlxs>.
927
928=item Copy
929
930The XSUB-writer's interface to the C C<memcpy> function. The C<s> is the
931source, C<d> is the destination, C<n> is the number of items, and C<t> is
932the type.
933
934 (void) Copy( s, d, n, t );
935
936=item croak
937
938This is the XSUB-writer's interface to Perl's C<die> function. Use this
939function the same way you use the C C<printf> function. See C<warn>.
940
941=item CvSTASH
942
943Returns the stash of the CV.
944
945 HV * CvSTASH( SV* sv )
946
947=item DBsingle
948
949When Perl is run in debugging mode, with the B<-d> switch, this SV is a
950boolean which indicates whether subs are being single-stepped.
951Single-stepping is automatically turned on after every step. See C<DBsub>.
952
953=item DBsub
954
955When Perl is run in debugging mode, with the B<-d> switch, this GV contains
956the SV which holds the name of the sub being debugged. See C<DBsingle>.
957The sub name can be found by
958
959 SvPV( GvSV( DBsub ), na )
960
961=item dMARK
962
963Declare a stack marker for the XSUB. See C<MARK> and C<dORIGMARK>.
964
965=item dORIGMARK
966
967Saves the original stack mark for the XSUB. See C<ORIGMARK>.
968
969=item dSP
970
971Declares a stack pointer for the XSUB. See C<SP>.
972
973=item dXSARGS
974
975Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is
976usually handled automatically by C<xsubpp>. Declares the C<items> variable
977to indicate the number of items on the stack.
978
979=item ENTER
980
981Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
982
983 ENTER;
984
985=item EXTEND
986
987Used to extend the argument stack for an XSUB's return values.
988
989 EXTEND( sp, int x );
990
991=item FREETMPS
992
993Closing bracket for temporaries on a callback. See C<SAVETMPS> and
994L<perlcall>.
995
996 FREETMPS;
997
998=item G_ARRAY
999
1000Used to indicate array context. See C<GIMME> and L<perlcall>.
1001
1002=item G_DISCARD
1003
1004Indicates that arguments returned from a callback should be discarded. See
1005L<perlcall>.
1006
1007=item G_EVAL
1008
1009Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>.
1010
1011=item GIMME
1012
1013The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_SCALAR> or
1014C<G_ARRAY> for scalar or array context.
1015
1016=item G_NOARGS
1017
1018Indicates that no arguments are being sent to a callback. See L<perlcall>.
1019
1020=item G_SCALAR
1021
1022Used to indicate scalar context. See C<GIMME> and L<perlcall>.
1023
1024=item gv_stashpv
1025
1026Returns a pointer to the stash for a specified package. If C<create> is set
1027then the package will be created if it does not already exist. If C<create>
1028is not set and the package does not exist then NULL is returned.
1029
1030 HV* gv_stashpv _((char* name, I32 create));
1031
1032=item gv_stashsv
1033
1034Returns a pointer to the stash for a specified package. See C<gv_stashpv>.
1035
1036 HV* gv_stashsv _((SV* sv, I32 create));
1037
1038=item GvSV
1039
1040Return the SV from the GV.
1041
1042=item he_free
1043
1044Releases a hash entry from an iterator. See C<hv_iternext>.
1045
1046=item hv_clear
1047
1048Clears a hash, making it empty.
1049
1050 void hv_clear _((HV* tb));
1051
1052=item hv_delete
1053
1054Deletes a key/value pair in the hash. The value SV is removed from the hash
1055and returned to the caller. The C<lken> is the length of the key. The
1056C<flags> value will normally be zero; if set to G_DISCARD then null will be
1057returned.
1058
1059 SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags));
1060
1061=item hv_exists
1062
1063Returns a boolean indicating whether the specified hash key exists. The
1064C<lken> is the length of the key.
1065
1066 bool hv_exists _((HV* tb, char* key, U32 klen));
1067
1068=item hv_fetch
1069
1070Returns the SV which corresponds to the specified key in the hash. The
1071C<lken> is the length of the key. If C<lval> is set then the fetch will be
1072part of a store. Check that the return value is non-null before
1073dereferencing it to a C<SV*>.
1074
1075 SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval));
1076
1077=item hv_iterinit
1078
1079Prepares a starting point to traverse a hash table.
1080
1081 I32 hv_iterinit _((HV* tb));
1082
1083=item hv_iterkey
1084
1085Returns the key from the current position of the hash iterator. See
1086C<hv_iterinit>.
1087
1088 char* hv_iterkey _((HE* entry, I32* retlen));
1089
1090=item hv_iternext
1091
1092Returns entries from a hash iterator. See C<hv_iterinit>.
1093
1094 HE* hv_iternext _((HV* tb));
1095
1096=item hv_iternextsv
1097
1098Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1099operation.
1100
1101 SV * hv_iternextsv _((HV* hv, char** key, I32* retlen));
1102
1103=item hv_iterval
1104
1105Returns the value from the current position of the hash iterator. See
1106C<hv_iterkey>.
1107
1108 SV* hv_iterval _((HV* tb, HE* entry));
1109
1110=item hv_magic
1111
1112Adds magic to a hash. See C<sv_magic>.
1113
1114 void hv_magic _((HV* hv, GV* gv, int how));
1115
1116=item HvNAME
1117
1118Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
1119
1120 char *HvNAME (HV* stash)
1121
1122=item hv_store
1123
1124Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1125the length of the key. The C<hash> parameter is the pre-computed hash
1126value; if it is zero then Perl will compute it. The return value will be
1127null if the operation failed, otherwise it can be dereferenced to get the
1128original C<SV*>.
1129
1130 SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash));
1131
1132=item hv_undef
1133
1134Undefines the hash.
1135
1136 void hv_undef _((HV* tb));
1137
1138=item isALNUM
1139
1140Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
1141character or digit.
1142
1143 int isALNUM (char c)
1144
1145=item isALPHA
1146
1147Returns a boolean indicating whether the C C<char> is an ascii alphanumeric
1148character.
1149
1150 int isALPHA (char c)
1151
1152=item isDIGIT
1153
1154Returns a boolean indicating whether the C C<char> is an ascii digit.
1155
1156 int isDIGIT (char c)
1157
1158=item isLOWER
1159
1160Returns a boolean indicating whether the C C<char> is a lowercase character.
1161
1162 int isLOWER (char c)
1163
1164=item isSPACE
1165
1166Returns a boolean indicating whether the C C<char> is whitespace.
1167
1168 int isSPACE (char c)
1169
1170=item isUPPER
1171
1172Returns a boolean indicating whether the C C<char> is an uppercase character.
1173
1174 int isUPPER (char c)
1175
1176=item items
1177
1178Variable which is setup by C<xsubpp> to indicate the number of items on the
1179stack. See L<perlxs>.
1180
1181=item LEAVE
1182
1183Closing bracket on a callback. See C<ENTER> and L<perlcall>.
1184
1185 LEAVE;
1186
1187=item MARK
1188
1189Stack marker for the XSUB. See C<dMARK>.
1190
1191=item mg_clear
1192
1193Clear something magical that the SV represents. See C<sv_magic>.
1194
1195 int mg_clear _((SV* sv));
1196
1197=item mg_copy
1198
1199Copies the magic from one SV to another. See C<sv_magic>.
1200
1201 int mg_copy _((SV *, SV *, char *, STRLEN));
1202
1203=item mg_find
1204
1205Finds the magic pointer for type matching the SV. See C<sv_magic>.
1206
1207 MAGIC* mg_find _((SV* sv, int type));
1208
1209=item mg_free
1210
1211Free any magic storage used by the SV. See C<sv_magic>.
1212
1213 int mg_free _((SV* sv));
1214
1215=item mg_get
1216
1217Do magic after a value is retrieved from the SV. See C<sv_magic>.
1218
1219 int mg_get _((SV* sv));
1220
1221=item mg_len
1222
1223Report on the SV's length. See C<sv_magic>.
1224
1225 U32 mg_len _((SV* sv));
1226
1227=item mg_magical
1228
1229Turns on the magical status of an SV. See C<sv_magic>.
1230
1231 void mg_magical _((SV* sv));
1232
1233=item mg_set
1234
1235Do magic after a value is assigned to the SV. See C<sv_magic>.
1236
1237 int mg_set _((SV* sv));
1238
1239=item Move
1240
1241The XSUB-writer's interface to the C C<memmove> function. The C<s> is the
1242source, C<d> is the destination, C<n> is the number of items, and C<t> is
1243the type.
1244
1245 (void) Move( s, d, n, t );
1246
1247=item na
1248
1249A variable which may be used with C<SvPV> to tell Perl to calculate the
1250string length.
1251
1252=item New
1253
1254The XSUB-writer's interface to the C C<malloc> function.
1255
1256 void * New( x, void *ptr, int size, type )
1257
1258=item Newc
1259
1260The XSUB-writer's interface to the C C<malloc> function, with cast.
1261
1262 void * Newc( x, void *ptr, int size, type, cast )
1263
1264=item Newz
1265
1266The XSUB-writer's interface to the C C<malloc> function. The allocated
1267memory is zeroed with C<memzero>.
1268
1269 void * Newz( x, void *ptr, int size, type )
1270
1271=item newAV
1272
1273Creates a new AV. The refcount is set to 1.
1274
1275 AV* newAV _((void));
1276
1277=item newHV
1278
1279Creates a new HV. The refcount is set to 1.
1280
1281 HV* newHV _((void));
1282
1283=item newRV
1284
1285Creates an RV wrapper for an SV. The refcount for the original SV is
1286incremented.
1287
1288 SV* newRV _((SV* ref));
1289
1290=item newSV
1291
1292Creates a new SV. The C<len> parameter indicates the number of bytes of
1293pre-allocated string space the SV should have. The refcount for the new SV
1294is set to 1.
1295
1296 SV* newSV _((STRLEN len));
1297
1298=item newSViv
1299
1300Creates a new SV and copies an integer into it. The refcount for the SV is
1301set to 1.
1302
1303 SV* newSViv _((IV i));
1304
1305=item newSVnv
1306
1307Creates a new SV and copies a double into it. The refcount for the SV is
1308set to 1.
1309
1310 SV* newSVnv _((NV i));
1311
1312=item newSVpv
1313
1314Creates a new SV and copies a string into it. The refcount for the SV is
1315set to 1. If C<len> is zero then Perl will compute the length.
1316
1317 SV* newSVpv _((char* s, STRLEN len));
1318
1319=item newSVrv
1320
1321Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
1322it will be upgraded one. If C<classname> is non-null then the new SV will
1323be blessed in the specified package. The new SV is returned and its
1324refcount is 1.
1325
1326 SV* newSVrv _((SV* rv, char* classname));
1327
1328=item newSVsv
1329
1330Creates a new SV which is an exact duplicate of the orignal SV.
1331
1332 SV* newSVsv _((SV* old));
1333
1334=item newXS
1335
1336Used by C<xsubpp> to hook up XSUBs as Perl subs.
1337
1338=item newXSproto
1339
1340Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1341the subs.
1342
1343=item Nullav
1344
1345Null AV pointer.
1346
1347=item Nullch
1348
1349Null character pointer.
1350
1351=item Nullcv
1352
1353Null CV pointer.
1354
1355=item Nullhv
1356
1357Null HV pointer.
1358
1359=item Nullsv
1360
1361Null SV pointer.
1362
1363=item ORIGMARK
1364
1365The original stack mark for the XSUB. See C<dORIGMARK>.
1366
1367=item perl_alloc
1368
1369Allocates a new Perl interpreter. See L<perlembed>.
1370
1371=item perl_call_argv
1372
1373Performs a callback to the specified Perl sub. See L<perlcall>.
1374
1375 I32 perl_call_argv _((char* subname, I32 flags, char** argv));
1376
1377=item perl_call_method
1378
1379Performs a callback to the specified Perl method. The blessed object must
1380be on the stack. See L<perlcall>.
1381
1382 I32 perl_call_method _((char* methname, I32 flags));
1383
1384=item perl_call_pv
1385
1386Performs a callback to the specified Perl sub. See L<perlcall>.
1387
1388 I32 perl_call_pv _((char* subname, I32 flags));
1389
1390=item perl_call_sv
1391
1392Performs a callback to the Perl sub whose name is in the SV. See
1393L<perlcall>.
1394
1395 I32 perl_call_sv _((SV* sv, I32 flags));
1396
1397=item perl_construct
1398
1399Initializes a new Perl interpreter. See L<perlembed>.
1400
1401=item perl_destruct
1402
1403Shuts down a Perl interpreter. See L<perlembed>.
1404
1405=item perl_eval_sv
1406
1407Tells Perl to C<eval> the string in the SV.
1408
1409 I32 perl_eval_sv _((SV* sv, I32 flags));
1410
1411=item perl_free
1412
1413Releases a Perl interpreter. See L<perlembed>.
1414
1415=item perl_get_av
1416
1417Returns the AV of the specified Perl array. If C<create> is set and the
1418Perl variable does not exist then it will be created. If C<create> is not
1419set and the variable does not exist then null is returned.
1420
1421 AV* perl_get_av _((char* name, I32 create));
1422
1423=item perl_get_cv
1424
1425Returns the CV of the specified Perl sub. If C<create> is set and the Perl
1426variable does not exist then it will be created. If C<create> is not
1427set and the variable does not exist then null is returned.
1428
1429 CV* perl_get_cv _((char* name, I32 create));
1430
1431=item perl_get_hv
1432
1433Returns the HV of the specified Perl hash. If C<create> is set and the Perl
1434variable does not exist then it will be created. If C<create> is not
1435set and the variable does not exist then null is returned.
1436
1437 HV* perl_get_hv _((char* name, I32 create));
1438
1439=item perl_get_sv
1440
1441Returns the SV of the specified Perl scalar. If C<create> is set and the
1442Perl variable does not exist then it will be created. If C<create> is not
1443set and the variable does not exist then null is returned.
1444
1445 SV* perl_get_sv _((char* name, I32 create));
1446
1447=item perl_parse
1448
1449Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1450
1451=item perl_require_pv
1452
1453Tells Perl to C<require> a module.
1454
1455 void perl_require_pv _((char* pv));
1456
1457=item perl_run
1458
1459Tells a Perl interpreter to run. See L<perlembed>.
1460
1461=item POPi
1462
1463Pops an integer off the stack.
1464
1465 int POPi();
1466
1467=item POPl
1468
1469Pops a long off the stack.
1470
1471 long POPl();
1472
1473=item POPp
1474
1475Pops a string off the stack.
1476
1477 char * POPp();
1478
1479=item POPn
1480
1481Pops a double off the stack.
1482
1483 double POPn();
1484
1485=item POPs
1486
1487Pops an SV off the stack.
1488
1489 SV* POPs();
1490
1491=item PUSHMARK
1492
1493Opening bracket for arguments on a callback. See C<PUTBACK> and L<perlcall>.
1494
1495 PUSHMARK(p)
1496
1497=item PUSHi
1498
1499Push an integer onto the stack. The stack must have room for this element.
1500See C<XPUSHi>.
1501
1502 PUSHi(int d)
1503
1504=item PUSHn
1505
1506Push a double onto the stack. The stack must have room for this element.
1507See C<XPUSHn>.
1508
1509 PUSHn(double d)
1510
1511=item PUSHp
1512
1513Push a string onto the stack. The stack must have room for this element.
1514The C<len> indicates the length of the string. See C<XPUSHp>.
1515
1516 PUSHp(char *c, int len )
1517
1518=item PUSHs
1519
1520Push an SV onto the stack. The stack must have room for this element. See
1521C<XPUSHs>.
1522
1523 PUSHs(sv)
1524
1525=item PUTBACK
1526
1527Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1528See C<PUSHMARK> and L<perlcall> for other uses.
1529
1530 PUTBACK;
1531
1532=item Renew
1533
1534The XSUB-writer's interface to the C C<realloc> function.
1535
1536 void * Renew( void *ptr, int size, type )
1537
1538=item Renewc
1539
1540The XSUB-writer's interface to the C C<realloc> function, with cast.
1541
1542 void * Renewc( void *ptr, int size, type, cast )
1543
1544=item RETVAL
1545
1546Variable which is setup by C<xsubpp> to hold the return value for an XSUB.
1547This is always the proper type for the XSUB. See L<perlxs>.
1548
1549=item safefree
1550
1551The XSUB-writer's interface to the C C<free> function.
1552
1553=item safemalloc
1554
1555The XSUB-writer's interface to the C C<malloc> function.
1556
1557=item saferealloc
1558
1559The XSUB-writer's interface to the C C<realloc> function.
1560
1561=item savepv
1562
1563Copy a string to a safe spot. This does not use an SV.
1564
1565 char* savepv _((char* sv));
1566
1567=item savepvn
1568
1569Copy a string to a safe spot. The C<len> indicates number of bytes to
1570copy. This does not use an SV.
1571
1572 char* savepvn _((char* sv, I32 len));
1573
1574=item SAVETMPS
1575
1576Opening bracket for temporaries on a callback. See C<FREETMPS> and
1577L<perlcall>.
1578
1579 SAVETMPS;
1580
1581=item SP
1582
1583Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1584C<SPAGAIN>.
1585
1586=item SPAGAIN
1587
1588Refetch the stack pointer. Used after a callback. See L<perlcall>.
1589
1590 SPAGAIN;
1591
1592=item ST
1593
1594Used to access elements on the XSUB's stack.
1595
1596 SV* ST(int x)
1597
1598=item strEQ
1599
1600Test two strings to see if they are equal. Returns true or false.
1601
1602 int strEQ( char *s1, char *s2 )
1603
1604=item strGE
1605
1606Test two strings to see if the first, C<s1>, is greater than or equal to the
1607second, C<s2>. Returns true or false.
1608
1609 int strGE( char *s1, char *s2 )
1610
1611=item strGT
1612
1613Test two strings to see if the first, C<s1>, is greater than the second,
1614C<s2>. Returns true or false.
1615
1616 int strGT( char *s1, char *s2 )
1617
1618=item strLE
1619
1620Test two strings to see if the first, C<s1>, is less than or equal to the
1621second, C<s2>. Returns true or false.
1622
1623 int strLE( char *s1, char *s2 )
1624
1625=item strLT
1626
1627Test two strings to see if the first, C<s1>, is less than the second,
1628C<s2>. Returns true or false.
1629
1630 int strLT( char *s1, char *s2 )
1631
1632=item strNE
1633
1634Test two strings to see if they are different. Returns true or false.
1635
1636 int strNE( char *s1, char *s2 )
1637
1638=item strnEQ
1639
1640Test two strings to see if they are equal. The C<len> parameter indicates
1641the number of bytes to compare. Returns true or false.
1642
1643 int strnEQ( char *s1, char *s2 )
1644
1645=item strnNE
1646
1647Test two strings to see if they are different. The C<len> parameter
1648indicates the number of bytes to compare. Returns true or false.
1649
1650 int strnNE( char *s1, char *s2, int len )
1651
1652=item sv_2mortal
1653
1654Marks an SV as mortal. The SV will be destroyed when the current context
1655ends.
1656
1657 SV* sv_2mortal _((SV* sv));
1658
1659=item sv_bless
1660
1661Blesses an SV into a specified package. The SV must be an RV. The package
1662must be designated by its stash (see C<gv_stashpv()>). The refcount of the
1663SV is unaffected.
1664
1665 SV* sv_bless _((SV* sv, HV* stash));
1666
1667=item sv_catpv
1668
1669Concatenates the string onto the end of the string which is in the SV.
1670
1671 void sv_catpv _((SV* sv, char* ptr));
1672
1673=item sv_catpvn
1674
1675Concatenates the string onto the end of the string which is in the SV. The
1676C<len> indicates number of bytes to copy.
1677
1678 void sv_catpvn _((SV* sv, char* ptr, STRLEN len));
1679
1680=item sv_catsv
1681
1682Concatentates the string from SV C<ssv> onto the end of the string in SV
1683C<dsv>.
1684
1685 void sv_catsv _((SV* dsv, SV* ssv));
1686
1687=item SvCUR
1688
1689Returns the length of the string which is in the SV. See C<SvLEN>.
1690
1691 int SvCUR (SV* sv)
1692
1693=item SvCUR_set
1694
1695Set the length of the string which is in the SV. See C<SvCUR>.
1696
1697 SvCUR_set (SV* sv, int val )
1698
1699=item SvEND
1700
1701Returns a pointer to the last character in the string which is in the SV.
1702See C<SvCUR>. Access the character as
1703
1704 *SvEND(sv)
1705
1706=item SvGROW
1707
1708Expands the character buffer in the SV.
1709
1710 char * SvGROW( SV* sv, int len )
1711
1712=item SvIOK
1713
1714Returns a boolean indicating whether the SV contains an integer.
1715
1716 int SvIOK (SV* SV)
1717
1718=item SvIOK_off
1719
1720Unsets the IV status of an SV.
1721
1722 SvIOK_off (SV* sv)
1723
1724=item SvIOK_on
1725
1726Tells an SV that it is an integer.
1727
1728 SvIOK_on (SV* sv)
1729
1730=item SvIOKp
1731
1732Returns a boolean indicating whether the SV contains an integer. Checks the
1733B<private> setting. Use C<SvIOK>.
1734
1735 int SvIOKp (SV* SV)
1736
1737=item sv_isa
1738
1739Returns a boolean indicating whether the SV is blessed into the specified
1740class. This does not know how to check for subtype, so it doesn't work in
1741an inheritance relationship.
1742
1743 int sv_isa _((SV* sv, char* name));
1744
1745=item SvIV
1746
1747Returns the integer which is in the SV.
1748
1749 int SvIV (SV* sv)
1750
1751=item sv_isobject
1752
1753Returns a boolean indicating whether the SV is an RV pointing to a blessed
1754object. If the SV is not an RV, or if the object is not blessed, then this
1755will return false.
1756
1757 int sv_isobject _((SV* sv));
1758
1759=item SvIVX
1760
1761Returns the integer which is stored in the SV.
1762
1763 int SvIVX (SV* sv);
1764
1765=item SvLEN
1766
1767Returns the size of the string buffer in the SV. See C<SvCUR>.
1768
1769 int SvLEN (SV* sv)
1770
1771=item sv_magic
1772
1773Adds magic to an SV.
1774
1775 void sv_magic _((SV* sv, SV* obj, int how, char* name, I32 namlen));
1776
1777=item sv_mortalcopy
1778
1779Creates a new SV which is a copy of the original SV. The new SV is marked
1780as mortal.
1781
1782 SV* sv_mortalcopy _((SV* oldsv));
1783
1784=item SvOK
1785
1786Returns a boolean indicating whether the value is an SV.
1787
1788 int SvOK (SV* sv)
1789
1790=item sv_newmortal
1791
1792Creates a new SV which is mortal. The refcount of the SV is set to 1.
1793
1794 SV* sv_newmortal _((void));
1795
1796=item sv_no
1797
1798This is the C<false> SV. See C<sv_yes>. Always refer to this as C<&sv_no>.
1799
1800=item SvNIOK
1801
1802Returns a boolean indicating whether the SV contains a number, integer or
1803double.
1804
1805 int SvNIOK (SV* SV)
1806
1807=item SvNIOK_off
1808
1809Unsets the NV/IV status of an SV.
1810
1811 SvNIOK_off (SV* sv)
1812
1813=item SvNIOKp
1814
1815Returns a boolean indicating whether the SV contains a number, integer or
1816double. Checks the B<private> setting. Use C<SvNIOK>.
1817
1818 int SvNIOKp (SV* SV)
1819
1820=item SvNOK
1821
1822Returns a boolean indicating whether the SV contains a double.
1823
1824 int SvNOK (SV* SV)
1825
1826=item SvNOK_off
1827
1828Unsets the NV status of an SV.
1829
1830 SvNOK_off (SV* sv)
1831
1832=item SvNOK_on
1833
1834Tells an SV that it is a double.
1835
1836 SvNOK_on (SV* sv)
1837
1838=item SvNOKp
1839
1840Returns a boolean indicating whether the SV contains a double. Checks the
1841B<private> setting. Use C<SvNOK>.
1842
1843 int SvNOKp (SV* SV)
1844
1845=item SvNV
1846
1847Returns the double which is stored in the SV.
1848
1849 double SvNV (SV* sv);
1850
1851=item SvNVX
1852
1853Returns the double which is stored in the SV.
1854
1855 double SvNVX (SV* sv);
1856
1857=item SvPOK
1858
1859Returns a boolean indicating whether the SV contains a character string.
1860
1861 int SvPOK (SV* SV)
1862
1863=item SvPOK_off
1864
1865Unsets the PV status of an SV.
1866
1867 SvPOK_off (SV* sv)
1868
1869=item SvPOK_on
1870
1871Tells an SV that it is a string.
1872
1873 SvPOK_on (SV* sv)
1874
1875=item SvPOKp
1876
1877Returns a boolean indicating whether the SV contains a character string.
1878Checks the B<private> setting. Use C<SvPOK>.
1879
1880 int SvPOKp (SV* SV)
1881
1882=item SvPV
1883
1884Returns a pointer to the string in the SV, or a stringified form of the SV
1885if the SV does not contain a string. If C<len> is C<na> then Perl will
1886handle the length on its own.
1887
1888 char * SvPV (SV* sv, int len )
1889
1890=item SvPVX
1891
1892Returns a pointer to the string in the SV. The SV must contain a string.
1893
1894 char * SvPVX (SV* sv)
1895
1896=item SvREFCNT
1897
1898Returns the value of the object's refcount.
1899
1900 int SvREFCNT (SV* sv);
1901
1902=item SvREFCNT_dec
1903
1904Decrements the refcount of the given SV.
1905
1906 void SvREFCNT_dec (SV* sv)
1907
1908=item SvREFCNT_inc
1909
1910Increments the refcount of the given SV.
1911
1912 void SvREFCNT_inc (SV* sv)
1913
1914=item SvROK
1915
1916Tests if the SV is an RV.
1917
1918 int SvROK (SV* sv)
1919
1920=item SvROK_off
1921
1922Unsets the RV status of an SV.
1923
1924 SvROK_off (SV* sv)
1925
1926=item SvROK_on
1927
1928Tells an SV that it is an RV.
1929
1930 SvROK_on (SV* sv)
1931
1932=item SvRV
1933
1934Dereferences an RV to return the SV.
1935
1936 SV* SvRV (SV* sv);
1937
1938=item sv_setiv
1939
1940Copies an integer into the given SV.
1941
1942 void sv_setiv _((SV* sv, IV num));
1943
1944=item sv_setnv
1945
1946Copies a double into the given SV.
1947
1948 void sv_setnv _((SV* sv, double num));
1949
1950=item sv_setpv
1951
1952Copies a string into an SV. The string must be null-terminated.
1953
1954 void sv_setpv _((SV* sv, char* ptr));
1955
1956=item sv_setpvn
1957
1958Copies a string into an SV. The C<len> parameter indicates the number of
1959bytes to be copied.
1960
1961 void sv_setpvn _((SV* sv, char* ptr, STRLEN len));
1962
1963=item sv_setref_iv
1964
1965Copies an integer into an SV, optionally blessing the SV. The SV must be an
1966RV. The C<classname> argument indicates the package for the blessing. Set
1967C<classname> to C<Nullch> to avoid the blessing. The new SV will be
1968returned and will have a refcount of 1.
1969
1970 SV* sv_setref_iv _((SV *rv, char *classname, IV iv));
1971
1972=item sv_setref_nv
1973
1974Copies a double into an SV, optionally blessing the SV. The SV must be an
1975RV. The C<classname> argument indicates the package for the blessing. Set
1976C<classname> to C<Nullch> to avoid the blessing. The new SV will be
1977returned and will have a refcount of 1.
1978
1979 SV* sv_setref_nv _((SV *rv, char *classname, double nv));
1980
1981=item sv_setref_pv
1982
1983Copies a pointer into an SV, optionally blessing the SV. The SV must be an
1984RV. If the C<pv> argument is NULL then C<sv_undef> will be placed into the
1985SV. The C<classname> argument indicates the package for the blessing. Set
1986C<classname> to C<Nullch> to avoid the blessing. The new SV will be
1987returned and will have a refcount of 1.
1988
1989 SV* sv_setref_pv _((SV *rv, char *classname, void* pv));
1990
1991Do not use with integral Perl types such as HV, AV, SV, CV, because those
1992objects will become corrupted by the pointer copy process.
1993
1994Note that C<sv_setref_pvn> copies the string while this copies the pointer.
1995
1996=item sv_setref_pvn
1997
1998Copies a string into an SV, optionally blessing the SV. The lenth of the
1999string must be specified with C<n>. The SV must be an RV. The C<classname>
2000argument indicates the package for the blessing. Set C<classname> to
2001C<Nullch> to avoid the blessing. The new SV will be returned and will have
2002a refcount of 1.
2003
2004 SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
2005
2006Note that C<sv_setref_pv> copies the pointer while this copies the string.
2007
2008=item sv_setsv
2009
2010Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
1faa3dee
PP
2011(B<NOTE:> If C<ssv> has the C<SVs_TEMP> bit set, C<sv_setsv> may simply steal
2012the string from C<ssv> and give it to C<dsv>, leaving C<ssv> empty.
2013Caveat caller.)
cb1a09d0
AD
2014
2015 void sv_setsv _((SV* dsv, SV* ssv));
2016
2017=item SvSTASH
2018
2019Returns the stash of the SV.
2020
2021 HV * SvSTASH (SV* sv)
2022
2023=item SVt_IV
2024
2025Integer type flag for scalars. See C<svtype>.
2026
2027=item SVt_PV
2028
2029Pointer type flag for scalars. See C<svtype>.
2030
2031=item SVt_PVAV
2032
2033Type flag for arrays. See C<svtype>.
2034
2035=item SVt_PVCV
2036
2037Type flag for code refs. See C<svtype>.
2038
2039=item SVt_PVHV
2040
2041Type flag for hashes. See C<svtype>.
2042
2043=item SVt_PVMG
2044
2045Type flag for blessed scalars. See C<svtype>.
2046
2047=item SVt_NV
2048
2049Double type flag for scalars. See C<svtype>.
2050
2051=item SvTRUE
2052
2053Returns a boolean indicating whether Perl would evaluate the SV as true or
2054false, defined or undefined.
2055
2056 int SvTRUE (SV* sv)
2057
2058=item SvTYPE
2059
2060Returns the type of the SV. See C<svtype>.
2061
2062 svtype SvTYPE (SV* sv)
2063
2064=item svtype
2065
2066An enum of flags for Perl types. These are found in the file B<sv.h> in the
2067C<svtype> enum. Test these flags with the C<SvTYPE> macro.
2068
2069=item SvUPGRADE
2070
2071Used to upgrade an SV to a more complex form. See C<svtype>.
2072
2073=item sv_undef
2074
2075This is the C<undef> SV. Always refer to this as C<&sv_undef>.
2076
2077=item sv_usepvn
2078
2079Tells an SV to use C<ptr> to find its string value. Normally the string is
2080stored inside the SV; this allows the SV to use an outside string. The
2081string length, C<len>, must be supplied. This function will realloc the
2082memory pointed to by C<ptr>, so that pointer should not be freed or used by
2083the programmer after giving it to sv_usepvn.
2084
2085 void sv_usepvn _((SV* sv, char* ptr, STRLEN len));
2086
2087=item sv_yes
2088
2089This is the C<true> SV. See C<sv_no>. Always refer to this as C<&sv_yes>.
2090
2091=item THIS
2092
2093Variable which is setup by C<xsubpp> to designate the object in a C++ XSUB.
2094This is always the proper type for the C++ object. See C<CLASS> and
2095L<perlxs>.
2096
2097=item toLOWER
2098
2099Converts the specified character to lowercase.
2100
2101 int toLOWER (char c)
2102
2103=item toUPPER
2104
2105Converts the specified character to uppercase.
2106
2107 int toUPPER (char c)
2108
2109=item warn
2110
2111This is the XSUB-writer's interface to Perl's C<warn> function. Use this
2112function the same way you use the C C<printf> function. See C<croak()>.
2113
2114=item XPUSHi
2115
2116Push an integer onto the stack, extending the stack if necessary. See
2117C<PUSHi>.
2118
2119 XPUSHi(int d)
2120
2121=item XPUSHn
2122
2123Push a double onto the stack, extending the stack if necessary. See
2124C<PUSHn>.
2125
2126 XPUSHn(double d)
2127
2128=item XPUSHp
2129
2130Push a string onto the stack, extending the stack if necessary. The C<len>
2131indicates the length of the string. See C<PUSHp>.
2132
2133 XPUSHp(char *c, int len)
2134
2135=item XPUSHs
2136
2137Push an SV onto the stack, extending the stack if necessary. See C<PUSHs>.
2138
2139 XPUSHs(sv)
2140
2141=item XSRETURN
2142
2143Return from XSUB, indicating number of items on the stack. This is usually
2144handled by C<xsubpp>.
2145
2146 XSRETURN(x);
2147
2148=item XSRETURN_EMPTY
2149
2150Return from an XSUB immediately.
2151
2152 XSRETURN_EMPTY;
2153
2154=item XSRETURN_NO
2155
2156Return C<false> from an XSUB immediately.
2157
2158 XSRETURN_NO;
2159
2160=item XSRETURN_UNDEF
2161
2162Return C<undef> from an XSUB immediately.
2163
2164 XSRETURN_UNDEF;
2165
2166=item XSRETURN_YES
2167
2168Return C<true> from an XSUB immediately.
2169
2170 XSRETURN_YES;
2171
2172=item Zero
2173
2174The XSUB-writer's interface to the C C<memzero> function. The C<d> is the
2175destination, C<n> is the number of items, and C<t> is the type.
2176
2177 (void) Zero( d, n, t );
2178
2179=back
2180
2181=head1 AUTHOR
2182
2183Jeff Okamoto <okamoto@corp.hp.com>
2184
2185With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2186Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
2187Bowers, Matthew Green, Tim Bunce, and Spider Boardman.
2188
2189API Listing by Dean Roehrich <roehrich@cray.com>.
2190
2191=head1 DATE
2192
2193Version 20: 1995/12/14
a0d0e21e 2194