EditPageHistoryDiffInfoLikePages

Annotated edit history of perlapi(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	PERLAPI
		2	!!!PERLAPI
		3	NAME
		4	DESCRIPTION
		5	AUTHORS
		6	SEE ALSO
		7	----
		8	!!NAME
		9
		10
		11	perlapi - autogenerated documentation for the perl public API
		12	!!DESCRIPTION
		13
		14
		15	This file contains the documentation of the perl public
		16	API generated by embed.pl, specifically a
		17	listing of functions, macros, flags, and variables that may
		18	be used by extension writers. The interfaces of any
		19	functions that are not listed here are subject to change
		20	without notice. For this reason, blindly using functions
		21	listed in proto.h is to be avoided when writing
		22	extensions.
		23
		24
		25	Note that all Perl API global variables must
		26	be referenced with the PL_ prefix. Some macros are
		27	provided for compatibility with the older, unadorned names,
		28	but this support may be disabled in a future
		29	release.
		30
		31
		32	The listing is alphabetical, case insensitive.
		33
		34
		35	AvFILL
		36
		37
		38	Same as av_len(). Deprecated, use av_len()
		39	instead.
		40
		41
		42	int AvFILL(AV* av)
		43
		44
		45	av_clear
		46
		47
		48	Clears an array, making it empty. Does not free the memory
		49	used by the array itself.
		50
		51
		52	void av_clear(AV* ar)
		53
		54
		55	av_delete
		56
		57
		58	Deletes the element indexed by key from the array.
		59	Returns the deleted element. flags is currently
		60	ignored.
		61
		62
		63	SV* av_delete(AV* ar, I32 key, I32 flags)
		64
		65
		66	av_exists
		67
		68
		69	Returns true if the element indexed by key has been
		70	initialized.
		71
		72
		73	This relies on the fact that uninitialized array elements
		74	are set to .
		75
		76
		77	bool av_exists(AV* ar, I32 key)
		78
		79
		80	av_extend
		81
		82
		83	Pre-extend an array. The key is the index to which
		84	the array should be extended.
		85
		86
		87	void av_extend(AV* ar, I32 key)
		88
		89
		90	av_fetch
		91
		92
		93	Returns the SV at the specified index in the
		94	array. The key is the index. If lval is
		95	set then the fetch will be part of a store. Check that the
		96	return value is non-null before dereferencing it to a
		97	SV*.
		98
		99
		100	See ``Understanding the Magic of Tied Hashes and Arrays'' in
		101	perlguts for more information on how to use this function on
		102	tied arrays.
		103
		104
		105	SV** av_fetch(AV* ar, I32 key, I32 lval)
		106
		107
		108	av_fill
		109
		110
		111	Ensure than an array has a given number of elements,
		112	equivalent to Perl's $#array = $fill;.
		113
		114
		115	void av_fill(AV* ar, I32 fill)
		116
		117
		118	av_len
		119
		120
		121	Returns the highest index in the array. Returns -1 if the
		122	array is empty.
		123
		124
		125	I32 av_len(AV* ar)
		126
		127
		128	av_make
		129
		130
		131	Creates a new AV and populates it with a list
		132	of SVs. The SVs are copied into the array, so they may be
		133	freed after the call to av_make. The new AV
		134	will have a reference count of 1.
		135
		136
		137	AV* av_make(I32 size, SV** svp)
		138
		139
		140	av_pop
		141
		142
		143	Pops an SV off the end of the array. Returns
		144	if the array is
		145	empty.
		146
		147
		148	SV* av_pop(AV* ar)
		149
		150
		151	av_push
		152
		153
		154	Pushes an SV onto the end of the array. The
		155	array will grow automatically to accommodate the
		156	addition.
		157
		158
		159	void av_push(AV* ar, SV* val)
		160
		161
		162	av_shift
		163
		164
		165	Shifts an SV off the beginning of the
		166	array.
		167
		168
		169	SV* av_shift(AV* ar)
		170
		171
		172	av_store
		173
		174
		175	Stores an SV in an array. The array index is
		176	specified as key. The return value will be
		177	NULL if the operation failed or if the value
		178	did not need to be actually stored within the array (as in
		179	the case of tied arrays). Otherwise it can be dereferenced
		180	to get the original SV*. Note that the caller is
		181	responsible for suitably incrementing the reference count of
		182	val before the call, and decrementing it if the
		183	function returned NULL .
		184
		185
		186	See ``Understanding the Magic of Tied Hashes and Arrays'' in
		187	perlguts for more information on how to use this function on
		188	tied arrays.
		189
		190
		191	SV** av_store(AV* ar, I32 key, SV* val)
		192
		193
		194	av_undef
		195
		196
		197	Undefines the array. Frees the memory used by the array
		198	itself.
		199
		200
		201	void av_undef(AV* ar)
		202
		203
		204	av_unshift
		205
		206
		207	Unshift the given number of undef values onto the
		208	beginning of the array. The array will grow automatically to
		209	accommodate the addition. You must then use
		210	av_store to assign values to these new
		211	elements.
		212
		213
		214	void av_unshift(AV* ar, I32 num)
		215
		216
		217	bytes_from_utf8
		218
		219
		220	Converts a string s of length len from
		221	UTF8 into byte encoding. Unlike
		222	bytes_to_utf8,
		223	returns a pointer to the newly-created string, and updates
		224	len to contain the new length. Returns the original
		225	string if no conversion occurs, len is unchanged.
		226	Do nothing if is_utf8 points to 0. Sets
		227	is_utf8 to 0 if s is converted or contains
		228	all 7bit characters.
		229
		230
		231	NOTE: this function is experimental and may
		232	change or be removed without notice.
		233
		234
		235	U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
		236
		237
		238	bytes_to_utf8
		239
		240
		241	Converts a string s of length len from
		242	ASCII into UTF8 encoding.
		243	Returns a pointer to the newly-created string, and sets
		244	len to reflect the new length.
		245
		246
		247	NOTE: this function is experimental and may
		248	change or be removed without notice.
		249
		250
		251	U8* bytes_to_utf8(U8 *s, STRLEN *len)
		252
		253
		254	call_argv
		255
		256
		257	Performs a callback to the specified Perl sub. See
		258	perlcall.
		259
		260
		261	NOTE: the perl_ form of this function is
		262	deprecated.
		263
		264
		265	I32 call_argv(const char* sub_name, I32 flags, char** argv)
		266
		267
		268	call_method
		269
		270
		271	Performs a callback to the specified Perl method. The
		272	blessed object must be on the stack. See
		273	perlcall.
		274
		275
		276	NOTE: the perl_ form of this function is
		277	deprecated.
		278
		279
		280	I32 call_method(const char* methname, I32 flags)
		281
		282
		283	call_pv
		284
		285
		286	Performs a callback to the specified Perl sub. See
		287	perlcall.
		288
		289
		290	NOTE: the perl_ form of this function is
		291	deprecated.
		292
		293
		294	I32 call_pv(const char* sub_name, I32 flags)
		295
		296
		297	call_sv
		298
		299
		300	Performs a callback to the Perl sub whose name is in the
		301	SV . See perlcall.
		302
		303
		304	NOTE: the perl_ form of this function is
		305	deprecated.
		306
		307
		308	I32 call_sv(SV* sv, I32 flags)
		309
		310
		311	CLASS
		312
		313
		314	Variable which is setup by xsubpp to indicate the
		315	class name for a C ++ XS constructor. This is
		316	always a char*. See THIS.
		317
		318
		319	char* CLASS
		320
		321
		322	Copy
		323
		324
		325	The XSUB-writer's interface to the C memcpy
		326	function. The src is the source, dest is
		327	the destination, nitems is the number of items, and
		328	type is the type. May fail on overlapping copies.
		329	See also Move.
		330
		331
		332	void Copy(void* src, void* dest, int nitems, type)
		333
		334
		335	croak
		336
		337
		338	This is the XSUB-writer's interface to Perl's die
		339	function. Normally use this function the same way you use
		340	the C printf function. See
		341	warn.
		342
		343
		344	If you want to throw an exception object, assign the object
		345	to $@ and then pass Nullch to
		346	''croak()'':
		347
		348
		349	errsv = get_sv(
		350	void croak(const char* pat, ...)
		351
		352
		353	CvSTASH
		354
		355
		356	Returns the stash of the CV .
		357
		358
		359	HV* CvSTASH(CV* cv)
		360
		361
		362	dMARK
		363
		364
		365	Declare a stack marker variable, mark, for the
		366	XSUB . See MARK and
		367	dORIGMARK.
		368
		369
		370	dMARK;
		371
		372
		373	dORIGMARK
		374
		375
		376	Saves the original stack mark for the XSUB .
		377	See ORIGMARK.
		378
		379
		380	dORIGMARK;
		381
		382
		383	dSP
		384
		385
		386	Declares a local copy of perl's stack pointer for the
		387	XSUB , available via the SP macro.
		388	See SP.
		389
		390
		391	dSP;
		392
		393
		394	dXSARGS
		395
		396
		397	Sets up stack and mark pointers for an XSUB ,
		398	calling dSP and dMARK. This is usually handled automatically
		399	by xsubpp. Declares the items variable to
		400	indicate the number of items on the stack.
		401
		402
		403	dXSARGS;
		404
		405
		406	dXSI32
		407
		408
		409	Sets up the ix variable for an XSUB
		410	which has aliases. This is usually handled automatically by
		411	xsubpp.
		412
		413
		414	dXSI32;
		415
		416
		417	ENTER
		418
		419
		420	Opening bracket on a callback. See LEAVE and
		421	perlcall.
		422
		423
		424	ENTER;
		425
		426
		427	eval_pv
		428
		429
		430	Tells Perl to eval the given string and return an
		431	SV* result.
		432
		433
		434	NOTE: the perl_ form of this function is
		435	deprecated.
		436
		437
		438	SV* eval_pv(const char* p, I32 croak_on_error)
		439
		440
		441	eval_sv
		442
		443
		444	Tells Perl to eval the string in the
		445	SV .
		446
		447
		448	NOTE: the perl_ form of this function is
		449	deprecated.
		450
		451
		452	I32 eval_sv(SV* sv, I32 flags)
		453
		454
		455	EXTEND
		456
		457
		458	Used to extend the argument stack for an XSUB
		459	's return values. Once used, guarantees that there is room
		460	for at least nitems to be pushed onto the
		461	stack.
		462
		463
		464	void EXTEND(SP, int nitems)
		465
		466
		467	fbm_compile
		468
		469
		470	Analyses the string in order to make fast searches on it
		471	using ''fbm_instr()'' -- the Boyer-Moore
		472	algorithm.
		473
		474
		475	void fbm_compile(SV* sv, U32 flags)
		476
		477
		478	fbm_instr
		479
		480
		481	Returns the location of the SV in the string
		482	delimited by str and strend. It returns
		483	Nullch if the string can't be found. The
		484	sv does not have to be fbm_compiled, but the search
		485	will not be as fast then.
		486
		487
		488	char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
		489
		490
		491	FREETMPS
		492
		493
		494	Closing bracket for temporaries on a callback. See
		495	SAVETMPS and perlcall.
		496
		497
		498	FREETMPS;
		499
		500
		501	get_av
		502
		503
		504	Returns the AV of the specified Perl array.
		505	If create is set and the Perl variable does not
		506	exist then it will be created. If create is not set
		507	and the variable does not exist then NULL is
		508	returned.
		509
		510
		511	NOTE: the perl_ form of this function is
		512	deprecated.
		513
		514
		515	AV* get_av(const char* name, I32 create)
		516
		517
		518	get_cv
		519
		520
		521	Returns the CV of the specified Perl
		522	subroutine. If create is set and the Perl
		523	subroutine does not exist then it will be declared (which
		524	has the same effect as saying sub name;). If
		525	create is not set and the subroutine does not exist
		526	then NULL is returned.
		527
		528
		529	NOTE: the perl_ form of this function is
		530	deprecated.
		531
		532
		533	CV* get_cv(const char* name, I32 create)
		534
		535
		536	get_hv
		537
		538
		539	Returns the HV of the specified Perl hash. If
		540	create is set and the Perl variable does not exist
		541	then it will be created. If create is not set and
		542	the variable does not exist then NULL is
		543	returned.
		544
		545
		546	NOTE: the perl_ form of this function is
		547	deprecated.
		548
		549
		550	HV* get_hv(const char* name, I32 create)
		551
		552
		553	get_sv
		554
		555
		556	Returns the SV of the specified Perl scalar.
		557	If create is set and the Perl variable does not
		558	exist then it will be created. If create is not set
		559	and the variable does not exist then NULL is
		560	returned.
		561
		562
		563	NOTE: the perl_ form of this function is
		564	deprecated.
		565
		566
		567	SV* get_sv(const char* name, I32 create)
		568
		569
		570	GIMME
		571
		572
		573	A backward-compatible version of GIMME_V which can
		574	only return G_SCALAR or G_ARRAY; in a void
		575	context, it returns G_SCALAR. Deprecated. Use
		576	GIMME_V instead.
		577
		578
		579	U32 GIMME
		580
		581
		582	GIMME_V
		583
		584
		585	The XSUB-writer's equivalent to Perl's wantarray.
		586	Returns G_VOID, G_SCALAR or
		587	G_ARRAY for void, scalar or list context,
		588	respectively.
		589
		590
		591	U32 GIMME_V
		592
		593
		594	GvSV
		595
		596
		597	Return the SV from the GV
		598	.
		599
		600
		601	SV* GvSV(GV* gv)
		602
		603
		604	gv_fetchmeth
		605
		606
		607	Returns the glob with the given name and a defined
		608	subroutine or NULL. The glob lives in the given
		609	stash, or in the stashes accessible via
		610	@ISA and @UNIVERSAL.
		611
		612
		613	The argument level should be either 0 or -1. If
		614	level==0, as a side-effect creates a glob with the
		615	given name in the given stash which in the
		616	case of success contains an alias for the subroutine, and
		617	sets up caching info for this glob. Similarly for all the
		618	searched stashes.
		619
		620
		621	This function grants token as a
		622	postfix of the stash name. The GV returned
		623	from gv_fetchmeth may be a method cache entry,
		624	which is not visible to Perl code. So when calling
		625	call_sv, you should not use the GV
		626	directly; instead, you should use the method's
		627	CV , which can be obtained from the
		628	GV with the GvCV macro.
		629
		630
		631	GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
		632
		633
		634	gv_fetchmethod
		635
		636
		637	See gv_fetchmethod_autoload.
		638
		639
		640	GV* gv_fetchmethod(HV* stash, const char* name)
		641
		642
		643	gv_fetchmethod_autoload
		644
		645
		646	Returns the glob which contains the subroutine to call to
		647	invoke the method on the stash. In fact in the
		648	presence of autoloading this may be the glob for ``
		649	AUTOLOAD ''. In this case the corresponding
		650	variable $AUTOLOAD is already setup.
		651
		652
		653	The third parameter of gv_fetchmethod_autoload
		654	determines whether AUTOLOAD lookup is
		655	performed if the given method is not present: non-zero means
		656	yes, look for AUTOLOAD ; zero means no, don't
		657	look for AUTOLOAD . Calling
		658	gv_fetchmethod is equivalent to calling
		659	gv_fetchmethod_autoload with a non-zero
		660	autoload parameter.
		661
		662
		663	These functions grant token as a
		664	prefix of the method name. Note that if you want to keep the
		665	returned glob for a long time, you need to check for it
		666	being `` AUTOLOAD '', since at the later time
		667	the call may load a different subroutine due to
		668	$AUTOLOAD changing its value. Use the glob created
		669	via a side effect to do this.
		670
		671
		672	These functions have the same side-effects and as
		673	gv_fetchmeth with level==0. name
		674	should be writable if contains ':' or '
		675	''. The warning against passing the GV
		676	returned by gv_fetchmeth to call_sv apply
		677	equally to these functions.
		678
		679
		680	GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
		681
		682
		683	gv_stashpv
		684
		685
		686	Returns a pointer to the stash for a specified package.
		687	name should be a valid UTF-8 string.
		688	If create is set then the package will be created
		689	if it does not already exist. If create is not set
		690	and the package does not exist then NULL is
		691	returned.
		692
		693
		694	HV* gv_stashpv(const char* name, I32 create)
		695
		696
		697	gv_stashsv
		698
		699
		700	Returns a pointer to the stash for a specified package,
		701	which must be a valid UTF-8 string. See
		702	gv_stashpv.
		703
		704
		705	HV* gv_stashsv(SV* sv, I32 create)
		706
		707
		708	G_ARRAY
		709
		710
		711	Used to indicate list context. See GIMME_V,
		712	GIMME and perlcall.
		713
		714
		715	G_DISCARD
		716
		717
		718	Indicates that arguments returned from a callback should be
		719	discarded. See perlcall.
		720
		721
		722	G_EVAL
		723
		724
		725	Used to force a Perl eval wrapper around a
		726	callback. See perlcall.
		727
		728
		729	G_NOARGS
		730
		731
		732	Indicates that no arguments are being sent to a callback.
		733	See perlcall.
		734
		735
		736	G_SCALAR
		737
		738
		739	Used to indicate scalar context. See GIMME_V,
		740	GIMME, and perlcall.
		741
		742
		743	G_VOID
		744
		745
		746	Used to indicate void context. See GIMME_V and
		747	perlcall.
		748
		749
		750	HEf_SVKEY
		751
		752
		753	This flag, used in the length slot of hash entries and magic
		754	structures, specifies the structure contains a SV*
		755	pointer where a char* pointer is to be expected.
		756	(For information only--not to be used).
		757
		758
		759	HeHASH
		760
		761
		762	Returns the computed hash stored in the hash
		763	entry.
		764
		765
		766	U32 HeHASH(HE* he)
		767
		768
		769	HeKEY
		770
		771
		772	Returns the actual pointer stored in the key slot of the
		773	hash entry. The pointer may be either char* or
		774	SV*, depending on the value of HeKLEN().
		775	Can be assigned to. The HePV() or
		776	HeSVKEY() macros are usually preferable for finding
		777	the value of a key.
		778
		779
		780	void* HeKEY(HE* he)
		781
		782
		783	HeKLEN
		784
		785
		786	If this is negative, and amounts to HEf_SVKEY, it
		787	indicates the entry holds an SV* key. Otherwise,
		788	holds the actual length of the key. Can be assigned to. The
		789	HePV() macro is usually preferable for finding key
		790	lengths.
		791
		792
		793	STRLEN HeKLEN(HE* he)
		794
		795
		796	HePV
		797
		798
		799	Returns the key slot of the hash entry as a char*
		800	value, doing any necessary dereferencing of possibly
		801	SV* keys. The length of the string is placed in
		802	len (this is a macro, so do ''not'' use
		803	). If you do not care about what the length
		804	of the key is, you may use the global variable
		805	PL_na, though this is rather less efficient than
		806	using a local variable. Remember though, that hash keys in
		807	perl are free to contain embedded nulls, so using
		808	strlen() or similar is not a good way to find the
		809	length of hash keys. This is very similar to the
		810	SvPV() macro described elsewhere in this
		811	document.
		812
		813
		814	char* HePV(HE* he, STRLEN len)
		815
		816
		817	HeSVKEY
		818
		819
		820	Returns the key as an SV*, or Nullsv if
		821	the hash entry does not contain an SV*
		822	key.
		823
		824
		825	SV* HeSVKEY(HE* he)
		826
		827
		828	HeSVKEY_force
		829
		830
		831	Returns the key as an SV*. Will create and return a
		832	temporary mortal SV* if the hash entry contains
		833	only a char* key.
		834
		835
		836	SV* HeSVKEY_force(HE* he)
		837
		838
		839	HeSVKEY_set
		840
		841
		842	Sets the key to a given SV*, taking care to set the
		843	appropriate flags to indicate the presence of an
		844	SV* key, and returns the same
		845	SV*.
		846
		847
		848	SV* HeSVKEY_set(HE* he, SV* sv)
		849
		850
		851	HeVAL
		852
		853
		854	Returns the value slot (type SV*) stored in the
		855	hash entry.
		856
		857
		858	SV* HeVAL(HE* he)
		859
		860
		861	HvNAME
		862
		863
		864	Returns the package name of a stash. See SvSTASH,
		865	CvSTASH.
		866
		867
		868	char* HvNAME(HV* stash)
		869
		870
		871	hv_clear
		872
		873
		874	Clears a hash, making it empty.
		875
		876
		877	void hv_clear(HV* tb)
		878
		879
		880	hv_delete
		881
		882
		883	Deletes a key/value pair in the hash. The value
		884	SV is removed from the hash and returned to
		885	the caller. The klen is the length of the key. The
		886	flags value will normally be zero; if set to
		887	G_DISCARD then NULL will be
		888	returned.
		889
		890
		891	SV* hv_delete(HV* tb, const char* key, U32 klen, I32 flags)
		892
		893
		894	hv_delete_ent
		895
		896
		897	Deletes a key/value pair in the hash. The value
		898	SV is removed from the hash and returned to
		899	the caller. The flags value will normally be zero;
		900	if set to G_DISCARD then NULL will be
		901	returned. hash can be a valid precomputed hash
		902	value, or 0 to ask for it to be computed.
		903
		904
		905	SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
		906
		907
		908	hv_exists
		909
		910
		911	Returns a boolean indicating whether the specified hash key
		912	exists. The klen is the length of the
		913	key.
		914
		915
		916	bool hv_exists(HV* tb, const char* key, U32 klen)
		917
		918
		919	hv_exists_ent
		920
		921
		922	Returns a boolean indicating whether the specified hash key
		923	exists. hash can be a valid precomputed hash value,
		924	or 0 to ask for it to be computed.
		925
		926
		927	bool hv_exists_ent(HV* tb, SV* key, U32 hash)
		928
		929
		930	hv_fetch
		931
		932
		933	Returns the SV which corresponds to the
		934	specified key in the hash. The klen is the length
		935	of the key. If lval is set then the fetch will be
		936	part of a store. Check that the return value is non-null
		937	before dereferencing it to a SV*.
		938
		939
		940	See ``Understanding the Magic of Tied Hashes and Arrays'' in
		941	perlguts for more information on how to use this function on
		942	tied hashes.
		943
		944
		945	SV** hv_fetch(HV* tb, const char* key, U32 klen, I32 lval)
		946
		947
		948	hv_fetch_ent
		949
		950
		951	Returns the hash entry which corresponds to the specified
		952	key in the hash. hash must be a valid precomputed
		953	hash number for the given key, or 0 if you want the
		954	function to compute it. IF lval is
		955	set then the fetch will be part of a store. Make sure the
		956	return value is non-null before accessing it. The return
		957	value when tb is a tied hash is a pointer to a
		958	static location, so be sure to make a copy of the structure
		959	if you need to store it somewhere.
		960
		961
		962	See ``Understanding the Magic of Tied Hashes and Arrays'' in
		963	perlguts for more information on how to use this function on
		964	tied hashes.
		965
		966
		967	HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
		968
		969
		970	hv_iterinit
		971
		972
		973	Prepares a starting point to traverse a hash table. Returns
		974	the number of keys in the hash (i.e. the same as
		975	HvKEYS(tb)). The return value is currently only
		976	meaningful for hashes without tie magic.
		977
		978
		979	NOTE: Before version 5.004_65,
		980	hv_iterinit used to return the number of hash
		981	buckets that happen to be in use. If you still need that
		982	esoteric value, you can get it through the macro
		983	HvFILL(tb).
		984
		985
		986	I32 hv_iterinit(HV* tb)
		987
		988
		989	hv_iterkey
		990
		991
		992	Returns the key from the current position of the hash
		993	iterator. See hv_iterinit.
		994
		995
		996	char* hv_iterkey(HE* entry, I32* retlen)
		997
		998
		999	hv_iterkeysv
		1000
		1001
		1002	Returns the key as an SV* from the current position
		1003	of the hash iterator. The return value will always be a
		1004	mortal copy of the key. Also see
		1005	hv_iterinit.
		1006
		1007
		1008	SV* hv_iterkeysv(HE* entry)
		1009
		1010
		1011	hv_iternext
		1012
		1013
		1014	Returns entries from a hash iterator. See
		1015	hv_iterinit.
		1016
		1017
		1018	HE* hv_iternext(HV* tb)
		1019
		1020
		1021	hv_iternextsv
		1022
		1023
		1024	Performs an hv_iternext, hv_iterkey, and
		1025	hv_iterval in one operation.
		1026
		1027
		1028	SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
		1029
		1030
		1031	hv_iterval
		1032
		1033
		1034	Returns the value from the current position of the hash
		1035	iterator. See hv_iterkey.
		1036
		1037
		1038	SV* hv_iterval(HV* tb, HE* entry)
		1039
		1040
		1041	hv_magic
		1042
		1043
		1044	Adds magic to a hash. See sv_magic.
		1045
		1046
		1047	void hv_magic(HV* hv, GV* gv, int how)
		1048
		1049
		1050	hv_store
		1051
		1052
		1053	Stores an SV in a hash. The hash key is
		1054	specified as key and klen is the length of
		1055	the key. The hash parameter is the precomputed hash
		1056	value; if it is zero then Perl will compute it. The return
		1057	value will be NULL if the operation failed or
		1058	if the value did not need to be actually stored within the
		1059	hash (as in the case of tied hashes). Otherwise it can be
		1060	dereferenced to get the original SV*. Note that the
		1061	caller is responsible for suitably incrementing the
		1062	reference count of val before the call, and
		1063	decrementing it if the function returned NULL
		1064	.
		1065
		1066
		1067	See ``Understanding the Magic of Tied Hashes and Arrays'' in
		1068	perlguts for more information on how to use this function on
		1069	tied hashes.
		1070
		1071
		1072	SV** hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash)
		1073
		1074
		1075	hv_store_ent
		1076
		1077
		1078	Stores val in a hash. The hash key is specified as
		1079	key. The hash parameter is the precomputed
		1080	hash value; if it is zero then Perl will compute it. The
		1081	return value is the new hash entry so created. It will be
		1082	NULL if the operation failed or if the value
		1083	did not need to be actually stored within the hash (as in
		1084	the case of tied hashes). Otherwise the contents of the
		1085	return value can be accessed using the He??? macros
		1086	described here. Note that the caller is responsible for
		1087	suitably incrementing the reference count of val
		1088	before the call, and decrementing it if the function
		1089	returned NULL .
		1090
		1091
		1092	See ``Understanding the Magic of Tied Hashes and Arrays'' in
		1093	perlguts for more information on how to use this function on
		1094	tied hashes.
		1095
		1096
		1097	HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
		1098
		1099
		1100	hv_undef
		1101
		1102
		1103	Undefines the hash.
		1104
		1105
		1106	void hv_undef(HV* tb)
		1107
		1108
		1109	isALNUM
		1110
		1111
		1112	Returns a boolean indicating whether the C char is
		1113	an ASCII alphanumeric character (including
		1114	underscore) or digit.
		1115
		1116
		1117	bool isALNUM(char ch)
		1118
		1119
		1120	isALPHA
		1121
		1122
		1123	Returns a boolean indicating whether the C char is
		1124	an ASCII alphabetic character.
		1125
		1126
		1127	bool isALPHA(char ch)
		1128
		1129
		1130	isDIGIT
		1131
		1132
		1133	Returns a boolean indicating whether the C char is
		1134	an ASCII digit.
		1135
		1136
		1137	bool isDIGIT(char ch)
		1138
		1139
		1140	isLOWER
		1141
		1142
		1143	Returns a boolean indicating whether the C char is
		1144	a lowercase character.
		1145
		1146
		1147	bool isLOWER(char ch)
		1148
		1149
		1150	isSPACE
		1151
		1152
		1153	Returns a boolean indicating whether the C char is
		1154	whitespace.
		1155
		1156
		1157	bool isSPACE(char ch)
		1158
		1159
		1160	isUPPER
		1161
		1162
		1163	Returns a boolean indicating whether the C char is
		1164	an uppercase character.
		1165
		1166
		1167	bool isUPPER(char ch)
		1168
		1169
		1170	is_utf8_char
		1171
		1172
		1173	Tests if some arbitrary number of bytes begins in a valid
		1174	UTF-8 character. The actual number of bytes
		1175	in the UTF-8 character will be returned if it
		1176	is valid, otherwise 0.
		1177
		1178
		1179	STRLEN is_utf8_char(U8 *p)
		1180
		1181
		1182	is_utf8_string
		1183
		1184
		1185	Returns true if first len bytes of the given string
		1186	form valid a UTF8 string, false
		1187	otherwise.
		1188
		1189
		1190	bool is_utf8_string(U8 *s, STRLEN len)
		1191
		1192
		1193	items
		1194
		1195
		1196	Variable which is setup by xsubpp to indicate the
		1197	number of items on the stack. See ``Variable-length
		1198	Parameter Lists'' in perlxs.
		1199
		1200
		1201	I32 items
		1202
		1203
		1204	ix
		1205
		1206
		1207	Variable which is setup by xsubpp to indicate which
		1208	of an XSUB 's aliases was used to invoke it.
		1209	See ``The ALIAS: Keyword'' in
		1210	perlxs.
		1211
		1212
		1213	I32 ix
		1214
		1215
		1216	LEAVE
		1217
		1218
		1219	Closing bracket on a callback. See ENTER and
		1220	perlcall.
		1221
		1222
		1223	LEAVE;
		1224
		1225
		1226	looks_like_number
		1227
		1228
		1229	Test if an the content of an SV looks like a
		1230	number (or is a number).
		1231
		1232
		1233	I32 looks_like_number(SV* sv)
		1234
		1235
		1236	MARK
		1237
		1238
		1239	Stack marker variable for the XSUB . See
		1240	dMARK.
		1241
		1242
		1243	mg_clear
		1244
		1245
		1246	Clear something magical that the SV
		1247	represents. See sv_magic.
		1248
		1249
		1250	int mg_clear(SV* sv)
		1251
		1252
		1253	mg_copy
		1254
		1255
		1256	Copies the magic from one SV to another. See
		1257	sv_magic.
		1258
		1259
		1260	int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
		1261
		1262
		1263	mg_find
		1264
		1265
		1266	Finds the magic pointer for type matching the
		1267	SV . See sv_magic.
		1268
		1269
		1270	MAGIC* mg_find(SV* sv, int type)
		1271
		1272
		1273	mg_free
		1274
		1275
		1276	Free any magic storage used by the SV . See
		1277	sv_magic.
		1278
		1279
		1280	int mg_free(SV* sv)
		1281
		1282
		1283	mg_get
		1284
		1285
		1286	Do magic after a value is retrieved from the
		1287	SV . See sv_magic.
		1288
		1289
		1290	int mg_get(SV* sv)
		1291
		1292
		1293	mg_length
		1294
		1295
		1296	Report on the SV 's length. See
		1297	sv_magic.
		1298
		1299
		1300	U32 mg_length(SV* sv)
		1301
		1302
		1303	mg_magical
		1304
		1305
		1306	Turns on the magical status of an SV . See
		1307	sv_magic.
		1308
		1309
		1310	void mg_magical(SV* sv)
		1311
		1312
		1313	mg_set
		1314
		1315
		1316	Do magic after a value is assigned to the SV
		1317	. See sv_magic.
		1318
		1319
		1320	int mg_set(SV* sv)
		1321
		1322
		1323	Move
		1324
		1325
		1326	The XSUB-writer's interface to the C memmove
		1327	function. The src is the source, dest is
		1328	the destination, nitems is the number of items, and
		1329	type is the type. Can do overlapping moves. See
		1330	also Copy.
		1331
		1332
		1333	void Move(void* src, void* dest, int nitems, type)
		1334
		1335
		1336	New
		1337
		1338
		1339	The XSUB-writer's interface to the C malloc
		1340	function.
		1341
		1342
		1343	void New(int id, void* ptr, int nitems, type)
		1344
		1345
		1346	newAV
		1347
		1348
		1349	Creates a new AV . The reference count is set
		1350	to 1.
		1351
		1352
		1353	AV* newAV()
		1354
		1355
		1356	Newc
		1357
		1358
		1359	The XSUB-writer's interface to the C malloc
		1360	function, with cast.
		1361
		1362
		1363	void Newc(int id, void* ptr, int nitems, type, cast)
		1364
		1365
		1366	newCONSTSUB
		1367
		1368
		1369	Creates a constant sub equivalent to Perl sub FOO () {
		1370	123 } which is eligible for inlining at
		1371	compile-time.
		1372
		1373
		1374	void newCONSTSUB(HV* stash, char* name, SV* sv)
		1375
		1376
		1377	newHV
		1378
		1379
		1380	Creates a new HV . The reference count is set
		1381	to 1.
		1382
		1383
		1384	HV* newHV()
		1385
		1386
		1387	newRV_inc
		1388
		1389
		1390	Creates an RV wrapper for an
		1391	SV . The reference count for the original
		1392	SV is incremented.
		1393
		1394
		1395	SV* newRV_inc(SV* sv)
		1396
		1397
		1398	newRV_noinc
		1399
		1400
		1401	Creates an RV wrapper for an
		1402	SV . The reference count for the original
		1403	SV is __not__ incremented.
		1404
		1405
		1406	SV* newRV_noinc(SV *sv)
		1407
		1408
		1409	NEWSV
		1410
		1411
		1412	Creates a new SV . A non-zero len
		1413	parameter indicates the number of bytes of preallocated
		1414	string space the SV should have. An extra
		1415	byte for a tailing NUL is also reserved.
		1416	(SvPOK is not set for the SV even if string
		1417	space is allocated.) The reference count for the new
		1418	SV is set to 1. id is an integer id
		1419	between 0 and 1299 (used to identify leaks).
		1420
		1421
		1422	SV* NEWSV(int id, STRLEN len)
		1423
		1424
		1425	newSViv
		1426
		1427
		1428	Creates a new SV and copies an integer into
		1429	it. The reference count for the SV is set to
		1430	1.
		1431
		1432
		1433	SV* newSViv(IV i)
		1434
		1435
		1436	newSVnv
		1437
		1438
		1439	Creates a new SV and copies a floating point
		1440	value into it. The reference count for the SV
		1441	is set to 1.
		1442
		1443
		1444	SV* newSVnv(NV n)
		1445
		1446
		1447	newSVpv
		1448
		1449
		1450	Creates a new SV and copies a string into it.
		1451	The reference count for the SV is set to 1.
		1452	If len is zero, Perl will compute the length using
		1453	''strlen()''. For efficiency, consider using
		1454	newSVpvn instead.
		1455
		1456
		1457	SV* newSVpv(const char* s, STRLEN len)
		1458
		1459
		1460	newSVpvf
		1461
		1462
		1463	Creates a new SV an initialize it with the
		1464	string formatted like sprintf.
		1465
		1466
		1467	SV* newSVpvf(const char* pat, ...)
		1468
		1469
		1470	newSVpvn
		1471
		1472
		1473	Creates a new SV and copies a string into it.
		1474	The reference count for the SV is set to 1.
		1475	Note that if len is zero, Perl will create a zero
		1476	length string. You are responsible for ensuring that the
		1477	source string is at least len bytes
		1478	long.
		1479
		1480
		1481	SV* newSVpvn(const char* s, STRLEN len)
		1482
		1483
		1484	newSVrv
		1485
		1486
		1487	Creates a new SV for the RV ,
		1488	rv, to point to. If rv is not an
		1489	RV then it will be upgraded to one. If
		1490	classname is non-null then the new
		1491	SV will be blessed in the specified package.
		1492	The new SV is returned and its reference
		1493	count is 1.
		1494
		1495
		1496	SV* newSVrv(SV* rv, const char* classname)
		1497
		1498
		1499	newSVsv
		1500
		1501
		1502	Creates a new SV which is an exact duplicate
		1503	of the original SV .
		1504
		1505
		1506	SV* newSVsv(SV* old)
		1507
		1508
		1509	newSVuv
		1510
		1511
		1512	Creates a new SV and copies an unsigned
		1513	integer into it. The reference count for the
		1514	SV is set to 1.
		1515
		1516
		1517	SV* newSVuv(UV u)
		1518
		1519
		1520	newXS
		1521
		1522
		1523	Used by xsubpp to hook up XSUBs as Perl
		1524	subs.
		1525
		1526
		1527	newXSproto
		1528
		1529
		1530	Used by xsubpp to hook up XSUBs as Perl subs. Adds
		1531	Perl prototypes to the subs.
		1532
		1533
		1534	Newz
		1535
		1536
		1537	The XSUB-writer's interface to the C malloc
		1538	function. The allocated memory is zeroed with
		1539	memzero.
		1540
		1541
		1542	void Newz(int id, void* ptr, int nitems, type)
		1543
		1544
		1545	Nullav
		1546
		1547
		1548	Null AV pointer.
		1549
		1550
		1551	Nullch
		1552
		1553
		1554	Null character pointer.
		1555
		1556
		1557	Nullcv
		1558
		1559
		1560	Null CV pointer.
		1561
		1562
		1563	Nullhv
		1564
		1565
		1566	Null HV pointer.
		1567
		1568
		1569	Nullsv
		1570
		1571
		1572	Null SV pointer.
		1573
		1574
		1575	ORIGMARK
		1576
		1577
		1578	The original stack mark for the XSUB . See
		1579	dORIGMARK.
		1580
		1581
		1582	perl_alloc
		1583
		1584
		1585	Allocates a new Perl interpreter. See
		1586	perlembed.
		1587
		1588
2	perry	1589	!PerlInterpreter* perl_alloc()
1	perry	1590
		1591
		1592	perl_construct
		1593
		1594
		1595	Initializes a new Perl interpreter. See
		1596	perlembed.
		1597
		1598
2	perry	1599	void perl_construct(!PerlInterpreter* interp)
1	perry	1600
		1601
		1602	perl_destruct
		1603
		1604
		1605	Shuts down a Perl interpreter. See perlembed.
		1606
		1607
2	perry	1608	void perl_destruct(!PerlInterpreter* interp)
1	perry	1609
		1610
		1611	perl_free
		1612
		1613
		1614	Releases a Perl interpreter. See perlembed.
		1615
		1616
2	perry	1617	void perl_free(!PerlInterpreter* interp)
1	perry	1618
		1619
		1620	perl_parse
		1621
		1622
		1623	Tells a Perl interpreter to parse a Perl script. See
		1624	perlembed.
		1625
		1626
2	perry	1627	int perl_parse(!PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1	perry	1628
		1629
		1630	perl_run
		1631
		1632
		1633	Tells a Perl interpreter to run. See perlembed.
		1634
		1635
2	perry	1636	int perl_run(!PerlInterpreter* interp)
1	perry	1637
		1638
		1639	PL_modglobal
		1640
		1641
		1642	PL_modglobal is a general purpose, interpreter
		1643	global HV for use by extensions that need to
		1644	keep information on a per-interpreter basis. In a pinch, it
		1645	can also be used as a symbol table for extensions to share
		1646	data among each other. It is a good idea to use keys
		1647	prefixed by the package name of the extension that owns the
		1648	data.
		1649
		1650
		1651	HV* PL_modglobal
		1652
		1653
		1654	PL_na
		1655
		1656
		1657	A convenience variable which is typically used with
		1658	SvPV when one doesn't care about the length of the
		1659	string. It is usually more efficient to either declare a
		1660	local variable and use that instead or to use the
		1661	SvPV_nolen macro.
		1662
		1663
		1664	STRLEN PL_na
		1665
		1666
		1667	PL_sv_no
		1668
		1669
		1670	This is the false SV . See
		1671	PL_sv_yes. Always refer to this as
		1672	.
		1673
		1674
		1675	SV PL_sv_no
		1676
		1677
		1678	PL_sv_undef
		1679
		1680
		1681	This is the undef SV . Always refer
		1682	to this as .
		1683
		1684
		1685	SV PL_sv_undef
		1686
		1687
		1688	PL_sv_yes
		1689
		1690
		1691	This is the true SV . See
		1692	PL_sv_no. Always refer to this as
		1693	.
		1694
		1695
		1696	SV PL_sv_yes
		1697
		1698
		1699	POPi
		1700
		1701
		1702	Pops an integer off the stack.
		1703
		1704
		1705	IV POPi
		1706
		1707
		1708	POPl
		1709
		1710
		1711	Pops a long off the stack.
		1712
		1713
		1714	long POPl
		1715
		1716
		1717	POPn
		1718
		1719
		1720	Pops a double off the stack.
		1721
		1722
		1723	NV POPn
		1724
		1725
		1726	POPp
		1727
		1728
		1729	Pops a string off the stack.
		1730
		1731
		1732	char* POPp
		1733
		1734
		1735	POPs
		1736
		1737
		1738	Pops an SV off the stack.
		1739
		1740
		1741	SV* POPs
		1742
		1743
		1744	PUSHi
		1745
		1746
		1747	Push an integer onto the stack. The stack must have room for
		1748	this element. Handles 'set' magic. See
		1749	XPUSHi.
		1750
		1751
		1752	void PUSHi(IV iv)
		1753
		1754
		1755	PUSHMARK
		1756
		1757
		1758	Opening bracket for arguments on a callback. See
		1759	PUTBACK and perlcall.
		1760
		1761
		1762	PUSHMARK;
		1763
		1764
		1765	PUSHn
		1766
		1767
		1768	Push a double onto the stack. The stack must have room for
		1769	this element. Handles 'set' magic. See
		1770	XPUSHn.
		1771
		1772
		1773	void PUSHn(NV nv)
		1774
		1775
		1776	PUSHp
		1777
		1778
		1779	Push a string onto the stack. The stack must have room for
		1780	this element. The len indicates the length of the
		1781	string. Handles 'set' magic. See
		1782	XPUSHp.
		1783
		1784
		1785	void PUSHp(char* str, STRLEN len)
		1786
		1787
		1788	PUSHs
		1789
		1790
		1791	Push an SV onto the stack. The stack must
		1792	have room for this element. Does not handle 'set' magic. See
		1793	XPUSHs.
		1794
		1795
		1796	void PUSHs(SV* sv)
		1797
		1798
		1799	PUSHu
		1800
		1801
		1802	Push an unsigned integer onto the stack. The stack must have
		1803	room for this element. See XPUSHu.
		1804
		1805
		1806	void PUSHu(UV uv)
		1807
		1808
		1809	PUTBACK
		1810
		1811
		1812	Closing bracket for XSUB arguments. This is
		1813	usually handled by xsubpp. See PUSHMARK
		1814	and perlcall for other uses.
		1815
		1816
		1817	PUTBACK;
		1818
		1819
		1820	Renew
		1821
		1822
		1823	The XSUB-writer's interface to the C realloc
		1824	function.
		1825
		1826
		1827	void Renew(void* ptr, int nitems, type)
		1828
		1829
		1830	Renewc
		1831
		1832
		1833	The XSUB-writer's interface to the C realloc
		1834	function, with cast.
		1835
		1836
		1837	void Renewc(void* ptr, int nitems, type, cast)
		1838
		1839
		1840	require_pv
		1841
		1842
		1843	Tells Perl to require a module.
		1844
		1845
		1846	NOTE: the perl_ form of this function is
		1847	deprecated.
		1848
		1849
		1850	void require_pv(const char* pv)
		1851
		1852
		1853	RETVAL
		1854
		1855
		1856	Variable which is setup by xsubpp to hold the
		1857	return value for an XSUB . This is always the
		1858	proper type for the XSUB . See ``The
		1859	RETVAL Variable'' in perlxs.
		1860
		1861
		1862	(whatever) RETVAL
		1863
		1864
		1865	Safefree
		1866
		1867
		1868	The XSUB-writer's interface to the C free
		1869	function.
		1870
		1871
		1872	void Safefree(void* ptr)
		1873
		1874
		1875	savepv
		1876
		1877
		1878	Copy a string to a safe spot. This does not use an
		1879	SV .
		1880
		1881
		1882	char* savepv(const char* sv)
		1883
		1884
		1885	savepvn
		1886
		1887
		1888	Copy a string to a safe spot. The len indicates
		1889	number of bytes to copy. This does not use an
		1890	SV .
		1891
		1892
		1893	char* savepvn(const char* sv, I32 len)
		1894
		1895
		1896	SAVETMPS
		1897
		1898
		1899	Opening bracket for temporaries on a callback. See
		1900	FREETMPS and perlcall.
		1901
		1902
		1903	SAVETMPS;
		1904
		1905
		1906	SP
		1907
		1908
		1909	Stack pointer. This is usually handled by xsubpp.
		1910	See dSP and SPAGAIN.
		1911
		1912
		1913	SPAGAIN
		1914
		1915
		1916	Refetch the stack pointer. Used after a callback. See
		1917	perlcall.
		1918
		1919
		1920	SPAGAIN;
		1921
		1922
		1923	ST
		1924
		1925
		1926	Used to access elements on the XSUB 's
		1927	stack.
		1928
		1929
		1930	SV* ST(int ix)
		1931
		1932
		1933	strEQ
		1934
		1935
		1936	Test two strings to see if they are equal. Returns true or
		1937	false.
		1938
		1939
		1940	bool strEQ(char* s1, char* s2)
		1941
		1942
		1943	strGE
		1944
		1945
		1946	Test two strings to see if the first, s1, is
		1947	greater than or equal to the second, s2. Returns
		1948	true or false.
		1949
		1950
		1951	bool strGE(char* s1, char* s2)
		1952
		1953
		1954	strGT
		1955
		1956
		1957	Test two strings to see if the first, s1, is
		1958	greater than the second, s2. Returns true or
		1959	false.
		1960
		1961
		1962	bool strGT(char* s1, char* s2)
		1963
		1964
		1965	strLE
		1966
		1967
		1968	Test two strings to see if the first, s1, is less
		1969	than or equal to the second, s2. Returns true or
		1970	false.
		1971
		1972
		1973	bool strLE(char* s1, char* s2)
		1974
		1975
		1976	strLT
		1977
		1978
		1979	Test two strings to see if the first, s1, is less
		1980	than the second, s2. Returns true or
		1981	false.
		1982
		1983
		1984	bool strLT(char* s1, char* s2)
		1985
		1986
		1987	strNE
		1988
		1989
		1990	Test two strings to see if they are different. Returns true
		1991	or false.
		1992
		1993
		1994	bool strNE(char* s1, char* s2)
		1995
		1996
		1997	strnEQ
		1998
		1999
		2000	Test two strings to see if they are equal. The len
		2001	parameter indicates the number of bytes to compare. Returns
		2002	true or false. (A wrapper for
		2003	strncmp).
		2004
		2005
		2006	bool strnEQ(char* s1, char* s2, STRLEN len)
		2007
		2008
		2009	strnNE
		2010
		2011
		2012	Test two strings to see if they are different. The
		2013	len parameter indicates the number of bytes to
		2014	compare. Returns true or false. (A wrapper for
		2015	strncmp).
		2016
		2017
		2018	bool strnNE(char* s1, char* s2, STRLEN len)
		2019
		2020
2	perry	2021	!StructCopy
1	perry	2022
		2023
		2024	This is an architecture-independent macro to copy one
		2025	structure to another.
		2026
		2027
2	perry	2028	void !StructCopy(type src, type dest, type)
1	perry	2029
		2030
		2031	SvCUR
		2032
		2033
		2034	Returns the length of the string which is in the
		2035	SV . See SvLEN.
		2036
		2037
		2038	STRLEN SvCUR(SV* sv)
		2039
		2040
		2041	SvCUR_set
		2042
		2043
		2044	Set the length of the string which is in the
		2045	SV . See SvCUR.
		2046
		2047
		2048	void SvCUR_set(SV* sv, STRLEN len)
		2049
		2050
		2051	SvEND
		2052
		2053
		2054	Returns a pointer to the last character in the string which
		2055	is in the SV . See SvCUR. Access the
		2056	character as *(SvEND(sv)).
		2057
		2058
		2059	char* SvEND(SV* sv)
		2060
		2061
		2062	SvGETMAGIC
		2063
		2064
		2065	Invokes mg_get on an SV if it has
		2066	'get' magic. This macro evaluates its argument more than
		2067	once.
		2068
		2069
		2070	void SvGETMAGIC(SV* sv)
		2071
		2072
		2073	SvGROW
		2074
		2075
		2076	Expands the character buffer in the SV so
		2077	that it has room for the indicated number of bytes (remember
		2078	to reserve space for an extra trailing NUL
		2079	character). Calls sv_grow to perform the expansion
		2080	if necessary. Returns a pointer to the character
		2081	buffer.
		2082
		2083
		2084	void SvGROW(SV* sv, STRLEN len)
		2085
		2086
		2087	SvIOK
		2088
		2089
		2090	Returns a boolean indicating whether the SV
		2091	contains an integer.
		2092
		2093
		2094	bool SvIOK(SV* sv)
		2095
		2096
		2097	SvIOKp
		2098
		2099
		2100	Returns a boolean indicating whether the SV
		2101	contains an integer. Checks the __private__ setting. Use
		2102	SvIOK.
		2103
		2104
		2105	bool SvIOKp(SV* sv)
		2106
		2107
		2108	SvIOK_notUV
		2109
		2110
		2111	Returns a boolean indicating whether the SV
		2112	contains an signed integer.
		2113
		2114
		2115	void SvIOK_notUV(SV* sv)
		2116
		2117
		2118	SvIOK_off
		2119
		2120
		2121	Unsets the IV status of an SV
		2122	.
		2123
		2124
		2125	void SvIOK_off(SV* sv)
		2126
		2127
		2128	SvIOK_on
		2129
		2130
		2131	Tells an SV that it is an
		2132	integer.
		2133
		2134
		2135	void SvIOK_on(SV* sv)
		2136
		2137
		2138	SvIOK_only
		2139
		2140
		2141	Tells an SV that it is an integer and
		2142	disables all other OK bits.
		2143
		2144
		2145	void SvIOK_only(SV* sv)
		2146
		2147
		2148	SvIOK_only_UV
		2149
		2150
		2151	Tells and SV that it is an unsigned integer
		2152	and disables all other OK bits.
		2153
		2154
		2155	void SvIOK_only_UV(SV* sv)
		2156
		2157
		2158	SvIOK_UV
		2159
		2160
		2161	Returns a boolean indicating whether the SV
		2162	contains an unsigned integer.
		2163
		2164
		2165	void SvIOK_UV(SV* sv)
		2166
		2167
		2168	SvIV
		2169
		2170
		2171	Coerces the given SV to an integer and
		2172	returns it.
		2173
		2174
		2175	IV SvIV(SV* sv)
		2176
		2177
		2178	SvIVX
		2179
		2180
		2181	Returns the integer which is stored in the SV
		2182	, assuming SvIOK is true.
		2183
		2184
		2185	IV SvIVX(SV* sv)
		2186
		2187
		2188	SvLEN
		2189
		2190
		2191	Returns the size of the string buffer in the
		2192	SV , not including any part attributable to
		2193	SvOOK. See SvCUR.
		2194
		2195
		2196	STRLEN SvLEN(SV* sv)
		2197
		2198
		2199	SvNIOK
		2200
		2201
		2202	Returns a boolean indicating whether the SV
		2203	contains a number, integer or double.
		2204
		2205
		2206	bool SvNIOK(SV* sv)
		2207
		2208
		2209	SvNIOKp
		2210
		2211
		2212	Returns a boolean indicating whether the SV
		2213	contains a number, integer or double. Checks the
		2214	__private__ setting. Use SvNIOK.
		2215
		2216
		2217	bool SvNIOKp(SV* sv)
		2218
		2219
		2220	SvNIOK_off
		2221
		2222
		2223	Unsets the NV/IV status of an
		2224	SV .
		2225
		2226
		2227	void SvNIOK_off(SV* sv)
		2228
		2229
		2230	SvNOK
		2231
		2232
		2233	Returns a boolean indicating whether the SV
		2234	contains a double.
		2235
		2236
		2237	bool SvNOK(SV* sv)
		2238
		2239
		2240	SvNOKp
		2241
		2242
		2243	Returns a boolean indicating whether the SV
		2244	contains a double. Checks the __private__ setting. Use
		2245	SvNOK.
		2246
		2247
		2248	bool SvNOKp(SV* sv)
		2249
		2250
		2251	SvNOK_off
		2252
		2253
		2254	Unsets the NV status of an SV
		2255	.
		2256
		2257
		2258	void SvNOK_off(SV* sv)
		2259
		2260
		2261	SvNOK_on
		2262
		2263
		2264	Tells an SV that it is a double.
		2265
		2266
		2267	void SvNOK_on(SV* sv)
		2268
		2269
		2270	SvNOK_only
		2271
		2272
		2273	Tells an SV that it is a double and disables
		2274	all other OK bits.
		2275
		2276
		2277	void SvNOK_only(SV* sv)
		2278
		2279
		2280	SvNV
		2281
		2282
		2283	Coerce the given SV to a double and return
		2284	it.
		2285
		2286
		2287	NV SvNV(SV* sv)
		2288
		2289
		2290	SvNVX
		2291
		2292
		2293	Returns the double which is stored in the SV
		2294	, assuming SvNOK is true.
		2295
		2296
		2297	NV SvNVX(SV* sv)
		2298
		2299
		2300	SvOK
		2301
		2302
		2303	Returns a boolean indicating whether the value is an
		2304	SV .
		2305
		2306
		2307	bool SvOK(SV* sv)
		2308
		2309
		2310	SvOOK
		2311
		2312
		2313	Returns a boolean indicating whether the SvIVX is a valid
		2314	offset value for the SvPVX. This hack is used internally to
		2315	speed up removal of characters from the beginning of a SvPV.
		2316	When SvOOK is true, then the start of the allocated string
		2317	buffer is really (SvPVX - SvIVX).
		2318
		2319
		2320	bool SvOOK(SV* sv)
		2321
		2322
		2323	SvPOK
		2324
		2325
		2326	Returns a boolean indicating whether the SV
		2327	contains a character string.
		2328
		2329
		2330	bool SvPOK(SV* sv)
		2331
		2332
		2333	SvPOKp
		2334
		2335
		2336	Returns a boolean indicating whether the SV
		2337	contains a character string. Checks the __private__
		2338	setting. Use SvPOK.
		2339
		2340
		2341	bool SvPOKp(SV* sv)
		2342
		2343
		2344	SvPOK_off
		2345
		2346
		2347	Unsets the PV status of an SV
		2348	.
		2349
		2350
		2351	void SvPOK_off(SV* sv)
		2352
		2353
		2354	SvPOK_on
		2355
		2356
		2357	Tells an SV that it is a string.
		2358
		2359
		2360	void SvPOK_on(SV* sv)
		2361
		2362
		2363	SvPOK_only
		2364
		2365
		2366	Tells an SV that it is a string and disables
		2367	all other OK bits.
		2368
		2369
		2370	void SvPOK_only(SV* sv)
		2371
		2372
		2373	SvPOK_only_UTF8
		2374
		2375
		2376	Tells an SV that it is a UTF8
		2377	string (do not use frivolously) and disables all other
		2378	OK bits.
		2379
		2380
		2381	void SvPOK_only_UTF8(SV* sv)
		2382
		2383
		2384	SvPV
		2385
		2386
		2387	Returns a pointer to the string in the SV ,
		2388	or a stringified form of the SV if the
		2389	SV does not contain a string. Handles 'get'
		2390	magic.
		2391
		2392
		2393	char* SvPV(SV* sv, STRLEN len)
		2394
		2395
		2396	SvPVX
		2397
		2398
		2399	Returns a pointer to the string in the SV .
		2400	The SV must contain a string.
		2401
		2402
		2403	char* SvPVX(SV* sv)
		2404
		2405
		2406	SvPV_force
		2407
		2408
		2409	Like SV into
		2410	becoming a string (SvPOK). You want force if you are going
		2411	to update the SvPVX directly.
		2412
		2413
		2414	char* SvPV_force(SV* sv, STRLEN len)
		2415
		2416
		2417	SvPV_nolen
		2418
		2419
		2420	Returns a pointer to the string in the SV ,
		2421	or a stringified form of the SV if the
		2422	SV does not contain a string. Handles 'get'
		2423	magic.
		2424
		2425
		2426	char* SvPV_nolen(SV* sv)
		2427
		2428
		2429	SvREFCNT
		2430
		2431
		2432	Returns the value of the object's reference
		2433	count.
		2434
		2435
		2436	U32 SvREFCNT(SV* sv)
		2437
		2438
		2439	SvREFCNT_dec
		2440
		2441
		2442	Decrements the reference count of the given
		2443	SV .
		2444
		2445
		2446	void SvREFCNT_dec(SV* sv)
		2447
		2448
		2449	SvREFCNT_inc
		2450
		2451
		2452	Increments the reference count of the given
		2453	SV .
		2454
		2455
		2456	SV* SvREFCNT_inc(SV* sv)
		2457
		2458
		2459	SvROK
		2460
		2461
		2462	Tests if the SV is an RV
		2463	.
		2464
		2465
		2466	bool SvROK(SV* sv)
		2467
		2468
		2469	SvROK_off
		2470
		2471
		2472	Unsets the RV status of an SV
		2473	.
		2474
		2475
		2476	void SvROK_off(SV* sv)
		2477
		2478
		2479	SvROK_on
		2480
		2481
		2482	Tells an SV that it is an RV
		2483	.
		2484
		2485
		2486	void SvROK_on(SV* sv)
		2487
		2488
		2489	SvRV
		2490
		2491
		2492	Dereferences an RV to return the
		2493	SV .
		2494
		2495
		2496	SV* SvRV(SV* sv)
		2497
		2498
		2499	SvSETMAGIC
		2500
		2501
		2502	Invokes mg_set on an SV if it has
		2503	'set' magic. This macro evaluates its argument more than
		2504	once.
		2505
		2506
		2507	void SvSETMAGIC(SV* sv)
		2508
		2509
		2510	SvSetSV
		2511
		2512
		2513	Calls sv_setsv if dsv is not the same as ssv. May
		2514	evaluate arguments more than once.
		2515
		2516
		2517	void SvSetSV(SV* dsb, SV* ssv)
		2518
		2519
		2520	SvSetSV_nosteal
		2521
		2522
		2523	Calls a non-destructive version of sv_setsv if dsv
		2524	is not the same as ssv. May evaluate arguments more than
		2525	once.
		2526
		2527
		2528	void SvSetSV_nosteal(SV* dsv, SV* ssv)
		2529
		2530
		2531	SvSTASH
		2532
		2533
		2534	Returns the stash of the SV .
		2535
		2536
		2537	HV* SvSTASH(SV* sv)
		2538
		2539
		2540	SvTAINT
		2541
		2542
		2543	Taints an SV if tainting is
		2544	enabled
		2545
		2546
		2547	void SvTAINT(SV* sv)
		2548
		2549
		2550	SvTAINTED
		2551
		2552
		2553	Checks to see if an SV is tainted. Returns
		2554	TRUE if it is, FALSE if
		2555	not.
		2556
		2557
		2558	bool SvTAINTED(SV* sv)
		2559
		2560
		2561	SvTAINTED_off
		2562
		2563
		2564	Untaints an SV . Be ''very'' careful with
		2565	this routine, as it short-circuits some of Perl's
		2566	fundamental security features. XS module
		2567	authors should not use this function unless they fully
		2568	understand all the implications of unconditionally
		2569	untainting the value. Untainting should be done in the
		2570	standard perl fashion, via a carefully crafted regexp,
		2571	rather than directly untainting variables.
		2572
		2573
		2574	void SvTAINTED_off(SV* sv)
		2575
		2576
		2577	SvTAINTED_on
		2578
		2579
		2580	Marks an SV as tainted.
		2581
		2582
		2583	void SvTAINTED_on(SV* sv)
		2584
		2585
		2586	SvTRUE
		2587
		2588
		2589	Returns a boolean indicating whether Perl would evaluate the
		2590	SV as true or false, defined or undefined.
		2591	Does not handle 'get' magic.
		2592
		2593
		2594	bool SvTRUE(SV* sv)
		2595
		2596
		2597	svtype
		2598
		2599
		2600	An enum of flags for Perl types. These are found in the file
		2601	__sv.h__ in the svtype enum. Test these flags
		2602	with the SvTYPE macro.
		2603
		2604
		2605	SvTYPE
		2606
		2607
		2608	Returns the type of the SV . See
		2609	svtype.
		2610
		2611
		2612	svtype SvTYPE(SV* sv)
		2613
		2614
		2615	SVt_IV
		2616
		2617
		2618	Integer type flag for scalars. See
		2619	svtype.
		2620
		2621
		2622	SVt_NV
		2623
		2624
		2625	Double type flag for scalars. See
		2626	svtype.
		2627
		2628
		2629	SVt_PV
		2630
		2631
		2632	Pointer type flag for scalars. See
		2633	svtype.
		2634
		2635
		2636	SVt_PVAV
		2637
		2638
		2639	Type flag for arrays. See svtype.
		2640
		2641
		2642	SVt_PVCV
		2643
		2644
		2645	Type flag for code refs. See svtype.
		2646
		2647
		2648	SVt_PVHV
		2649
		2650
		2651	Type flag for hashes. See svtype.
		2652
		2653
		2654	SVt_PVMG
		2655
		2656
		2657	Type flag for blessed scalars. See
		2658	svtype.
		2659
		2660
		2661	SvUPGRADE
		2662
		2663
		2664	Used to upgrade an SV to a more complex form.
		2665	Uses sv_upgrade to perform the upgrade if
		2666	necessary. See svtype.
		2667
		2668
		2669	void SvUPGRADE(SV* sv, svtype type)
		2670
		2671
		2672	SvUTF8
		2673
		2674
		2675	Returns a boolean indicating whether the SV
		2676	contains UTF-8 encoded data.
		2677
		2678
		2679	void SvUTF8(SV* sv)
		2680
		2681
		2682	SvUTF8_off
		2683
		2684
		2685	Unsets the UTF8 status of an
		2686	SV .
		2687
		2688
		2689	void SvUTF8_off(SV *sv)
		2690
		2691
		2692	SvUTF8_on
		2693
		2694
		2695	Tells an SV that it is a string and encoded
		2696	in UTF8 . Do not use
		2697	frivolously.
		2698
		2699
		2700	void SvUTF8_on(SV *sv)
		2701
		2702
		2703	SvUV
		2704
		2705
		2706	Coerces the given SV to an unsigned integer
		2707	and returns it.
		2708
		2709
		2710	UV SvUV(SV* sv)
		2711
		2712
		2713	SvUVX
		2714
		2715
		2716	Returns the unsigned integer which is stored in the
		2717	SV , assuming SvIOK is true.
		2718
		2719
		2720	UV SvUVX(SV* sv)
		2721
		2722
		2723	sv_2mortal
		2724
		2725
		2726	Marks an SV as mortal. The SV
		2727	will be destroyed when the current context
		2728	ends.
		2729
		2730
		2731	SV* sv_2mortal(SV* sv)
		2732
		2733
		2734	sv_bless
		2735
		2736
		2737	Blesses an SV into a specified package. The
		2738	SV must be an RV . The package
		2739	must be designated by its stash (see gv_stashpv()).
		2740	The reference count of the SV is
		2741	unaffected.
		2742
		2743
		2744	SV* sv_bless(SV* sv, HV* stash)
		2745
		2746
		2747	sv_catpv
		2748
		2749
		2750	Concatenates the string onto the end of the string which is
		2751	in the SV . Handles 'get' magic, but not
		2752	'set' magic. See sv_catpv_mg.
		2753
		2754
		2755	void sv_catpv(SV* sv, const char* ptr)
		2756
		2757
		2758	sv_catpvf
		2759
		2760
		2761	Processes its arguments like sprintf and appends
		2762	the formatted output to an SV . Handles 'get'
		2763	magic, but not 'set' magic. SvSETMAGIC() must
		2764	typically be called after calling this function to handle
		2765	'set' magic.
		2766
		2767
		2768	void sv_catpvf(SV* sv, const char* pat, ...)
		2769
		2770
		2771	sv_catpvf_mg
		2772
		2773
		2774	Like sv_catpvf, but also handles 'set'
		2775	magic.
		2776
		2777
		2778	void sv_catpvf_mg(SV *sv, const char* pat, ...)
		2779
		2780
		2781	sv_catpvn
		2782
		2783
		2784	Concatenates the string onto the end of the string which is
		2785	in the SV . The len indicates number
		2786	of bytes to copy. Handles 'get' magic, but not 'set' magic.
		2787	See sv_catpvn_mg.
		2788
		2789
		2790	void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
		2791
		2792
		2793	sv_catpvn_mg
		2794
		2795
		2796	Like sv_catpvn, but also handles 'set'
		2797	magic.
		2798
		2799
		2800	void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
		2801
		2802
		2803	sv_catpv_mg
		2804
		2805
		2806	Like sv_catpv, but also handles 'set'
		2807	magic.
		2808
		2809
		2810	void sv_catpv_mg(SV *sv, const char *ptr)
		2811
		2812
		2813	sv_catsv
		2814
		2815
		2816	Concatenates the string from SV ssv
		2817	onto the end of the string in SV
		2818	dsv. Modifies dsv but not ssv.
		2819	Handles 'get' magic, but not 'set' magic. See
		2820	sv_catsv_mg.
		2821
		2822
		2823	void sv_catsv(SV* dsv, SV* ssv)
		2824
		2825
		2826	sv_catsv_mg
		2827
		2828
		2829	Like sv_catsv, but also handles 'set'
		2830	magic.
		2831
		2832
		2833	void sv_catsv_mg(SV *dstr, SV *sstr)
		2834
		2835
		2836	sv_chop
		2837
		2838
		2839	Efficient removal of characters from the beginning of the
		2840	string buffer. SvPOK(sv) must be true and the ptr
		2841	must be a pointer to somewhere inside the string buffer. The
		2842	ptr becomes the first character of the adjusted
		2843	string.
		2844
		2845
		2846	void sv_chop(SV* sv, char* ptr)
		2847
		2848
		2849	sv_clear
		2850
		2851
		2852	Clear an SV , making it empty. Does not free
		2853	the memory used by the SV
		2854	itself.
		2855
		2856
		2857	void sv_clear(SV* sv)
		2858
		2859
		2860	sv_cmp
		2861
		2862
		2863	Compares the strings in two SVs. Returns -1, 0, or 1
		2864	indicating whether the string in sv1 is less than,
		2865	equal to, or greater than the string in
		2866	sv2.
		2867
		2868
		2869	I32 sv_cmp(SV* sv1, SV* sv2)
		2870
		2871
		2872	sv_cmp_locale
		2873
		2874
		2875	Compares the strings in two SVs in a locale-aware manner.
		2876	See ``sv_cmp_locale''
		2877
		2878
		2879	I32 sv_cmp_locale(SV* sv1, SV* sv2)
		2880
		2881
		2882	sv_dec
		2883
		2884
		2885	Auto-decrement of the value in the SV
		2886	.
		2887
		2888
		2889	void sv_dec(SV* sv)
		2890
		2891
		2892	sv_derived_from
		2893
		2894
		2895	Returns a boolean indicating whether the SV
		2896	is derived from the specified class. This is the function
		2897	that implements UNIVERSAL::isa. It works for class
		2898	names as well as for objects.
		2899
		2900
		2901	bool sv_derived_from(SV* sv, const char* name)
		2902
		2903
		2904	sv_eq
		2905
		2906
		2907	Returns a boolean indicating whether the strings in the two
		2908	SVs are identical.
		2909
		2910
		2911	I32 sv_eq(SV* sv1, SV* sv2)
		2912
		2913
		2914	sv_free
		2915
		2916
		2917	Free the memory used by an SV .
		2918
		2919
		2920	void sv_free(SV* sv)
		2921
		2922
		2923	sv_gets
		2924
		2925
		2926	Get a line from the filehandle and store it into the
		2927	SV , optionally appending to the
		2928	currently-stored string.
		2929
		2930
		2931	char* sv_gets(SV* sv, PerlIO* fp, I32 append)
		2932
		2933
		2934	sv_grow
		2935
		2936
		2937	Expands the character buffer in the SV . This
		2938	will use sv_unref and will upgrade the
		2939	SV to SVt_PV. Returns a pointer to
		2940	the character buffer. Use SvGROW.
		2941
		2942
		2943	char* sv_grow(SV* sv, STRLEN newlen)
		2944
		2945
		2946	sv_inc
		2947
		2948
		2949	Auto-increment of the value in the SV
		2950	.
		2951
		2952
		2953	void sv_inc(SV* sv)
		2954
		2955
		2956	sv_insert
		2957
		2958
		2959	Inserts a string at the specified offset/length within the
		2960	SV . Similar to the Perl ''substr()''
		2961	function.
		2962
		2963
		2964	void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
		2965
		2966
		2967	sv_isa
		2968
		2969
		2970	Returns a boolean indicating whether the SV
		2971	is blessed into the specified class. This does not check for
		2972	subtypes; use sv_derived_from to verify an
		2973	inheritance relationship.
		2974
		2975
		2976	int sv_isa(SV* sv, const char* name)
		2977
		2978
		2979	sv_isobject
		2980
		2981
		2982	Returns a boolean indicating whether the SV
		2983	is an RV pointing to a blessed object. If the
		2984	SV is not an RV , or if the
		2985	object is not blessed, then this will return
		2986	false.
		2987
		2988
		2989	int sv_isobject(SV* sv)
		2990
		2991
		2992	sv_len
		2993
		2994
		2995	Returns the length of the string in the SV .
		2996	See also SvCUR.
		2997
		2998
		2999	STRLEN sv_len(SV* sv)
		3000
		3001
		3002	sv_len_utf8
		3003
		3004
		3005	Returns the number of characters in the string in an
		3006	SV , counting wide UTF8 bytes
		3007	as a single character.
		3008
		3009
		3010	STRLEN sv_len_utf8(SV* sv)
		3011
		3012
		3013	sv_magic
		3014
		3015
		3016	Adds magic to an SV .
		3017
		3018
		3019	void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
		3020
		3021
		3022	sv_mortalcopy
		3023
		3024
		3025	Creates a new SV which is a copy of the
		3026	original SV . The new SV is
		3027	marked as mortal.
		3028
		3029
		3030	SV* sv_mortalcopy(SV* oldsv)
		3031
		3032
		3033	sv_newmortal
		3034
		3035
		3036	Creates a new SV which is mortal. The
		3037	reference count of the SV is set to
		3038	1.
		3039
		3040
		3041	SV* sv_newmortal()
		3042
		3043
		3044	sv_pvn_force
		3045
		3046
		3047	Get a sensible string out of the SV
		3048	somehow.
		3049
		3050
		3051	char* sv_pvn_force(SV* sv, STRLEN* lp)
		3052
		3053
		3054	sv_pvutf8n_force
		3055
		3056
		3057	Get a sensible UTF8-encoded string out of the
		3058	SV somehow. See
		3059	``sv_pvn_force''.
		3060
		3061
		3062	char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
		3063
		3064
		3065	sv_reftype
		3066
		3067
		3068	Returns a string describing what the SV is a
		3069	reference to.
		3070
		3071
		3072	char* sv_reftype(SV* sv, int ob)
		3073
		3074
		3075	sv_replace
		3076
		3077
		3078	Make the first argument a copy of the second, then delete
		3079	the original.
		3080
		3081
		3082	void sv_replace(SV* sv, SV* nsv)
		3083
		3084
		3085	sv_rvweaken
		3086
		3087
		3088	Weaken a reference.
		3089
		3090
		3091	SV* sv_rvweaken(SV *sv)
		3092
		3093
		3094	sv_setiv
		3095
		3096
		3097	Copies an integer into the given SV . Does
		3098	not handle 'set' magic. See
		3099	sv_setiv_mg.
		3100
		3101
		3102	void sv_setiv(SV* sv, IV num)
		3103
		3104
		3105	sv_setiv_mg
		3106
		3107
		3108	Like sv_setiv, but also handles 'set'
		3109	magic.
		3110
		3111
		3112	void sv_setiv_mg(SV *sv, IV i)
		3113
		3114
		3115	sv_setnv
		3116
		3117
		3118	Copies a double into the given SV . Does not
		3119	handle 'set' magic. See sv_setnv_mg.
		3120
		3121
		3122	void sv_setnv(SV* sv, NV num)
		3123
		3124
		3125	sv_setnv_mg
		3126
		3127
		3128	Like sv_setnv, but also handles 'set'
		3129	magic.
		3130
		3131
		3132	void sv_setnv_mg(SV *sv, NV num)
		3133
		3134
		3135	sv_setpv
		3136
		3137
		3138	Copies a string into an SV . The string must
		3139	be null-terminated. Does not handle 'set' magic. See
		3140	sv_setpv_mg.
		3141
		3142
		3143	void sv_setpv(SV* sv, const char* ptr)
		3144
		3145
		3146	sv_setpvf
		3147
		3148
		3149	Processes its arguments like sprintf and sets an
		3150	SV to the formatted output. Does not handle
		3151	'set' magic. See sv_setpvf_mg.
		3152
		3153
		3154	void sv_setpvf(SV* sv, const char* pat, ...)
		3155
		3156
		3157	sv_setpvf_mg
		3158
		3159
		3160	Like sv_setpvf, but also handles 'set'
		3161	magic.
		3162
		3163
		3164	void sv_setpvf_mg(SV *sv, const char* pat, ...)
		3165
		3166
		3167	sv_setpviv
		3168
		3169
		3170	Copies an integer into the given SV , also
		3171	updating its string value. Does not handle 'set' magic. See
		3172	sv_setpviv_mg.
		3173
		3174
		3175	void sv_setpviv(SV* sv, IV num)
		3176
		3177
		3178	sv_setpviv_mg
		3179
		3180
		3181	Like sv_setpviv, but also handles 'set'
		3182	magic.
		3183
		3184
		3185	void sv_setpviv_mg(SV *sv, IV iv)
		3186
		3187
		3188	sv_setpvn
		3189
		3190
		3191	Copies a string into an SV . The len
		3192	parameter indicates the number of bytes to be copied. Does
		3193	not handle 'set' magic. See
		3194	sv_setpvn_mg.
		3195
		3196
		3197	void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
		3198
		3199
		3200	sv_setpvn_mg
		3201
		3202
		3203	Like sv_setpvn, but also handles 'set'
		3204	magic.
		3205
		3206
		3207	void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
		3208
		3209
		3210	sv_setpv_mg
		3211
		3212
		3213	Like sv_setpv, but also handles 'set'
		3214	magic.
		3215
		3216
		3217	void sv_setpv_mg(SV *sv, const char *ptr)
		3218
		3219
		3220	sv_setref_iv
		3221
		3222
		3223	Copies an integer into a new SV , optionally
		3224	blessing the SV . The rv argument
		3225	will be upgraded to an RV . That
		3226	RV will be modified to point to the new
		3227	SV . The classname argument
		3228	indicates the package for the blessing. Set
		3229	classname to Nullch to avoid the blessing.
		3230	The new SV will be returned and will have a
		3231	reference count of 1.
		3232
		3233
		3234	SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
		3235
		3236
		3237	sv_setref_nv
		3238
		3239
		3240	Copies a double into a new SV , optionally
		3241	blessing the SV . The rv argument
		3242	will be upgraded to an RV . That
		3243	RV will be modified to point to the new
		3244	SV . The classname argument
		3245	indicates the package for the blessing. Set
		3246	classname to Nullch to avoid the blessing.
		3247	The new SV will be returned and will have a
		3248	reference count of 1.
		3249
		3250
		3251	SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
		3252
		3253
		3254	sv_setref_pv
		3255
		3256
		3257	Copies a pointer into a new SV , optionally
		3258	blessing the SV . The rv argument
		3259	will be upgraded to an RV . That
		3260	RV will be modified to point to the new
		3261	SV . If the pv argument is
		3262	NULL then PL_sv_undef will be placed
		3263	into the SV . The classname argument
		3264	indicates the package for the blessing. Set
		3265	classname to Nullch to avoid the blessing.
		3266	The new SV will be returned and will have a
		3267	reference count of 1.
		3268
		3269
		3270	Do not use with other Perl types such as HV ,
		3271	AV , SV , CV ,
		3272	because those objects will become corrupted by the pointer
		3273	copy process.
		3274
		3275
		3276	Note that sv_setref_pvn copies the string while
		3277	this copies the pointer.
		3278
		3279
		3280	SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
		3281
		3282
		3283	sv_setref_pvn
		3284
		3285
		3286	Copies a string into a new SV , optionally
		3287	blessing the SV . The length of the string
		3288	must be specified with n. The rv argument
		3289	will be upgraded to an RV . That
		3290	RV will be modified to point to the new
		3291	SV . The classname argument
		3292	indicates the package for the blessing. Set
		3293	classname to Nullch to avoid the blessing.
		3294	The new SV will be returned and will have a
		3295	reference count of 1.
		3296
		3297
		3298	Note that sv_setref_pv copies the pointer while
		3299	this copies the string.
		3300
		3301
		3302	SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
		3303
		3304
		3305	sv_setsv
		3306
		3307
		3308	Copies the contents of the source SV
		3309	ssv into the destination SV
		3310	dsv. The source SV may be destroyed
		3311	if it is mortal. Does not handle 'set' magic. See the macro
		3312	forms SvSetSV, SvSetSV_nosteal and
		3313	sv_setsv_mg.
		3314
		3315
		3316	void sv_setsv(SV* dsv, SV* ssv)
		3317
		3318
		3319	sv_setsv_mg
		3320
		3321
		3322	Like sv_setsv, but also handles 'set'
		3323	magic.
		3324
		3325
		3326	void sv_setsv_mg(SV *dstr, SV *sstr)
		3327
		3328
		3329	sv_setuv
		3330
		3331
		3332	Copies an unsigned integer into the given SV
		3333	. Does not handle 'set' magic. See
		3334	sv_setuv_mg.
		3335
		3336
		3337	void sv_setuv(SV* sv, UV num)
		3338
		3339
		3340	sv_setuv_mg
		3341
		3342
		3343	Like sv_setuv, but also handles 'set'
		3344	magic.
		3345
		3346
		3347	void sv_setuv_mg(SV *sv, UV u)
		3348
		3349
		3350	sv_true
		3351
		3352
		3353	Returns true if the SV has a true value by
		3354	Perl's rules.
		3355
		3356
		3357	I32 sv_true(SV *sv)
		3358
		3359
		3360	sv_unmagic
		3361
		3362
		3363	Removes magic from an SV .
		3364
		3365
		3366	int sv_unmagic(SV* sv, int type)
		3367
		3368
		3369	sv_unref
		3370
		3371
		3372	Unsets the RV status of the SV
		3373	, and decrements the reference count of whatever was being
		3374	referenced by the RV . This can almost be
		3375	thought of as a reversal of newSVrv. See
		3376	SvROK_off.
		3377
		3378
		3379	void sv_unref(SV* sv)
		3380
		3381
		3382	sv_upgrade
		3383
		3384
		3385	Upgrade an SV to a more complex form. Use
		3386	SvUPGRADE. See svtype.
		3387
		3388
		3389	bool sv_upgrade(SV* sv, U32 mt)
		3390
		3391
		3392	sv_usepvn
		3393
		3394
		3395	Tells an SV to use ptr to find its
		3396	string value. Normally the string is stored inside the
		3397	SV but sv_usepvn allows the SV
		3398	to use an outside string. The ptr should point to
		3399	memory that was allocated by malloc. The string
		3400	length, len, must be supplied. This function will
		3401	realloc the memory pointed to by ptr, so that
		3402	pointer should not be freed or used by the programmer after
		3403	giving it to sv_usepvn. Does not handle 'set' magic. See
		3404	sv_usepvn_mg.
		3405
		3406
		3407	void sv_usepvn(SV* sv, char* ptr, STRLEN len)
		3408
		3409
		3410	sv_usepvn_mg
		3411
		3412
		3413	Like sv_usepvn, but also handles 'set'
		3414	magic.
		3415
		3416
		3417	void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
		3418
		3419
		3420	sv_utf8_downgrade
		3421
		3422
		3423	Attempt to convert the PV of an
		3424	SV from UTF8-encoded to byte encoding. This
		3425	may not be possible if the PV contains
		3426	non-byte encoding characters; if this is the case, either
		3427	returns false or, if fail_ok is not true,
		3428	croaks.
		3429
		3430
		3431	NOTE: this function is experimental and may
		3432	change or be removed without notice.
		3433
		3434
		3435	bool sv_utf8_downgrade(SV *sv, bool fail_ok)
		3436
		3437
		3438	sv_utf8_encode
		3439
		3440
		3441	Convert the PV of an SV to
		3442	UTF8-encoded, but then turn off the SvUTF8 flag so
		3443	that it looks like bytes again. Nothing calls
		3444	this.
		3445
		3446
		3447	NOTE: this function is experimental and may
		3448	change or be removed without notice.
		3449
		3450
		3451	void sv_utf8_encode(SV *sv)
		3452
		3453
		3454	sv_utf8_upgrade
		3455
		3456
		3457	Convert the PV of an SV to its
		3458	UTF8-encoded form.
		3459
		3460
		3461	NOTE: this function is experimental and may
		3462	change or be removed without notice.
		3463
		3464
		3465	void sv_utf8_upgrade(SV *sv)
		3466
		3467
		3468	sv_vcatpvfn
		3469
		3470
		3471	Processes its arguments like vsprintf and appends
		3472	the formatted output to an SV . Uses an array
		3473	of SVs if the C style variable argument list is missing (
		3474	NULL ). When running with taint checks
		3475	enabled, indicates via maybe_tainted if results are
		3476	untrustworthy (often due to the use of
		3477	locales).
		3478
		3479
		3480	void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
		3481
		3482
		3483	sv_vsetpvfn
		3484
		3485
		3486	Works like vcatpvfn but copies the text into the
		3487	SV instead of appending it.
		3488
		3489
		3490	void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
		3491
		3492
		3493	THIS
		3494
		3495
		3496	Variable which is setup by xsubpp to designate the
		3497	object in a C ++ XSUB . This is always the
		3498	proper type for the C ++ object. See
		3499	CLASS and ``Using XS With C
		3500	++ '' in perlxs.
		3501
		3502
		3503	(whatever) THIS
		3504
		3505
		3506	toLOWER
		3507
		3508
		3509	Converts the specified character to lowercase.
		3510
		3511
		3512	char toLOWER(char ch)
		3513
		3514
		3515	toUPPER
		3516
		3517
		3518	Converts the specified character to uppercase.
		3519
		3520
		3521	char toUPPER(char ch)
		3522
		3523
		3524	utf8_distance
		3525
		3526
		3527	Returns the number of UTF8 characters between
		3528	the UTF-8 pointers a and
		3529	b.
		3530
		3531
		3532	WARNING: use only if you *know* that the
		3533	pointers point inside the same UTF-8
		3534	buffer.
		3535
		3536
		3537	NOTE: this function is experimental and may
		3538	change or be removed without notice.
		3539
		3540
		3541	IV utf8_distance(U8 *a, U8 *b)
		3542
		3543
		3544	utf8_hop
		3545
		3546
		3547	Return the UTF-8 pointer s displaced
		3548	by off characters, either forward or
		3549	backward.
		3550
		3551
		3552	WARNING: do not use the following unless you
		3553	*know* off is within the UTF-8 data
		3554	pointed to by s *and* that on entry s is
		3555	aligned on the first byte of character or just after the
		3556	last byte of a character.
		3557
		3558
		3559	NOTE: this function is experimental and may
		3560	change or be removed without notice.
		3561
		3562
		3563	U8* utf8_hop(U8 *s, I32 off)
		3564
		3565
		3566	utf8_length
		3567
		3568
		3569	Return the length of the UTF-8 char encoded
		3570	string s in characters. Stops at e
		3571	(inclusive). If e or if the scan would end
		3572	up past e, croaks.
		3573
		3574
		3575	NOTE: this function is experimental and may
		3576	change or be removed without notice.
		3577
		3578
		3579	STRLEN utf8_length(U8* s, U8 *e)
		3580
		3581
		3582	utf8_to_bytes
		3583
		3584
		3585	Converts a string s of length len from
		3586	UTF8 into byte encoding. Unlike
		3587	bytes_to_utf8, this over-writes the original
		3588	string, and updates len to contain the new length. Returns
		3589	zero on failure, setting len to -1.
		3590
		3591
		3592	NOTE: this function is experimental and may
		3593	change or be removed without notice.
		3594
		3595
		3596	U8* utf8_to_bytes(U8 *s, STRLEN *len)
		3597
		3598
		3599	utf8_to_uv
		3600
		3601
		3602	Returns the character value of the first character in the
		3603	string s which is assumed to be in
		3604	UTF8 encoding and no longer than
		3605	curlen; retlen will be set to the length,
		3606	in bytes, of that character.
		3607
		3608
		3609	If s does not point to a well-formed
		3610	UTF8 character, the behaviour is dependent on
		3611	the value of flags: if it contains
		3612	UTF8_CHECK_ONLY , it is assumed that the
		3613	caller will raise a warning, and this function will silently
		3614	just set retlen to -1 and return zero. If
		3615	the flags does not contain
		3616	UTF8_CHECK_ONLY , warnings about
		3617	malformations will be given, retlen will be set to
		3618	the expected length of the UTF-8 character in
		3619	bytes, and zero will be returned.
		3620
		3621
		3622	The flags can also contain various flags to allow
		3623	deviations from the strict UTF-8 encoding
		3624	(see ''utf8.h'').
		3625
		3626
		3627	NOTE: this function is experimental and may
		3628	change or be removed without notice.
		3629
		3630
		3631	UV utf8_to_uv(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
		3632
		3633
		3634	utf8_to_uv_simple
		3635
		3636
		3637	Returns the character value of the first character in the
		3638	string s which is assumed to be in
		3639	UTF8 encoding; retlen will be set to
		3640	the length, in bytes, of that character.
		3641
		3642
		3643	If s does not point to a well-formed
		3644	UTF8 character, zero is returned and retlen
		3645	is set, if possible, to -1.
		3646
		3647
		3648	NOTE: this function is experimental and may
		3649	change or be removed without notice.
		3650
		3651
		3652	UV utf8_to_uv_simple(U8 *s, STRLEN* retlen)
		3653
		3654
		3655	uv_to_utf8
		3656
		3657
		3658	Adds the UTF8 representation of the Unicode
		3659	codepoint uv to the end of the string d;
		3660	d should be have at least UTF8_MAXLEN+1
		3661	free bytes available. The return value is the pointer to the
		3662	byte after the end of the new character. In other
		3663	words,
		3664
		3665
		3666	d = uv_to_utf8(d, uv);
		3667	is the recommended Unicode-aware way of saying
		3668
		3669
		3670	*(d++) = uv;
		3671	NOTE: this function is experimental and may change or be removed without notice.
		3672
		3673
		3674	U8* uv_to_utf8(U8 *d, UV uv)
		3675
		3676
		3677	warn
		3678
		3679
		3680	This is the XSUB-writer's interface to Perl's warn
		3681	function. Use this function the same way you use the C
		3682	printf function. See croak.
		3683
		3684
		3685	void warn(const char* pat, ...)
		3686
		3687
		3688	XPUSHi
		3689
		3690
		3691	Push an integer onto the stack, extending the stack if
		3692	necessary. Handles 'set' magic. See
		3693	PUSHi.
		3694
		3695
		3696	void XPUSHi(IV iv)
		3697
		3698
		3699	XPUSHn
		3700
		3701
		3702	Push a double onto the stack, extending the stack if
		3703	necessary. Handles 'set' magic. See
		3704	PUSHn.
		3705
		3706
		3707	void XPUSHn(NV nv)
		3708
		3709
		3710	XPUSHp
		3711
		3712
		3713	Push a string onto the stack, extending the stack if
		3714	necessary. The len indicates the length of the
		3715	string. Handles 'set' magic. See
		3716	PUSHp.
		3717
		3718
		3719	void XPUSHp(char* str, STRLEN len)
		3720
		3721
		3722	XPUSHs
		3723
		3724
		3725	Push an SV onto the stack, extending the
		3726	stack if necessary. Does not handle 'set' magic. See
		3727	PUSHs.
		3728
		3729
		3730	void XPUSHs(SV* sv)
		3731
		3732
		3733	XPUSHu
		3734
		3735
		3736	Push an unsigned integer onto the stack, extending the stack
		3737	if necessary. See PUSHu.
		3738
		3739
		3740	void XPUSHu(UV uv)
		3741
		3742
		3743	XS
		3744
		3745
		3746	Macro to declare an XSUB and its C parameter
		3747	list. This is handled by xsubpp.
		3748
		3749
		3750	XSRETURN
		3751
		3752
		3753	Return from XSUB , indicating number of items
		3754	on the stack. This is usually handled by
		3755	xsubpp.
		3756
		3757
		3758	void XSRETURN(int nitems)
		3759
		3760
		3761	XSRETURN_EMPTY
		3762
		3763
		3764	Return an empty list from an XSUB
		3765	immediately.
		3766
		3767
		3768	XSRETURN_EMPTY;
		3769
		3770
		3771	XSRETURN_IV
		3772
		3773
		3774	Return an integer from an XSUB immediately.
		3775	Uses XST_mIV.
		3776
		3777
		3778	void XSRETURN_IV(IV iv)
		3779
		3780
		3781	XSRETURN_NO
		3782
		3783
		3784	Return from an XSUB
		3785	immediately. Uses XST_mNO.
		3786
		3787
		3788	XSRETURN_NO;
		3789
		3790
		3791	XSRETURN_NV
		3792
		3793
		3794	Return an double from an XSUB immediately.
		3795	Uses XST_mNV.
		3796
		3797
		3798	void XSRETURN_NV(NV nv)
		3799
		3800
		3801	XSRETURN_PV
		3802
		3803
		3804	Return a copy of a string from an XSUB
		3805	immediately. Uses XST_mPV.
		3806
		3807
		3808	void XSRETURN_PV(char* str)
		3809
		3810
		3811	XSRETURN_UNDEF
		3812
		3813
		3814	Return from an XSUB
		3815	immediately. Uses XST_mUNDEF.
		3816
		3817
		3818	XSRETURN_UNDEF;
		3819
		3820
		3821	XSRETURN_YES
		3822
		3823
		3824	Return from an XSUB
		3825	immediately. Uses XST_mYES.
		3826
		3827
		3828	XSRETURN_YES;
		3829
		3830
		3831	XST_mIV
		3832
		3833
		3834	Place an integer into the specified position pos on
		3835	the stack. The value is stored in a new mortal
		3836	SV .
		3837
		3838
		3839	void XST_mIV(int pos, IV iv)
		3840
		3841
		3842	XST_mNO
		3843
		3844
		3845	Place into the specified position
		3846	pos on the stack.
		3847
		3848
		3849	void XST_mNO(int pos)
		3850
		3851
		3852	XST_mNV
		3853
		3854
		3855	Place a double into the specified position pos on
		3856	the stack. The value is stored in a new mortal
		3857	SV .
		3858
		3859
		3860	void XST_mNV(int pos, NV nv)
		3861
		3862
		3863	XST_mPV
		3864
		3865
		3866	Place a copy of a string into the specified position
		3867	pos on the stack. The value is stored in a new
		3868	mortal SV .
		3869
		3870
		3871	void XST_mPV(int pos, char* str)
		3872
		3873
		3874	XST_mUNDEF
		3875
		3876
		3877	Place into the specified position
		3878	pos on the stack.
		3879
		3880
		3881	void XST_mUNDEF(int pos)
		3882
		3883
		3884	XST_mYES
		3885
		3886
		3887	Place into the specified position
		3888	pos on the stack.
		3889
		3890
		3891	void XST_mYES(int pos)
		3892
		3893
		3894	XS_VERSION
		3895
		3896
		3897	The version identifier for an XS module. This
		3898	is usually handled automatically by
2	perry	3899	!ExtUtils::!MakeMaker. See
1	perry	3900	XS_VERSION_BOOTCHECK.
		3901
		3902
		3903	XS_VERSION_BOOTCHECK
		3904
		3905
		3906	Macro to verify that a PM module's
		3907	$VERSION variable matches the XS
		3908	module's XS_VERSION variable. This is usually
		3909	handled automatically by xsubpp. See ``The
		3910	VERSIONCHECK: Keyword'' in
		3911	perlxs.
		3912
		3913
		3914	XS_VERSION_BOOTCHECK;
		3915
		3916
		3917	Zero
		3918
		3919
		3920	The XSUB-writer's interface to the C memzero
		3921	function. The dest is the destination,
		3922	nitems is the number of items, and type is
		3923	the type.
		3924
		3925
		3926	void Zero(void* dest, int nitems, type)
		3927	!!AUTHORS
		3928
		3929
		3930	Until May 1997, this document was maintained by Jeff Okamoto
		3931
		3932
		3933	With lots of help and suggestions from Dean Roehrich,
		3934	Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya
		3935	Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim
2	perry	3936	Bunce, Spider Boardman, Ulrich Pfeifer, Stephen !McCamant,
1	perry	3937	and Gurusamy Sarathy.
		3938
		3939
		3940	API Listing originally by Dean Roehrich
		3941
		3942
		3943	Updated to be autogenerated from comments in the source by
		3944	Benjamin Stuhl.
		3945	!!SEE ALSO
		3946
		3947
		3948	perlguts(1), perlxs(1), perlxstut(1),
		3949	perlintern(1)
		3950	----