mingw/html/pod/perlapi.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>perlapi - autogenerated documentation for the perl public API</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;perlapi - autogenerated documentation for the perl public API</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#description">DESCRIPTION</a></li>
  24         <li><a href="#gimme_values">``Gimme'' Values</a></li>
  25         <li><a href="#array_manipulation_functions">Array Manipulation Functions</a></li>
  26         <li><a href="#callback_functions">Callback Functions</a></li>
  27         <li><a href="#character_classes">Character classes</a></li>
  28         <li><a href="#cloning_an_interpreter">Cloning an interpreter</a></li>
  29         <li><a href="#cv_manipulation_functions">CV Manipulation Functions</a></li>
  30         <li><a href="#embedding_functions">Embedding Functions</a></li>
  31         <li><a href="#functions_in_file_pp_pack_c">Functions in file pp_pack.c</a></li>
  32         <li><a href="#global_variables">Global Variables</a></li>
  33         <li><a href="#gv_functions">GV Functions</a></li>
  34         <li><a href="#handy_values">Handy Values</a></li>
  35         <li><a href="#hash_manipulation_functions">Hash Manipulation Functions</a></li>
  36         <li><a href="#magical_functions">Magical Functions</a></li>
  37         <li><a href="#memory_management">Memory Management</a></li>
  38         <li><a href="#miscellaneous_functions">Miscellaneous Functions</a></li>
  39         <li><a href="#numeric_functions">Numeric functions</a></li>
  40         <li><a href="#optree_manipulation_functions">Optree Manipulation Functions</a></li>
  41         <li><a href="#pad_data_structures">Pad Data Structures</a></li>
  42         <li><a href="#stack_manipulation_macros">Stack Manipulation Macros</a></li>
  43         <li><a href="#sv_flags">SV Flags</a></li>
  44         <li><a href="#sv_manipulation_functions">SV Manipulation Functions</a></li>
  45         <li><a href="#unicode_support">Unicode Support</a></li>
  46         <li><a href="#variables_created_by_xsubpp_and_xsubpp_internal_functions">Variables created by <code>xsubpp</code> and <code>xsubpp</code> internal functions</a></li>
  47         <li><a href="#warning_and_dieing">Warning and Dieing</a></li>
  48         <li><a href="#authors">AUTHORS</a></li>
  49         <li><a href="#see_also">SEE ALSO</a></li>
  50 </ul>
  51 <!-- INDEX END -->
  52
  53 <hr />
  54 <p>
  55 </p>
  56 <h1><a name="name">NAME</a></h1>
  57 <p>perlapi - autogenerated documentation for the perl public API</p>
  58 <p>
  59 </p>
  60 <hr />
  61 <h1><a name="description_x_perl_api__x_api__x_api_">DESCRIPTION
  62   </a></h1>
  63 <p>This file contains the documentation of the perl public API generated by
  64 embed.pl, specifically a listing of functions, macros, flags, and variables
  65 that may be used by extension writers.  The interfaces of any functions that
  66 are not listed here are subject to change without notice.  For this reason,
  67 blindly using functions listed in proto.h is to be avoided when writing
  68 extensions.</p>
  69 <p>Note that all Perl API global variables must be referenced with the <code>PL_</code>
  70 prefix.  Some macros are provided for compatibility with the older,
  71 unadorned names, but this support may be disabled in a future release.</p>
  72 <p>The listing is alphabetical, case insensitive.</p>
  73 <p>
  74 </p>
  75 <hr />
  76 <h1><a name="gimme_values">``Gimme'' Values</a></h1>
  77 <dl>
  78 <dt><strong><a name="item_gimme_x_3cgimme_3e">GIMME
  79 </a></strong>
  80
  81 <dd>
  82 <p>A backward-compatible version of <code>GIMME_V</code> which can only return
  83 <code>G_SCALAR</code> or <code>G_ARRAY</code>; in a void context, it returns <code>G_SCALAR</code>.
  84 Deprecated.  Use <code>GIMME_V</code> instead.</p>
  85 </dd>
  86 <dd>
  87 <pre>
  88         U32     GIMME</pre>
  89 </dd>
  90 </li>
  91 <dt><strong><a name="item_gimme_v_x_3cgimme_v_3e">GIMME_V
  92 </a></strong>
  93
  94 <dd>
  95 <p>The XSUB-writer's equivalent to Perl's <code>wantarray</code>.  Returns <code>G_VOID</code>,
  96 <code>G_SCALAR</code> or <code>G_ARRAY</code> for void, scalar or list context,
  97 respectively.</p>
  98 </dd>
  99 <dd>
 100 <pre>
 101         U32     GIMME_V</pre>
 102 </dd>
 103 </li>
 104 <dt><strong><a name="item_g_array_x_3cg_array_3e">G_ARRAY
 105 </a></strong>
 106
 107 <dd>
 108 <p>Used to indicate list context.  See <code>GIMME_V</code>, <code>GIMME</code> and
 109 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 110 </dd>
 111 </li>
 112 <dt><strong><a name="item_g_discard_x_3cg_discard_3e">G_DISCARD
 113 </a></strong>
 114
 115 <dd>
 116 <p>Indicates that arguments returned from a callback should be discarded.  See
 117 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 118 </dd>
 119 </li>
 120 <dt><strong><a name="item_g_eval_x_3cg_eval_3e">G_EVAL
 121 </a></strong>
 122
 123 <dd>
 124 <p>Used to force a Perl <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_eval"><code>eval</code></a> wrapper around a callback.  See
 125 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 126 </dd>
 127 </li>
 128 <dt><strong><a name="item_g_noargs_x_3cg_noargs_3e">G_NOARGS
 129 </a></strong>
 130
 131 <dd>
 132 <p>Indicates that no arguments are being sent to a callback.  See
 133 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 134 </dd>
 135 </li>
 136 <dt><strong><a name="item_g_scalar_x_3cg_scalar_3e">G_SCALAR
 137 </a></strong>
 138
 139 <dd>
 140 <p>Used to indicate scalar context.  See <code>GIMME_V</code>, <code>GIMME</code>, and
 141 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 142 </dd>
 143 </li>
 144 <dt><strong><a name="item_g_void_x_3cg_void_3e">G_VOID
 145 </a></strong>
 146
 147 <dd>
 148 <p>Used to indicate void context.  See <code>GIMME_V</code> and <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 149 </dd>
 150 </li>
 151 </dl>
 152 <p>
 153 </p>
 154 <hr />
 155 <h1><a name="array_manipulation_functions">Array Manipulation Functions</a></h1>
 156 <dl>
 157 <dt><strong><a name="item_avfill_x_3cavfill_3e">AvFILL
 158 </a></strong>
 159
 160 <dd>
 161 <p>Same as <code>av_len()</code>.  Deprecated, use <code>av_len()</code> instead.</p>
 162 </dd>
 163 <dd>
 164 <pre>
 165         int     AvFILL(AV* av)</pre>
 166 </dd>
 167 </li>
 168 <dt><strong><a name="item_av_clear_x_3cav_clear_3e">av_clear
 169 </a></strong>
 170
 171 <dd>
 172 <p>Clears an array, making it empty.  Does not free the memory used by the
 173 array itself.</p>
 174 </dd>
 175 <dd>
 176 <pre>
 177         void    av_clear(AV* ar)</pre>
 178 </dd>
 179 </li>
 180 <dt><strong><a name="item_av_delete_x_3cav_delete_3e">av_delete
 181 </a></strong>
 182
 183 <dd>
 184 <p>Deletes the element indexed by <code>key</code> from the array.  Returns the
 185 deleted element. If <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> equals <code>G_DISCARD</code>, the element is freed
 186 and null is returned.</p>
 187 </dd>
 188 <dd>
 189 <pre>
 190         SV*     av_delete(AV* ar, I32 key, I32 flags)</pre>
 191 </dd>
 192 </li>
 193 <dt><strong><a name="item_av_exists_x_3cav_exists_3e">av_exists
 194 </a></strong>
 195
 196 <dd>
 197 <p>Returns true if the element indexed by <code>key</code> has been initialized.</p>
 198 </dd>
 199 <dd>
 200 <p>This relies on the fact that uninitialized array elements are set to
 201 <code>&amp;PL_sv_undef</code>.</p>
 202 </dd>
 203 <dd>
 204 <pre>
 205         bool    av_exists(AV* ar, I32 key)</pre>
 206 </dd>
 207 </li>
 208 <dt><strong><a name="item_av_extend_x_3cav_extend_3e">av_extend
 209 </a></strong>
 210
 211 <dd>
 212 <p>Pre-extend an array.  The <code>key</code> is the index to which the array should be
 213 extended.</p>
 214 </dd>
 215 <dd>
 216 <pre>
 217         void    av_extend(AV* ar, I32 key)</pre>
 218 </dd>
 219 </li>
 220 <dt><strong><a name="item_av_fetch_x_3cav_fetch_3e">av_fetch
 221 </a></strong>
 222
 223 <dd>
 224 <p>Returns the SV at the specified index in the array.  The <code>key</code> is the
 225 index.  If <code>lval</code> is set then the fetch will be part of a store.  Check
 226 that the return value is non-null before dereferencing it to a <code>SV*</code>.</p>
 227 </dd>
 228 <dd>
 229 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for
 230 more information on how to use this function on tied arrays.</p>
 231 </dd>
 232 <dd>
 233 <pre>
 234         SV**    av_fetch(AV* ar, I32 key, I32 lval)</pre>
 235 </dd>
 236 </li>
 237 <dt><strong><a name="item_av_fill_x_3cav_fill_3e">av_fill
 238 </a></strong>
 239
 240 <dd>
 241 <p>Ensure than an array has a given number of elements, equivalent to
 242 Perl's <code>$#array = $fill;</code>.</p>
 243 </dd>
 244 <dd>
 245 <pre>
 246         void    av_fill(AV* ar, I32 fill)</pre>
 247 </dd>
 248 </li>
 249 <dt><strong><a name="item_av_len_x_3cav_len_3e">av_len
 250 </a></strong>
 251
 252 <dd>
 253 <p>Returns the highest index in the array.  Returns -1 if the array is
 254 empty.</p>
 255 </dd>
 256 <dd>
 257 <pre>
 258         I32     av_len(AV* ar)</pre>
 259 </dd>
 260 </li>
 261 <dt><strong><a name="item_av_make_x_3cav_make_3e">av_make
 262 </a></strong>
 263
 264 <dd>
 265 <p>Creates a new AV and populates it with a list of SVs.  The SVs are copied
 266 into the array, so they may be freed after the call to av_make.  The new AV
 267 will have a reference count of 1.</p>
 268 </dd>
 269 <dd>
 270 <pre>
 271         AV*     av_make(I32 size, SV** svp)</pre>
 272 </dd>
 273 </li>
 274 <dt><strong><a name="item_av_pop_x_3cav_pop_3e">av_pop
 275 </a></strong>
 276
 277 <dd>
 278 <p>Pops an SV off the end of the array.  Returns <code>&amp;PL_sv_undef</code> if the array
 279 is empty.</p>
 280 </dd>
 281 <dd>
 282 <pre>
 283         SV*     av_pop(AV* ar)</pre>
 284 </dd>
 285 </li>
 286 <dt><strong><a name="item_av_push_x_3cav_push_3e">av_push
 287 </a></strong>
 288
 289 <dd>
 290 <p>Pushes an SV onto the end of the array.  The array will grow automatically
 291 to accommodate the addition.</p>
 292 </dd>
 293 <dd>
 294 <pre>
 295         void    av_push(AV* ar, SV* val)</pre>
 296 </dd>
 297 </li>
 298 <dt><strong><a name="item_av_shift_x_3cav_shift_3e">av_shift
 299 </a></strong>
 300
 301 <dd>
 302 <p>Shifts an SV off the beginning of the array.</p>
 303 </dd>
 304 <dd>
 305 <pre>
 306         SV*     av_shift(AV* ar)</pre>
 307 </dd>
 308 </li>
 309 <dt><strong><a name="item_av_store_x_3cav_store_3e">av_store
 310 </a></strong>
 311
 312 <dd>
 313 <p>Stores an SV in an array.  The array index is specified as <code>key</code>.  The
 314 return value will be NULL if the operation failed or if the value did not
 315 need to be actually stored within the array (as in the case of tied
 316 arrays). Otherwise it can be dereferenced to get the original <code>SV*</code>.  Note
 317 that the caller is responsible for suitably incrementing the reference
 318 count of <code>val</code> before the call, and decrementing it if the function
 319 returned NULL.</p>
 320 </dd>
 321 <dd>
 322 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for
 323 more information on how to use this function on tied arrays.</p>
 324 </dd>
 325 <dd>
 326 <pre>
 327         SV**    av_store(AV* ar, I32 key, SV* val)</pre>
 328 </dd>
 329 </li>
 330 <dt><strong><a name="item_av_undef_x_3cav_undef_3e">av_undef
 331 </a></strong>
 332
 333 <dd>
 334 <p>Undefines the array.  Frees the memory used by the array itself.</p>
 335 </dd>
 336 <dd>
 337 <pre>
 338         void    av_undef(AV* ar)</pre>
 339 </dd>
 340 </li>
 341 <dt><strong><a name="item_av_unshift_x_3cav_unshift_3e">av_unshift
 342 </a></strong>
 343
 344 <dd>
 345 <p>Unshift the given number of <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> values onto the beginning of the
 346 array.  The array will grow automatically to accommodate the addition.  You
 347 must then use <code>av_store</code> to assign values to these new elements.</p>
 348 </dd>
 349 <dd>
 350 <pre>
 351         void    av_unshift(AV* ar, I32 num)</pre>
 352 </dd>
 353 </li>
 354 <dt><strong><a name="item_get_av_x_3cget_av_3e">get_av
 355 </a></strong>
 356
 357 <dd>
 358 <p>Returns the AV of the specified Perl array.  If <code>create</code> is set and the
 359 Perl variable does not exist then it will be created.  If <code>create</code> is not
 360 set and the variable does not exist then NULL is returned.</p>
 361 </dd>
 362 <dd>
 363 <p>NOTE: the perl_ form of this function is deprecated.</p>
 364 </dd>
 365 <dd>
 366 <pre>
 367         AV*     get_av(const char* name, I32 create)</pre>
 368 </dd>
 369 </li>
 370 <dt><strong><a name="item_newav_x_3cnewav_3e">newAV
 371 </a></strong>
 372
 373 <dd>
 374 <p>Creates a new AV.  The reference count is set to 1.</p>
 375 </dd>
 376 <dd>
 377 <pre>
 378         AV*     newAV()</pre>
 379 </dd>
 380 </li>
 381 <dt><strong><a name="item_sortsv_x_3csortsv_3e">sortsv
 382 </a></strong>
 383
 384 <dd>
 385 <p>Sort an array. Here is an example:</p>
 386 </dd>
 387 <dd>
 388 <pre>
 389     sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);</pre>
 390 </dd>
 391 <dd>
 392 <p>See lib/sort.pm for details about controlling the sorting algorithm.</p>
 393 </dd>
 394 <dd>
 395 <pre>
 396         void    sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)</pre>
 397 </dd>
 398 </li>
 399 </dl>
 400 <p>
 401 </p>
 402 <hr />
 403 <h1><a name="callback_functions">Callback Functions</a></h1>
 404 <dl>
 405 <dt><strong><a name="item_call_argv_x_3ccall_argv_3e">call_argv
 406 </a></strong>
 407
 408 <dd>
 409 <p>Performs a callback to the specified Perl sub.  See <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 410 </dd>
 411 <dd>
 412 <p>NOTE: the perl_ form of this function is deprecated.</p>
 413 </dd>
 414 <dd>
 415 <pre>
 416         I32     call_argv(const char* sub_name, I32 flags, char** argv)</pre>
 417 </dd>
 418 </li>
 419 <dt><strong><a name="item_call_method_x_3ccall_method_3e">call_method
 420 </a></strong>
 421
 422 <dd>
 423 <p>Performs a callback to the specified Perl method.  The blessed object must
 424 be on the stack.  See <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 425 </dd>
 426 <dd>
 427 <p>NOTE: the perl_ form of this function is deprecated.</p>
 428 </dd>
 429 <dd>
 430 <pre>
 431         I32     call_method(const char* methname, I32 flags)</pre>
 432 </dd>
 433 </li>
 434 <dt><strong><a name="item_call_pv_x_3ccall_pv_3e">call_pv
 435 </a></strong>
 436
 437 <dd>
 438 <p>Performs a callback to the specified Perl sub.  See <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 439 </dd>
 440 <dd>
 441 <p>NOTE: the perl_ form of this function is deprecated.</p>
 442 </dd>
 443 <dd>
 444 <pre>
 445         I32     call_pv(const char* sub_name, I32 flags)</pre>
 446 </dd>
 447 </li>
 448 <dt><strong><a name="item_call_sv_x_3ccall_sv_3e">call_sv
 449 </a></strong>
 450
 451 <dd>
 452 <p>Performs a callback to the Perl sub whose name is in the SV.  See
 453 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 454 </dd>
 455 <dd>
 456 <p>NOTE: the perl_ form of this function is deprecated.</p>
 457 </dd>
 458 <dd>
 459 <pre>
 460         I32     call_sv(SV* sv, I32 flags)</pre>
 461 </dd>
 462 </li>
 463 <dt><strong><a name="item_enter_x_3center_3e">ENTER
 464 </a></strong>
 465
 466 <dd>
 467 <p>Opening bracket on a callback.  See <code>LEAVE</code> and <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 468 </dd>
 469 <dd>
 470 <pre>
 471                 ENTER;</pre>
 472 </dd>
 473 </li>
 474 <dt><strong><a name="item_eval_pv_x_3ceval_pv_3e">eval_pv
 475 </a></strong>
 476
 477 <dd>
 478 <p>Tells Perl to <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_eval"><code>eval</code></a> the given string and return an SV* result.</p>
 479 </dd>
 480 <dd>
 481 <p>NOTE: the perl_ form of this function is deprecated.</p>
 482 </dd>
 483 <dd>
 484 <pre>
 485         SV*     eval_pv(const char* p, I32 croak_on_error)</pre>
 486 </dd>
 487 </li>
 488 <dt><strong><a name="item_eval_sv_x_3ceval_sv_3e">eval_sv
 489 </a></strong>
 490
 491 <dd>
 492 <p>Tells Perl to <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_eval"><code>eval</code></a> the string in the SV.</p>
 493 </dd>
 494 <dd>
 495 <p>NOTE: the perl_ form of this function is deprecated.</p>
 496 </dd>
 497 <dd>
 498 <pre>
 499         I32     eval_sv(SV* sv, I32 flags)</pre>
 500 </dd>
 501 </li>
 502 <dt><strong><a name="item_freetmps_x_3cfreetmps_3e">FREETMPS
 503 </a></strong>
 504
 505 <dd>
 506 <p>Closing bracket for temporaries on a callback.  See <code>SAVETMPS</code> and
 507 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 508 </dd>
 509 <dd>
 510 <pre>
 511                 FREETMPS;</pre>
 512 </dd>
 513 </li>
 514 <dt><strong><a name="item_leave_x_3cleave_3e">LEAVE
 515 </a></strong>
 516
 517 <dd>
 518 <p>Closing bracket on a callback.  See <code>ENTER</code> and <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 519 </dd>
 520 <dd>
 521 <pre>
 522                 LEAVE;</pre>
 523 </dd>
 524 </li>
 525 <dt><strong><a name="item_savetmps_x_3csavetmps_3e">SAVETMPS
 526 </a></strong>
 527
 528 <dd>
 529 <p>Opening bracket for temporaries on a callback.  See <code>FREETMPS</code> and
 530 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
 531 </dd>
 532 <dd>
 533 <pre>
 534                 SAVETMPS;</pre>
 535 </dd>
 536 </li>
 537 </dl>
 538 <p>
 539 </p>
 540 <hr />
 541 <h1><a name="character_classes">Character classes</a></h1>
 542 <dl>
 543 <dt><strong><a name="item_isalnum_x_3cisalnum_3e">isALNUM
 544 </a></strong>
 545
 546 <dd>
 547 <p>Returns a boolean indicating whether the C <code>char</code> is an ASCII alphanumeric
 548 character (including underscore) or digit.</p>
 549 </dd>
 550 <dd>
 551 <pre>
 552         bool    isALNUM(char ch)</pre>
 553 </dd>
 554 </li>
 555 <dt><strong><a name="item_isalpha_x_3cisalpha_3e">isALPHA
 556 </a></strong>
 557
 558 <dd>
 559 <p>Returns a boolean indicating whether the C <code>char</code> is an ASCII alphabetic
 560 character.</p>
 561 </dd>
 562 <dd>
 563 <pre>
 564         bool    isALPHA(char ch)</pre>
 565 </dd>
 566 </li>
 567 <dt><strong><a name="item_isdigit_x_3cisdigit_3e">isDIGIT
 568 </a></strong>
 569
 570 <dd>
 571 <p>Returns a boolean indicating whether the C <code>char</code> is an ASCII
 572 digit.</p>
 573 </dd>
 574 <dd>
 575 <pre>
 576         bool    isDIGIT(char ch)</pre>
 577 </dd>
 578 </li>
 579 <dt><strong><a name="item_islower_x_3cislower_3e">isLOWER
 580 </a></strong>
 581
 582 <dd>
 583 <p>Returns a boolean indicating whether the C <code>char</code> is a lowercase
 584 character.</p>
 585 </dd>
 586 <dd>
 587 <pre>
 588         bool    isLOWER(char ch)</pre>
 589 </dd>
 590 </li>
 591 <dt><strong><a name="item_isspace_x_3cisspace_3e">isSPACE
 592 </a></strong>
 593
 594 <dd>
 595 <p>Returns a boolean indicating whether the C <code>char</code> is whitespace.</p>
 596 </dd>
 597 <dd>
 598 <pre>
 599         bool    isSPACE(char ch)</pre>
 600 </dd>
 601 </li>
 602 <dt><strong><a name="item_isupper_x_3cisupper_3e">isUPPER
 603 </a></strong>
 604
 605 <dd>
 606 <p>Returns a boolean indicating whether the C <code>char</code> is an uppercase
 607 character.</p>
 608 </dd>
 609 <dd>
 610 <pre>
 611         bool    isUPPER(char ch)</pre>
 612 </dd>
 613 </li>
 614 <dt><strong><a name="item_tolower_x_3ctolower_3e">toLOWER
 615 </a></strong>
 616
 617 <dd>
 618 <p>Converts the specified character to lowercase.</p>
 619 </dd>
 620 <dd>
 621 <pre>
 622         char    toLOWER(char ch)</pre>
 623 </dd>
 624 </li>
 625 <dt><strong><a name="item_toupper_x_3ctoupper_3e">toUPPER
 626 </a></strong>
 627
 628 <dd>
 629 <p>Converts the specified character to uppercase.</p>
 630 </dd>
 631 <dd>
 632 <pre>
 633         char    toUPPER(char ch)</pre>
 634 </dd>
 635 </li>
 636 </dl>
 637 <p>
 638 </p>
 639 <hr />
 640 <h1><a name="cloning_an_interpreter">Cloning an interpreter</a></h1>
 641 <dl>
 642 <dt><strong><a name="item_perl_clone_x_3cperl_clone_3e">perl_clone
 643 </a></strong>
 644
 645 <dd>
 646 <p>Create and return a new interpreter by cloning the current one.</p>
 647 </dd>
 648 <dd>
 649 <p>perl_clone takes these flags as parameters:</p>
 650 </dd>
 651 <dd>
 652 <p>CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
 653 without it we only clone the data and zero the stacks,
 654 with it we copy the stacks and the new perl interpreter is
 655 ready to run at the exact same point as the previous one.
 656 The pseudo-fork code uses COPY_STACKS while the
 657 threads-&gt;new doesn't.</p>
 658 </dd>
 659 <dd>
 660 <p>CLONEf_KEEP_PTR_TABLE
 661 perl_clone keeps a ptr_table with the pointer of the old
 662 variable as a key and the new variable as a value,
 663 this allows it to check if something has been cloned and not
 664 clone it again but rather just use the value and increase the
 665 refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
 666 the ptr_table using the function
 667 <code>ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;</code>,
 668 reason to keep it around is if you want to dup some of your own
 669 variable who are outside the graph perl scans, example of this
 670 code is in threads.xs create</p>
 671 </dd>
 672 <dd>
 673 <p>CLONEf_CLONE_HOST
 674 This is a win32 thing, it is ignored on unix, it tells perls
 675 win32host code (which is c++) to clone itself, this is needed on
 676 win32 if you want to run two threads at the same time,
 677 if you just want to do some stuff in a separate perl interpreter
 678 and then throw it away and return to the original one,
 679 you don't need to do anything.</p>
 680 </dd>
 681 <dd>
 682 <pre>
 683         PerlInterpreter*        perl_clone(PerlInterpreter* interp, UV flags)</pre>
 684 </dd>
 685 </li>
 686 </dl>
 687 <p>
 688 </p>
 689 <hr />
 690 <h1><a name="cv_manipulation_functions">CV Manipulation Functions</a></h1>
 691 <dl>
 692 <dt><strong><a name="item_cvstash_x_3ccvstash_3e">CvSTASH
 693 </a></strong>
 694
 695 <dd>
 696 <p>Returns the stash of the CV.</p>
 697 </dd>
 698 <dd>
 699 <pre>
 700         HV*     CvSTASH(CV* cv)</pre>
 701 </dd>
 702 </li>
 703 <dt><strong><a name="item_get_cv_x_3cget_cv_3e">get_cv
 704 </a></strong>
 705
 706 <dd>
 707 <p>Returns the CV of the specified Perl subroutine.  If <code>create</code> is set and
 708 the Perl subroutine does not exist then it will be declared (which has the
 709 same effect as saying <code>sub name;</code>).  If <code>create</code> is not set and the
 710 subroutine does not exist then NULL is returned.</p>
 711 </dd>
 712 <dd>
 713 <p>NOTE: the perl_ form of this function is deprecated.</p>
 714 </dd>
 715 <dd>
 716 <pre>
 717         CV*     get_cv(const char* name, I32 create)</pre>
 718 </dd>
 719 </li>
 720 </dl>
 721 <p>
 722 </p>
 723 <hr />
 724 <h1><a name="embedding_functions">Embedding Functions</a></h1>
 725 <dl>
 726 <dt><strong><a name="item_cv_undef_x_3ccv_undef_3e">cv_undef
 727 </a></strong>
 728
 729 <dd>
 730 <p>Clear out all the active components of a CV. This can happen either
 731 by an explicit <code>undef &amp;foo</code>, or by the reference count going to zero.
 732 In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
 733 children can still follow the full lexical scope chain.</p>
 734 </dd>
 735 <dd>
 736 <pre>
 737         void    cv_undef(CV* cv)</pre>
 738 </dd>
 739 </li>
 740 <dt><strong><a name="item_load_module_x_3cload_module_3e">load_module
 741 </a></strong>
 742
 743 <dd>
 744 <p>Loads the module whose name is pointed to by the string part of name.
 745 Note that the actual module name, not its filename, should be given.
 746 Eg, ``Foo::Bar'' instead of ``Foo/Bar.pm''.  flags can be any of
 747 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
 748 (or 0 for no flags). ver, if specified, provides version semantics
 749 similar to <code>use Foo::Bar VERSION</code>.  The optional trailing SV*
 750 arguments can be used to specify arguments to the module's <code>import()</code>
 751 method, similar to <code>use Foo::Bar VERSION LIST</code>.</p>
 752 </dd>
 753 <dd>
 754 <pre>
 755         void    load_module(U32 flags, SV* name, SV* ver, ...)</pre>
 756 </dd>
 757 </li>
 758 <dt><strong><a name="item_nothreadhook_x_3cnothreadhook_3e">nothreadhook
 759 </a></strong>
 760
 761 <dd>
 762 <p>Stub that provides thread hook for perl_destruct when there are
 763 no threads.</p>
 764 </dd>
 765 <dd>
 766 <pre>
 767         int     nothreadhook()</pre>
 768 </dd>
 769 </li>
 770 <dt><strong><a name="item_perl_alloc_x_3cperl_alloc_3e">perl_alloc
 771 </a></strong>
 772
 773 <dd>
 774 <p>Allocates a new Perl interpreter.  See <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>.</p>
 775 </dd>
 776 <dd>
 777 <pre>
 778         PerlInterpreter*        perl_alloc()</pre>
 779 </dd>
 780 </li>
 781 <dt><strong><a name="item_perl_construct_x_3cperl_construct_3e">perl_construct
 782 </a></strong>
 783
 784 <dd>
 785 <p>Initializes a new Perl interpreter.  See <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>.</p>
 786 </dd>
 787 <dd>
 788 <pre>
 789         void    perl_construct(PerlInterpreter* interp)</pre>
 790 </dd>
 791 </li>
 792 <dt><strong><a name="item_perl_destruct_x_3cperl_destruct_3e">perl_destruct
 793 </a></strong>
 794
 795 <dd>
 796 <p>Shuts down a Perl interpreter.  See <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>.</p>
 797 </dd>
 798 <dd>
 799 <pre>
 800         int     perl_destruct(PerlInterpreter* interp)</pre>
 801 </dd>
 802 </li>
 803 <dt><strong><a name="item_perl_free_x_3cperl_free_3e">perl_free
 804 </a></strong>
 805
 806 <dd>
 807 <p>Releases a Perl interpreter.  See <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>.</p>
 808 </dd>
 809 <dd>
 810 <pre>
 811         void    perl_free(PerlInterpreter* interp)</pre>
 812 </dd>
 813 </li>
 814 <dt><strong><a name="item_perl_parse_x_3cperl_parse_3e">perl_parse
 815 </a></strong>
 816
 817 <dd>
 818 <p>Tells a Perl interpreter to parse a Perl script.  See <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>.</p>
 819 </dd>
 820 <dd>
 821 <pre>
 822         int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)</pre>
 823 </dd>
 824 </li>
 825 <dt><strong><a name="item_perl_run_x_3cperl_run_3e">perl_run
 826 </a></strong>
 827
 828 <dd>
 829 <p>Tells a Perl interpreter to run.  See <a href="file://C|\msysgit\mingw\html/pod/perlembed.html">the perlembed manpage</a>.</p>
 830 </dd>
 831 <dd>
 832 <pre>
 833         int     perl_run(PerlInterpreter* interp)</pre>
 834 </dd>
 835 </li>
 836 <dt><strong><a name="item_require_pv_x_3crequire_pv_3e">require_pv
 837 </a></strong>
 838
 839 <dd>
 840 <p>Tells Perl to <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_require"><code>require</code></a> the file named by the string argument.  It is
 841 analogous to the Perl code <code>eval &quot;require '$file'&quot;</code>.  It's even
 842 implemented that way; consider using load_module instead.</p>
 843 </dd>
 844 <dd>
 845 <p>NOTE: the perl_ form of this function is deprecated.</p>
 846 </dd>
 847 <dd>
 848 <pre>
 849         void    require_pv(const char* pv)</pre>
 850 </dd>
 851 </li>
 852 </dl>
 853 <p>
 854 </p>
 855 <hr />
 856 <h1><a name="functions_in_file_pp_pack_c">Functions in file pp_pack.c</a></h1>
 857 <dl>
 858 <dt><strong><a name="item_packlist_x_3cpacklist_3e">packlist
 859 </a></strong>
 860
 861 <dd>
 862 <p>The engine implementing <code>pack()</code> Perl function.</p>
 863 </dd>
 864 <dd>
 865 <pre>
 866         void    packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist)</pre>
 867 </dd>
 868 </li>
 869 <dt><strong><a name="item_pack_cat_x_3cpack_cat_3e">pack_cat
 870 </a></strong>
 871
 872 <dd>
 873 <p>The engine implementing <code>pack()</code> Perl function. Note: parameters next_in_list and
 874 flags are not used. This call should not be used; use packlist instead.</p>
 875 </dd>
 876 <dd>
 877 <pre>
 878         void    pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)</pre>
 879 </dd>
 880 </li>
 881 <dt><strong><a name="item_unpackstring_x_3cunpackstring_3e">unpackstring
 882 </a></strong>
 883
 884 <dd>
 885 <p>The engine implementing <code>unpack()</code> Perl function. <code>unpackstring</code> puts the
 886 extracted list items on the stack and returns the number of elements.
 887 Issue <code>PUTBACK</code> before and <code>SPAGAIN</code> after the call to this function.</p>
 888 </dd>
 889 <dd>
 890 <pre>
 891         I32     unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags)</pre>
 892 </dd>
 893 </li>
 894 <dt><strong><a name="item_unpack_str_x_3cunpack_str_3e">unpack_str
 895 </a></strong>
 896
 897 <dd>
 898 <p>The engine implementing <code>unpack()</code> Perl function. Note: parameters strbeg, new_s
 899 and ocnt are not used. This call should not be used, use unpackstring instead.</p>
 900 </dd>
 901 <dd>
 902 <pre>
 903         I32     unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)</pre>
 904 </dd>
 905 </li>
 906 </dl>
 907 <p>
 908 </p>
 909 <hr />
 910 <h1><a name="global_variables">Global Variables</a></h1>
 911 <dl>
 912 <dt><strong><a name="item_pl_modglobal_x_3cpl_modglobal_3e">PL_modglobal
 913 </a></strong>
 914
 915 <dd>
 916 <p><code>PL_modglobal</code> is a general purpose, interpreter global HV for use by
 917 extensions that need to keep information on a per-interpreter basis.
 918 In a pinch, it can also be used as a symbol table for extensions
 919 to share data among each other.  It is a good idea to use keys
 920 prefixed by the package name of the extension that owns the data.</p>
 921 </dd>
 922 <dd>
 923 <pre>
 924         HV*     PL_modglobal</pre>
 925 </dd>
 926 </li>
 927 <dt><strong><a name="item_pl_na_x_3cpl_na_3e">PL_na
 928 </a></strong>
 929
 930 <dd>
 931 <p>A convenience variable which is typically used with <code>SvPV</code> when one
 932 doesn't care about the length of the string.  It is usually more efficient
 933 to either declare a local variable and use that instead or to use the
 934 <code>SvPV_nolen</code> macro.</p>
 935 </dd>
 936 <dd>
 937 <pre>
 938         STRLEN  PL_na</pre>
 939 </dd>
 940 </li>
 941 <dt><strong><a name="item_pl_sv_no_x_3cpl_sv_no_3e">PL_sv_no
 942 </a></strong>
 943
 944 <dd>
 945 <p>This is the <code>false</code> SV.  See <code>PL_sv_yes</code>.  Always refer to this as
 946 <code>&amp;PL_sv_no</code>.</p>
 947 </dd>
 948 <dd>
 949 <pre>
 950         SV      PL_sv_no</pre>
 951 </dd>
 952 </li>
 953 <dt><strong><a name="item_pl_sv_undef_x_3cpl_sv_undef_3e">PL_sv_undef
 954 </a></strong>
 955
 956 <dd>
 957 <p>This is the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> SV.  Always refer to this as <code>&amp;PL_sv_undef</code>.</p>
 958 </dd>
 959 <dd>
 960 <pre>
 961         SV      PL_sv_undef</pre>
 962 </dd>
 963 </li>
 964 <dt><strong><a name="item_pl_sv_yes_x_3cpl_sv_yes_3e">PL_sv_yes
 965 </a></strong>
 966
 967 <dd>
 968 <p>This is the <code>true</code> SV.  See <code>PL_sv_no</code>.  Always refer to this as
 969 <code>&amp;PL_sv_yes</code>.</p>
 970 </dd>
 971 <dd>
 972 <pre>
 973         SV      PL_sv_yes</pre>
 974 </dd>
 975 </li>
 976 </dl>
 977 <p>
 978 </p>
 979 <hr />
 980 <h1><a name="gv_functions">GV Functions</a></h1>
 981 <dl>
 982 <dt><strong><a name="item_gvsv_x_3cgvsv_3e">GvSV
 983 </a></strong>
 984
 985 <dd>
 986 <p>Return the SV from the GV.</p>
 987 </dd>
 988 <dd>
 989 <pre>
 990         SV*     GvSV(GV* gv)</pre>
 991 </dd>
 992 </li>
 993 <dt><strong><a name="item_gv_fetchmeth_x_3cgv_fetchmeth_3e">gv_fetchmeth
 994 </a></strong>
 995
 996 <dd>
 997 <p>Returns the glob with the given <code>name</code> and a defined subroutine or
 998 <code>NULL</code>.  The glob lives in the given <code>stash</code>, or in the stashes
 999 accessible via @ISA and UNIVERSAL::.</p>
1000 </dd>
1001 <dd>
1002 <p>The argument <code>level</code> should be either 0 or -1.  If <code>level==0</code>, as a
1003 side-effect creates a glob with the given <code>name</code> in the given <code>stash</code>
1004 which in the case of success contains an alias for the subroutine, and sets
1005 up caching info for this glob.  Similarly for all the searched stashes.</p>
1006 </dd>
1007 <dd>
1008 <p>This function grants <code>&quot;SUPER&quot;</code> token as a postfix of the stash name. The
1009 GV returned from <code>gv_fetchmeth</code> may be a method cache entry, which is not
1010 visible to Perl code.  So when calling <code>call_sv</code>, you should not use
1011 the GV directly; instead, you should use the method's CV, which can be
1012 obtained from the GV with the <code>GvCV</code> macro.</p>
1013 </dd>
1014 <dd>
1015 <pre>
1016         GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)</pre>
1017 </dd>
1018 </li>
1019 <dt><strong><a name="item_gv_fetchmethod_x_3cgv_fetchmethod_3e">gv_fetchmethod
1020 </a></strong>
1021
1022 <dd>
1023 <p>See <em>gv_fetchmethod_autoload</em>.</p>
1024 </dd>
1025 <dd>
1026 <pre>
1027         GV*     gv_fetchmethod(HV* stash, const char* name)</pre>
1028 </dd>
1029 </li>
1030 <dt><strong><a name="item_gv_fetchmethod_autoload_x_3cgv_fetchmethod_autoloa">gv_fetchmethod_autoload
1031 </a></strong>
1032
1033 <dd>
1034 <p>Returns the glob which contains the subroutine to call to invoke the method
1035 on the <code>stash</code>.  In fact in the presence of autoloading this may be the
1036 glob for ``AUTOLOAD''.  In this case the corresponding variable $AUTOLOAD is
1037 already setup.</p>
1038 </dd>
1039 <dd>
1040 <p>The third parameter of <code>gv_fetchmethod_autoload</code> determines whether
1041 AUTOLOAD lookup is performed if the given method is not present: non-zero
1042 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1043 Calling <code>gv_fetchmethod</code> is equivalent to calling <code>gv_fetchmethod_autoload</code>
1044 with a non-zero <code>autoload</code> parameter.</p>
1045 </dd>
1046 <dd>
1047 <p>These functions grant <code>&quot;SUPER&quot;</code> token as a prefix of the method name. Note
1048 that if you want to keep the returned glob for a long time, you need to
1049 check for it being ``AUTOLOAD'', since at the later time the call may load a
1050 different subroutine due to $AUTOLOAD changing its value. Use the glob
1051 created via a side effect to do this.</p>
1052 </dd>
1053 <dd>
1054 <p>These functions have the same side-effects and as <code>gv_fetchmeth</code> with
1055 <code>level==0</code>.  <code>name</code> should be writable if contains <code>':'</code> or <code>'
1056 ''</code>. The warning against passing the GV returned by <code>gv_fetchmeth</code> to
1057 <code>call_sv</code> apply equally to these functions.</p>
1058 </dd>
1059 <dd>
1060 <pre>
1061         GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)</pre>
1062 </dd>
1063 </li>
1064 <dt><strong><a name="item_gv_fetchmeth_autoload_x_3cgv_fetchmeth_autoload_3e">gv_fetchmeth_autoload
1065 </a></strong>
1066
1067 <dd>
1068 <p>Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1069 Returns a glob for the subroutine.</p>
1070 </dd>
1071 <dd>
1072 <p>For an autoloaded subroutine without a GV, will create a GV even
1073 if <code>level &lt; 0</code>.  For an autoloaded subroutine without a stub, <code>GvCV()</code>
1074 of the result may be zero.</p>
1075 </dd>
1076 <dd>
1077 <pre>
1078         GV*     gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)</pre>
1079 </dd>
1080 </li>
1081 <dt><strong><a name="item_gv_stashpv_x_3cgv_stashpv_3e">gv_stashpv
1082 </a></strong>
1083
1084 <dd>
1085 <p>Returns a pointer to the stash for a specified package.  <code>name</code> should
1086 be a valid UTF-8 string and must be null-terminated.  If <code>create</code> is set
1087 then the package will be created if it does not already exist.  If <code>create</code>
1088 is not set and the package does not exist then NULL is returned.</p>
1089 </dd>
1090 <dd>
1091 <pre>
1092         HV*     gv_stashpv(const char* name, I32 create)</pre>
1093 </dd>
1094 </li>
1095 <dt><strong><a name="item_gv_stashpvn_x_3cgv_stashpvn_3e">gv_stashpvn
1096 </a></strong>
1097
1098 <dd>
1099 <p>Returns a pointer to the stash for a specified package.  <code>name</code> should
1100 be a valid UTF-8 string.  The <code>namelen</code> parameter indicates the length of
1101 the <code>name</code>, in bytes.  If <code>create</code> is set then the package will be
1102 created if it does not already exist.  If <code>create</code> is not set and the
1103 package does not exist then NULL is returned.</p>
1104 </dd>
1105 <dd>
1106 <pre>
1107         HV*     gv_stashpvn(const char* name, U32 namelen, I32 create)</pre>
1108 </dd>
1109 </li>
1110 <dt><strong><a name="item_gv_stashsv_x_3cgv_stashsv_3e">gv_stashsv
1111 </a></strong>
1112
1113 <dd>
1114 <p>Returns a pointer to the stash for a specified package, which must be a
1115 valid UTF-8 string.  See <code>gv_stashpv</code>.</p>
1116 </dd>
1117 <dd>
1118 <pre>
1119         HV*     gv_stashsv(SV* sv, I32 create)</pre>
1120 </dd>
1121 </li>
1122 </dl>
1123 <p>
1124 </p>
1125 <hr />
1126 <h1><a name="handy_values">Handy Values</a></h1>
1127 <dl>
1128 <dt><strong><a name="item_nullav_x_3cnullav_3e">Nullav
1129 </a></strong>
1130
1131 <dd>
1132 <p>Null AV pointer.</p>
1133 </dd>
1134 </li>
1135 <dt><strong><a name="item_nullch_x_3cnullch_3e">Nullch
1136 </a></strong>
1137
1138 <dd>
1139 <p>Null character pointer.</p>
1140 </dd>
1141 </li>
1142 <dt><strong><a name="item_nullcv_x_3cnullcv_3e">Nullcv
1143 </a></strong>
1144
1145 <dd>
1146 <p>Null CV pointer.</p>
1147 </dd>
1148 </li>
1149 <dt><strong><a name="item_nullhv_x_3cnullhv_3e">Nullhv
1150 </a></strong>
1151
1152 <dd>
1153 <p>Null HV pointer.</p>
1154 </dd>
1155 </li>
1156 <dt><strong><a name="item_nullsv_x_3cnullsv_3e">Nullsv
1157 </a></strong>
1158
1159 <dd>
1160 <p>Null SV pointer.</p>
1161 </dd>
1162 </li>
1163 </dl>
1164 <p>
1165 </p>
1166 <hr />
1167 <h1><a name="hash_manipulation_functions">Hash Manipulation Functions</a></h1>
1168 <dl>
1169 <dt><strong><a name="item_get_hv_x_3cget_hv_3e">get_hv
1170 </a></strong>
1171
1172 <dd>
1173 <p>Returns the HV of the specified Perl hash.  If <code>create</code> is set and the
1174 Perl variable does not exist then it will be created.  If <code>create</code> is not
1175 set and the variable does not exist then NULL is returned.</p>
1176 </dd>
1177 <dd>
1178 <p>NOTE: the perl_ form of this function is deprecated.</p>
1179 </dd>
1180 <dd>
1181 <pre>
1182         HV*     get_hv(const char* name, I32 create)</pre>
1183 </dd>
1184 </li>
1185 <dt><strong><a name="item_hef_svkey_x_3chef_svkey_3e">HEf_SVKEY
1186 </a></strong>
1187
1188 <dd>
1189 <p>This flag, used in the length slot of hash entries and magic structures,
1190 specifies the structure contains an <code>SV*</code> pointer where a <code>char*</code> pointer
1191 is to be expected. (For information only--not to be used).</p>
1192 </dd>
1193 </li>
1194 <dt><strong><a name="item_hehash_x_3chehash_3e">HeHASH
1195 </a></strong>
1196
1197 <dd>
1198 <p>Returns the computed hash stored in the hash entry.</p>
1199 </dd>
1200 <dd>
1201 <pre>
1202         U32     HeHASH(HE* he)</pre>
1203 </dd>
1204 </li>
1205 <dt><strong><a name="item_hekey_x_3chekey_3e">HeKEY
1206 </a></strong>
1207
1208 <dd>
1209 <p>Returns the actual pointer stored in the key slot of the hash entry. The
1210 pointer may be either <code>char*</code> or <code>SV*</code>, depending on the value of
1211 <code>HeKLEN()</code>.  Can be assigned to.  The <code>HePV()</code> or <code>HeSVKEY()</code> macros are
1212 usually preferable for finding the value of a key.</p>
1213 </dd>
1214 <dd>
1215 <pre>
1216         void*   HeKEY(HE* he)</pre>
1217 </dd>
1218 </li>
1219 <dt><strong><a name="item_heklen_x_3cheklen_3e">HeKLEN
1220 </a></strong>
1221
1222 <dd>
1223 <p>If this is negative, and amounts to <code>HEf_SVKEY</code>, it indicates the entry
1224 holds an <code>SV*</code> key.  Otherwise, holds the actual length of the key.  Can
1225 be assigned to. The <code>HePV()</code> macro is usually preferable for finding key
1226 lengths.</p>
1227 </dd>
1228 <dd>
1229 <pre>
1230         STRLEN  HeKLEN(HE* he)</pre>
1231 </dd>
1232 </li>
1233 <dt><strong><a name="item_hepv_x_3chepv_3e">HePV
1234 </a></strong>
1235
1236 <dd>
1237 <p>Returns the key slot of the hash entry as a <code>char*</code> value, doing any
1238 necessary dereferencing of possibly <code>SV*</code> keys.  The length of the string
1239 is placed in <code>len</code> (this is a macro, so do <em>not</em> use <code>&amp;len</code>).  If you do
1240 not care about what the length of the key is, you may use the global
1241 variable <code>PL_na</code>, though this is rather less efficient than using a local
1242 variable.  Remember though, that hash keys in perl are free to contain
1243 embedded nulls, so using <code>strlen()</code> or similar is not a good way to find
1244 the length of hash keys. This is very similar to the <code>SvPV()</code> macro
1245 described elsewhere in this document.</p>
1246 </dd>
1247 <dd>
1248 <pre>
1249         char*   HePV(HE* he, STRLEN len)</pre>
1250 </dd>
1251 </li>
1252 <dt><strong><a name="item_hesvkey_x_3chesvkey_3e">HeSVKEY
1253 </a></strong>
1254
1255 <dd>
1256 <p>Returns the key as an <code>SV*</code>, or <code>Nullsv</code> if the hash entry does not
1257 contain an <code>SV*</code> key.</p>
1258 </dd>
1259 <dd>
1260 <pre>
1261         SV*     HeSVKEY(HE* he)</pre>
1262 </dd>
1263 </li>
1264 <dt><strong><a name="item_hesvkey_force_x_3chesvkey_force_3e">HeSVKEY_force
1265 </a></strong>
1266
1267 <dd>
1268 <p>Returns the key as an <code>SV*</code>.  Will create and return a temporary mortal
1269 <code>SV*</code> if the hash entry contains only a <code>char*</code> key.</p>
1270 </dd>
1271 <dd>
1272 <pre>
1273         SV*     HeSVKEY_force(HE* he)</pre>
1274 </dd>
1275 </li>
1276 <dt><strong><a name="item_hesvkey_set_x_3chesvkey_set_3e">HeSVKEY_set
1277 </a></strong>
1278
1279 <dd>
1280 <p>Sets the key to a given <code>SV*</code>, taking care to set the appropriate flags to
1281 indicate the presence of an <code>SV*</code> key, and returns the same
1282 <code>SV*</code>.</p>
1283 </dd>
1284 <dd>
1285 <pre>
1286         SV*     HeSVKEY_set(HE* he, SV* sv)</pre>
1287 </dd>
1288 </li>
1289 <dt><strong><a name="item_heval_x_3cheval_3e">HeVAL
1290 </a></strong>
1291
1292 <dd>
1293 <p>Returns the value slot (type <code>SV*</code>) stored in the hash entry.</p>
1294 </dd>
1295 <dd>
1296 <pre>
1297         SV*     HeVAL(HE* he)</pre>
1298 </dd>
1299 </li>
1300 <dt><strong><a name="item_hvname_x_3chvname_3e">HvNAME
1301 </a></strong>
1302
1303 <dd>
1304 <p>Returns the package name of a stash.  See <code>SvSTASH</code>, <code>CvSTASH</code>.</p>
1305 </dd>
1306 <dd>
1307 <pre>
1308         char*   HvNAME(HV* stash)</pre>
1309 </dd>
1310 </li>
1311 <dt><strong><a name="item_hv_clear_x_3chv_clear_3e">hv_clear
1312 </a></strong>
1313
1314 <dd>
1315 <p>Clears a hash, making it empty.</p>
1316 </dd>
1317 <dd>
1318 <pre>
1319         void    hv_clear(HV* tb)</pre>
1320 </dd>
1321 </li>
1322 <dt><strong><a name="item_hv_clear_placeholders_x_3chv_clear_placeholders_3e">hv_clear_placeholders
1323 </a></strong>
1324
1325 <dd>
1326 <p>Clears any placeholders from a hash.  If a restricted hash has any of its keys
1327 marked as readonly and the key is subsequently deleted, the key is not actually
1328 deleted but is marked by assigning it a value of &amp;PL_sv_placeholder.  This tags
1329 it so it will be ignored by future operations such as iterating over the hash,
1330 but will still allow the hash to have a value reassigned to the key at some
1331 future point.  This function clears any such placeholder keys from the hash.
1332 See Hash::Util::lock_keys() for an example of its use.</p>
1333 </dd>
1334 <dd>
1335 <pre>
1336         void    hv_clear_placeholders(HV* hb)</pre>
1337 </dd>
1338 </li>
1339 <dt><strong><a name="item_hv_delete_x_3chv_delete_3e">hv_delete
1340 </a></strong>
1341
1342 <dd>
1343 <p>Deletes a key/value pair in the hash.  The value SV is removed from the
1344 hash and returned to the caller.  The <code>klen</code> is the length of the key.
1345 The <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> value will normally be zero; if set to G_DISCARD then NULL
1346 will be returned.</p>
1347 </dd>
1348 <dd>
1349 <pre>
1350         SV*     hv_delete(HV* tb, const char* key, I32 klen, I32 flags)</pre>
1351 </dd>
1352 </li>
1353 <dt><strong><a name="item_hv_delete_ent_x_3chv_delete_ent_3e">hv_delete_ent
1354 </a></strong>
1355
1356 <dd>
1357 <p>Deletes a key/value pair in the hash.  The value SV is removed from the
1358 hash and returned to the caller.  The <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> value will normally be zero;
1359 if set to G_DISCARD then NULL will be returned.  <code>hash</code> can be a valid
1360 precomputed hash value, or 0 to ask for it to be computed.</p>
1361 </dd>
1362 <dd>
1363 <pre>
1364         SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)</pre>
1365 </dd>
1366 </li>
1367 <dt><strong><a name="item_hv_exists_x_3chv_exists_3e">hv_exists
1368 </a></strong>
1369
1370 <dd>
1371 <p>Returns a boolean indicating whether the specified hash key exists.  The
1372 <code>klen</code> is the length of the key.</p>
1373 </dd>
1374 <dd>
1375 <pre>
1376         bool    hv_exists(HV* tb, const char* key, I32 klen)</pre>
1377 </dd>
1378 </li>
1379 <dt><strong><a name="item_hv_exists_ent_x_3chv_exists_ent_3e">hv_exists_ent
1380 </a></strong>
1381
1382 <dd>
1383 <p>Returns a boolean indicating whether the specified hash key exists. <code>hash</code>
1384 can be a valid precomputed hash value, or 0 to ask for it to be
1385 computed.</p>
1386 </dd>
1387 <dd>
1388 <pre>
1389         bool    hv_exists_ent(HV* tb, SV* key, U32 hash)</pre>
1390 </dd>
1391 </li>
1392 <dt><strong><a name="item_hv_fetch_x_3chv_fetch_3e">hv_fetch
1393 </a></strong>
1394
1395 <dd>
1396 <p>Returns the SV which corresponds to the specified key in the hash.  The
1397 <code>klen</code> is the length of the key.  If <code>lval</code> is set then the fetch will be
1398 part of a store.  Check that the return value is non-null before
1399 dereferencing it to an <code>SV*</code>.</p>
1400 </dd>
1401 <dd>
1402 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for more
1403 information on how to use this function on tied hashes.</p>
1404 </dd>
1405 <dd>
1406 <pre>
1407         SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)</pre>
1408 </dd>
1409 </li>
1410 <dt><strong><a name="item_hv_fetch_ent_x_3chv_fetch_ent_3e">hv_fetch_ent
1411 </a></strong>
1412
1413 <dd>
1414 <p>Returns the hash entry which corresponds to the specified key in the hash.
1415 <code>hash</code> must be a valid precomputed hash number for the given <code>key</code>, or 0
1416 if you want the function to compute it.  IF <code>lval</code> is set then the fetch
1417 will be part of a store.  Make sure the return value is non-null before
1418 accessing it.  The return value when <code>tb</code> is a tied hash is a pointer to a
1419 static location, so be sure to make a copy of the structure if you need to
1420 store it somewhere.</p>
1421 </dd>
1422 <dd>
1423 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for more
1424 information on how to use this function on tied hashes.</p>
1425 </dd>
1426 <dd>
1427 <pre>
1428         HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)</pre>
1429 </dd>
1430 </li>
1431 <dt><strong><a name="item_hv_iterinit_x_3chv_iterinit_3e">hv_iterinit
1432 </a></strong>
1433
1434 <dd>
1435 <p>Prepares a starting point to traverse a hash table.  Returns the number of
1436 keys in the hash (i.e. the same as <code>HvKEYS(tb)</code>).  The return value is
1437 currently only meaningful for hashes without tie magic.</p>
1438 </dd>
1439 <dd>
1440 <p>NOTE: Before version 5.004_65, <code>hv_iterinit</code> used to return the number of
1441 hash buckets that happen to be in use.  If you still need that esoteric
1442 value, you can get it through the macro <code>HvFILL(tb)</code>.</p>
1443 </dd>
1444 <dd>
1445 <pre>
1446         I32     hv_iterinit(HV* tb)</pre>
1447 </dd>
1448 </li>
1449 <dt><strong><a name="item_hv_iterkey_x_3chv_iterkey_3e">hv_iterkey
1450 </a></strong>
1451
1452 <dd>
1453 <p>Returns the key from the current position of the hash iterator.  See
1454 <code>hv_iterinit</code>.</p>
1455 </dd>
1456 <dd>
1457 <pre>
1458         char*   hv_iterkey(HE* entry, I32* retlen)</pre>
1459 </dd>
1460 </li>
1461 <dt><strong><a name="item_hv_iterkeysv_x_3chv_iterkeysv_3e">hv_iterkeysv
1462 </a></strong>
1463
1464 <dd>
1465 <p>Returns the key as an <code>SV*</code> from the current position of the hash
1466 iterator.  The return value will always be a mortal copy of the key.  Also
1467 see <code>hv_iterinit</code>.</p>
1468 </dd>
1469 <dd>
1470 <pre>
1471         SV*     hv_iterkeysv(HE* entry)</pre>
1472 </dd>
1473 </li>
1474 <dt><strong><a name="item_hv_iternext_x_3chv_iternext_3e">hv_iternext
1475 </a></strong>
1476
1477 <dd>
1478 <p>Returns entries from a hash iterator.  See <code>hv_iterinit</code>.</p>
1479 </dd>
1480 <dd>
1481 <p>You may call <code>hv_delete</code> or <code>hv_delete_ent</code> on the hash entry that the
1482 iterator currently points to, without losing your place or invalidating your
1483 iterator.  Note that in this case the current entry is deleted from the hash
1484 with your iterator holding the last reference to it.  Your iterator is flagged
1485 to free the entry on the next call to <code>hv_iternext</code>, so you must not discard
1486 your iterator immediately else the entry will leak - call <code>hv_iternext</code> to
1487 trigger the resource deallocation.</p>
1488 </dd>
1489 <dd>
1490 <pre>
1491         HE*     hv_iternext(HV* tb)</pre>
1492 </dd>
1493 </li>
1494 <dt><strong><a name="item_hv_iternextsv_x_3chv_iternextsv_3e">hv_iternextsv
1495 </a></strong>
1496
1497 <dd>
1498 <p>Performs an <code>hv_iternext</code>, <code>hv_iterkey</code>, and <code>hv_iterval</code> in one
1499 operation.</p>
1500 </dd>
1501 <dd>
1502 <pre>
1503         SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)</pre>
1504 </dd>
1505 </li>
1506 <dt><strong><a name="item_hv_iternext_flags_x_3chv_iternext_flags_3e">hv_iternext_flags
1507 </a></strong>
1508
1509 <dd>
1510 <p>Returns entries from a hash iterator.  See <code>hv_iterinit</code> and <code>hv_iternext</code>.
1511 The <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1512 set the placeholders keys (for restricted hashes) will be returned in addition
1513 to normal keys. By default placeholders are automatically skipped over.
1514 Currently a placeholder is implemented with a value that is
1515 <code>&amp;Perl_sv_placeholder</code>. Note that the implementation of placeholders and
1516 restricted hashes may change, and the implementation currently is
1517 insufficiently abstracted for any change to be tidy.</p>
1518 </dd>
1519 <dd>
1520 <p>NOTE: this function is experimental and may change or be
1521 removed without notice.</p>
1522 </dd>
1523 <dd>
1524 <pre>
1525         HE*     hv_iternext_flags(HV* tb, I32 flags)</pre>
1526 </dd>
1527 </li>
1528 <dt><strong><a name="item_hv_iterval_x_3chv_iterval_3e">hv_iterval
1529 </a></strong>
1530
1531 <dd>
1532 <p>Returns the value from the current position of the hash iterator.  See
1533 <code>hv_iterkey</code>.</p>
1534 </dd>
1535 <dd>
1536 <pre>
1537         SV*     hv_iterval(HV* tb, HE* entry)</pre>
1538 </dd>
1539 </li>
1540 <dt><strong><a name="item_hv_magic_x_3chv_magic_3e">hv_magic
1541 </a></strong>
1542
1543 <dd>
1544 <p>Adds magic to a hash.  See <code>sv_magic</code>.</p>
1545 </dd>
1546 <dd>
1547 <pre>
1548         void    hv_magic(HV* hv, GV* gv, int how)</pre>
1549 </dd>
1550 </li>
1551 <dt><strong><a name="item_hv_scalar_x_3chv_scalar_3e">hv_scalar
1552 </a></strong>
1553
1554 <dd>
1555 <p>Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.</p>
1556 </dd>
1557 <dd>
1558 <pre>
1559         SV*     hv_scalar(HV* hv)</pre>
1560 </dd>
1561 </li>
1562 <dt><strong><a name="item_hv_store_x_3chv_store_3e">hv_store
1563 </a></strong>
1564
1565 <dd>
1566 <p>Stores an SV in a hash.  The hash key is specified as <code>key</code> and <code>klen</code> is
1567 the length of the key.  The <code>hash</code> parameter is the precomputed hash
1568 value; if it is zero then Perl will compute it.  The return value will be
1569 NULL if the operation failed or if the value did not need to be actually
1570 stored within the hash (as in the case of tied hashes).  Otherwise it can
1571 be dereferenced to get the original <code>SV*</code>.  Note that the caller is
1572 responsible for suitably incrementing the reference count of <code>val</code> before
1573 the call, and decrementing it if the function returned NULL.  Effectively
1574 a successful hv_store takes ownership of one reference to <code>val</code>.  This is
1575 usually what you want; a newly created SV has a reference count of one, so
1576 if all your code does is create SVs then store them in a hash, hv_store
1577 will own the only reference to the new SV, and your code doesn't need to do
1578 anything further to tidy up.  hv_store is not implemented as a call to
1579 hv_store_ent, and does not create a temporary SV for the key, so if your
1580 key data is not already in SV form then use hv_store in preference to
1581 hv_store_ent.</p>
1582 </dd>
1583 <dd>
1584 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for more
1585 information on how to use this function on tied hashes.</p>
1586 </dd>
1587 <dd>
1588 <pre>
1589         SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)</pre>
1590 </dd>
1591 </li>
1592 <dt><strong><a name="item_hv_store_ent_x_3chv_store_ent_3e">hv_store_ent
1593 </a></strong>
1594
1595 <dd>
1596 <p>Stores <code>val</code> in a hash.  The hash key is specified as <code>key</code>.  The <code>hash</code>
1597 parameter is the precomputed hash value; if it is zero then Perl will
1598 compute it.  The return value is the new hash entry so created.  It will be
1599 NULL if the operation failed or if the value did not need to be actually
1600 stored within the hash (as in the case of tied hashes).  Otherwise the
1601 contents of the return value can be accessed using the <code>He?</code> macros
1602 described here.  Note that the caller is responsible for suitably
1603 incrementing the reference count of <code>val</code> before the call, and
1604 decrementing it if the function returned NULL.  Effectively a successful
1605 hv_store_ent takes ownership of one reference to <code>val</code>.  This is
1606 usually what you want; a newly created SV has a reference count of one, so
1607 if all your code does is create SVs then store them in a hash, hv_store
1608 will own the only reference to the new SV, and your code doesn't need to do
1609 anything further to tidy up.  Note that hv_store_ent only reads the <code>key</code>;
1610 unlike <code>val</code> it does not take ownership of it, so maintaining the correct
1611 reference count on <code>key</code> is entirely the caller's responsibility.  hv_store
1612 is not implemented as a call to hv_store_ent, and does not create a temporary
1613 SV for the key, so if your key data is not already in SV form then use
1614 hv_store in preference to hv_store_ent.</p>
1615 </dd>
1616 <dd>
1617 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for more
1618 information on how to use this function on tied hashes.</p>
1619 </dd>
1620 <dd>
1621 <pre>
1622         HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)</pre>
1623 </dd>
1624 </li>
1625 <dt><strong><a name="item_hv_undef_x_3chv_undef_3e">hv_undef
1626 </a></strong>
1627
1628 <dd>
1629 <p>Undefines the hash.</p>
1630 </dd>
1631 <dd>
1632 <pre>
1633         void    hv_undef(HV* tb)</pre>
1634 </dd>
1635 </li>
1636 <dt><strong><a name="item_newhv_x_3cnewhv_3e">newHV
1637 </a></strong>
1638
1639 <dd>
1640 <p>Creates a new HV.  The reference count is set to 1.</p>
1641 </dd>
1642 <dd>
1643 <pre>
1644         HV*     newHV()</pre>
1645 </dd>
1646 </li>
1647 </dl>
1648 <p>
1649 </p>
1650 <hr />
1651 <h1><a name="magical_functions">Magical Functions</a></h1>
1652 <dl>
1653 <dt><strong><a name="item_mg_clear_x_3cmg_clear_3e">mg_clear
1654 </a></strong>
1655
1656 <dd>
1657 <p>Clear something magical that the SV represents.  See <code>sv_magic</code>.</p>
1658 </dd>
1659 <dd>
1660 <pre>
1661         int     mg_clear(SV* sv)</pre>
1662 </dd>
1663 </li>
1664 <dt><strong><a name="item_mg_copy_x_3cmg_copy_3e">mg_copy
1665 </a></strong>
1666
1667 <dd>
1668 <p>Copies the magic from one SV to another.  See <code>sv_magic</code>.</p>
1669 </dd>
1670 <dd>
1671 <pre>
1672         int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)</pre>
1673 </dd>
1674 </li>
1675 <dt><strong><a name="item_mg_find_x_3cmg_find_3e">mg_find
1676 </a></strong>
1677
1678 <dd>
1679 <p>Finds the magic pointer for type matching the SV.  See <code>sv_magic</code>.</p>
1680 </dd>
1681 <dd>
1682 <pre>
1683         MAGIC*  mg_find(SV* sv, int type)</pre>
1684 </dd>
1685 </li>
1686 <dt><strong><a name="item_mg_free_x_3cmg_free_3e">mg_free
1687 </a></strong>
1688
1689 <dd>
1690 <p>Free any magic storage used by the SV.  See <code>sv_magic</code>.</p>
1691 </dd>
1692 <dd>
1693 <pre>
1694         int     mg_free(SV* sv)</pre>
1695 </dd>
1696 </li>
1697 <dt><strong><a name="item_mg_get_x_3cmg_get_3e">mg_get
1698 </a></strong>
1699
1700 <dd>
1701 <p>Do magic after a value is retrieved from the SV.  See <code>sv_magic</code>.</p>
1702 </dd>
1703 <dd>
1704 <pre>
1705         int     mg_get(SV* sv)</pre>
1706 </dd>
1707 </li>
1708 <dt><strong><a name="item_mg_length_x_3cmg_length_3e">mg_length
1709 </a></strong>
1710
1711 <dd>
1712 <p>Report on the SV's length.  See <code>sv_magic</code>.</p>
1713 </dd>
1714 <dd>
1715 <pre>
1716         U32     mg_length(SV* sv)</pre>
1717 </dd>
1718 </li>
1719 <dt><strong><a name="item_mg_magical_x_3cmg_magical_3e">mg_magical
1720 </a></strong>
1721
1722 <dd>
1723 <p>Turns on the magical status of an SV.  See <code>sv_magic</code>.</p>
1724 </dd>
1725 <dd>
1726 <pre>
1727         void    mg_magical(SV* sv)</pre>
1728 </dd>
1729 </li>
1730 <dt><strong><a name="item_mg_set_x_3cmg_set_3e">mg_set
1731 </a></strong>
1732
1733 <dd>
1734 <p>Do magic after a value is assigned to the SV.  See <code>sv_magic</code>.</p>
1735 </dd>
1736 <dd>
1737 <pre>
1738         int     mg_set(SV* sv)</pre>
1739 </dd>
1740 </li>
1741 <dt><strong><a name="item_svgetmagic_x_3csvgetmagic_3e">SvGETMAGIC
1742 </a></strong>
1743
1744 <dd>
1745 <p>Invokes <code>mg_get</code> on an SV if it has 'get' magic.  This macro evaluates its
1746 argument more than once.</p>
1747 </dd>
1748 <dd>
1749 <pre>
1750         void    SvGETMAGIC(SV* sv)</pre>
1751 </dd>
1752 </li>
1753 <dt><strong><a name="item_svlock_x_3csvlock_3e">SvLOCK
1754 </a></strong>
1755
1756 <dd>
1757 <p>Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
1758 has been loaded.</p>
1759 </dd>
1760 <dd>
1761 <pre>
1762         void    SvLOCK(SV* sv)</pre>
1763 </dd>
1764 </li>
1765 <dt><strong><a name="item_svsetmagic_x_3csvsetmagic_3e">SvSETMAGIC
1766 </a></strong>
1767
1768 <dd>
1769 <p>Invokes <code>mg_set</code> on an SV if it has 'set' magic.  This macro evaluates its
1770 argument more than once.</p>
1771 </dd>
1772 <dd>
1773 <pre>
1774         void    SvSETMAGIC(SV* sv)</pre>
1775 </dd>
1776 </li>
1777 <dt><strong><a name="item_svsetmagicsv_x_3csvsetmagicsv_3e">SvSetMagicSV
1778 </a></strong>
1779
1780 <dd>
1781 <p>Like <code>SvSetSV</code>, but does any set magic required afterwards.</p>
1782 </dd>
1783 <dd>
1784 <pre>
1785         void    SvSetMagicSV(SV* dsb, SV* ssv)</pre>
1786 </dd>
1787 </li>
1788 <dt><strong><a name="item_svsetmagicsv_nosteal_x_3csvsetmagicsv_nosteal_3e">SvSetMagicSV_nosteal
1789 </a></strong>
1790
1791 <dd>
1792 <p>Like <code>SvSetSV_nosteal</code>, but does any set magic required afterwards.</p>
1793 </dd>
1794 <dd>
1795 <pre>
1796         void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)</pre>
1797 </dd>
1798 </li>
1799 <dt><strong><a name="item_svsetsv_x_3csvsetsv_3e">SvSetSV
1800 </a></strong>
1801
1802 <dd>
1803 <p>Calls <code>sv_setsv</code> if dsv is not the same as ssv.  May evaluate arguments
1804 more than once.</p>
1805 </dd>
1806 <dd>
1807 <pre>
1808         void    SvSetSV(SV* dsb, SV* ssv)</pre>
1809 </dd>
1810 </li>
1811 <dt><strong><a name="item_svsetsv_nosteal_x_3csvsetsv_nosteal_3e">SvSetSV_nosteal
1812 </a></strong>
1813
1814 <dd>
1815 <p>Calls a non-destructive version of <code>sv_setsv</code> if dsv is not the same as
1816 ssv. May evaluate arguments more than once.</p>
1817 </dd>
1818 <dd>
1819 <pre>
1820         void    SvSetSV_nosteal(SV* dsv, SV* ssv)</pre>
1821 </dd>
1822 </li>
1823 <dt><strong><a name="item_svshare_x_3csvshare_3e">SvSHARE
1824 </a></strong>
1825
1826 <dd>
1827 <p>Arranges for sv to be shared between threads if a suitable module
1828 has been loaded.</p>
1829 </dd>
1830 <dd>
1831 <pre>
1832         void    SvSHARE(SV* sv)</pre>
1833 </dd>
1834 </li>
1835 <dt><strong><a name="item_svunlock_x_3csvunlock_3e">SvUNLOCK
1836 </a></strong>
1837
1838 <dd>
1839 <p>Releases a mutual exclusion lock on sv if a suitable module
1840 has been loaded.</p>
1841 </dd>
1842 <dd>
1843 <pre>
1844         void    SvUNLOCK(SV* sv)</pre>
1845 </dd>
1846 </li>
1847 </dl>
1848 <p>
1849 </p>
1850 <hr />
1851 <h1><a name="memory_management">Memory Management</a></h1>
1852 <dl>
1853 <dt><strong><a name="item_copy_x_3ccopy_3e">Copy
1854 </a></strong>
1855
1856 <dd>
1857 <p>The XSUB-writer's interface to the C <code>memcpy</code> function.  The <code>src</code> is the
1858 source, <code>dest</code> is the destination, <code>nitems</code> is the number of items, and <code>type</code> is
1859 the type.  May fail on overlapping copies.  See also <code>Move</code>.</p>
1860 </dd>
1861 <dd>
1862 <pre>
1863         void    Copy(void* src, void* dest, int nitems, type)</pre>
1864 </dd>
1865 </li>
1866 <dt><strong><a name="item_copyd_x_3ccopyd_3e">CopyD
1867 </a></strong>
1868
1869 <dd>
1870 <p>Like <code>Copy</code> but returns dest. Useful for encouraging compilers to tail-call
1871 optimise.</p>
1872 </dd>
1873 <dd>
1874 <pre>
1875         void *  CopyD(void* src, void* dest, int nitems, type)</pre>
1876 </dd>
1877 </li>
1878 <dt><strong><a name="item_move_x_3cmove_3e">Move
1879 </a></strong>
1880
1881 <dd>
1882 <p>The XSUB-writer's interface to the C <code>memmove</code> function.  The <code>src</code> is the
1883 source, <code>dest</code> is the destination, <code>nitems</code> is the number of items, and <code>type</code> is
1884 the type.  Can do overlapping moves.  See also <code>Copy</code>.</p>
1885 </dd>
1886 <dd>
1887 <pre>
1888         void    Move(void* src, void* dest, int nitems, type)</pre>
1889 </dd>
1890 </li>
1891 <dt><strong><a name="item_moved_x_3cmoved_3e">MoveD
1892 </a></strong>
1893
1894 <dd>
1895 <p>Like <code>Move</code> but returns dest. Useful for encouraging compilers to tail-call
1896 optimise.</p>
1897 </dd>
1898 <dd>
1899 <pre>
1900         void *  MoveD(void* src, void* dest, int nitems, type)</pre>
1901 </dd>
1902 </li>
1903 <dt><strong><a name="item_newx_x_3cnewx_3e">Newx
1904 </a></strong>
1905
1906 <dd>
1907 <p>The XSUB-writer's interface to the C <code>malloc</code> function.</p>
1908 </dd>
1909 <dd>
1910 <pre>
1911         void    Newx(void* ptr, int nitems, type)</pre>
1912 </dd>
1913 </li>
1914 <dt><strong><a name="item_newxc_x_3cnewxc_3e">Newxc
1915 </a></strong>
1916
1917 <dd>
1918 <p>The XSUB-writer's interface to the C <code>malloc</code> function, with
1919 cast.</p>
1920 </dd>
1921 <dd>
1922 <pre>
1923         void    Newxc(void* ptr, int nitems, type, cast)</pre>
1924 </dd>
1925 </li>
1926 <dt><strong><a name="item_newxz_x_3cnewxz_3e">Newxz
1927 </a></strong>
1928
1929 <dd>
1930 <p>The XSUB-writer's interface to the C <code>malloc</code> function.  The allocated
1931 memory is zeroed with <code>memzero</code>.</p>
1932 </dd>
1933 <dd>
1934 <p>In 5.9.3, we removed the 1st parameter, a debug aid, from the api.  It
1935 was used to uniquely identify each usage of these allocation
1936 functions, but was deemed unnecessary with the availability of better
1937 memory tracking tools, valgrind for example.</p>
1938 </dd>
1939 <dd>
1940 <pre>
1941         void    Newxz(void* ptr, int nitems, type)</pre>
1942 </dd>
1943 </li>
1944 <dt><strong><a name="item_poison_x_3cpoison_3e">Poison
1945 </a></strong>
1946
1947 <dd>
1948 <p>Fill up memory with a pattern (byte 0xAB over and over again) that
1949 hopefully catches attempts to access uninitialized memory.</p>
1950 </dd>
1951 <dd>
1952 <pre>
1953         void    Poison(void* dest, int nitems, type)</pre>
1954 </dd>
1955 </li>
1956 <dt><strong><a name="item_renew_x_3crenew_3e">Renew
1957 </a></strong>
1958
1959 <dd>
1960 <p>The XSUB-writer's interface to the C <code>realloc</code> function.</p>
1961 </dd>
1962 <dd>
1963 <pre>
1964         void    Renew(void* ptr, int nitems, type)</pre>
1965 </dd>
1966 </li>
1967 <dt><strong><a name="item_renewc_x_3crenewc_3e">Renewc
1968 </a></strong>
1969
1970 <dd>
1971 <p>The XSUB-writer's interface to the C <code>realloc</code> function, with
1972 cast.</p>
1973 </dd>
1974 <dd>
1975 <pre>
1976         void    Renewc(void* ptr, int nitems, type, cast)</pre>
1977 </dd>
1978 </li>
1979 <dt><strong><a name="item_safefree_x_3csafefree_3e">Safefree
1980 </a></strong>
1981
1982 <dd>
1983 <p>The XSUB-writer's interface to the C <code>free</code> function.</p>
1984 </dd>
1985 <dd>
1986 <pre>
1987         void    Safefree(void* ptr)</pre>
1988 </dd>
1989 </li>
1990 <dt><strong><a name="item_savepv_x_3csavepv_3e">savepv
1991 </a></strong>
1992
1993 <dd>
1994 <p>Perl's version of <code>strdup()</code>. Returns a pointer to a newly allocated
1995 string which is a duplicate of <code>pv</code>. The size of the string is
1996 determined by <code>strlen()</code>. The memory allocated for the new string can
1997 be freed with the <code>Safefree()</code> function.</p>
1998 </dd>
1999 <dd>
2000 <pre>
2001         char*   savepv(const char* pv)</pre>
2002 </dd>
2003 </li>
2004 <dt><strong><a name="item_savepvn_x_3csavepvn_3e">savepvn
2005 </a></strong>
2006
2007 <dd>
2008 <p>Perl's version of what <code>strndup()</code> would be if it existed. Returns a
2009 pointer to a newly allocated string which is a duplicate of the first
2010 <code>len</code> bytes from <code>pv</code>. The memory allocated for the new string can be
2011 freed with the <code>Safefree()</code> function.</p>
2012 </dd>
2013 <dd>
2014 <pre>
2015         char*   savepvn(const char* pv, I32 len)</pre>
2016 </dd>
2017 </li>
2018 <dt><strong><a name="item_savesharedpv_x_3csavesharedpv_3e">savesharedpv
2019 </a></strong>
2020
2021 <dd>
2022 <p>A version of <code>savepv()</code> which allocates the duplicate string in memory
2023 which is shared between threads.</p>
2024 </dd>
2025 <dd>
2026 <pre>
2027         char*   savesharedpv(const char* pv)</pre>
2028 </dd>
2029 </li>
2030 <dt><strong><a name="item_savesvpv_x_3csavesvpv_3e">savesvpv
2031 </a></strong>
2032
2033 <dd>
2034 <p>A version of <code>savepv()</code>/<code>savepvn()</code> which gets the string to duplicate from
2035 the passed in SV using <code>SvPV()</code></p>
2036 </dd>
2037 <dd>
2038 <pre>
2039         char*   savesvpv(SV* sv)</pre>
2040 </dd>
2041 </li>
2042 <dt><strong><a name="item_structcopy_x_3cstructcopy_3e">StructCopy
2043 </a></strong>
2044
2045 <dd>
2046 <p>This is an architecture-independent macro to copy one structure to another.</p>
2047 </dd>
2048 <dd>
2049 <pre>
2050         void    StructCopy(type src, type dest, type)</pre>
2051 </dd>
2052 </li>
2053 <dt><strong><a name="item_zero_x_3czero_3e">Zero
2054 </a></strong>
2055
2056 <dd>
2057 <p>The XSUB-writer's interface to the C <code>memzero</code> function.  The <code>dest</code> is the
2058 destination, <code>nitems</code> is the number of items, and <code>type</code> is the type.</p>
2059 </dd>
2060 <dd>
2061 <pre>
2062         void    Zero(void* dest, int nitems, type)</pre>
2063 </dd>
2064 </li>
2065 <dt><strong><a name="item_zerod_x_3czerod_3e">ZeroD
2066 </a></strong>
2067
2068 <dd>
2069 <p>Like <code>Zero</code> but returns dest. Useful for encouraging compilers to tail-call
2070 optimise.</p>
2071 </dd>
2072 <dd>
2073 <pre>
2074         void *  ZeroD(void* dest, int nitems, type)</pre>
2075 </dd>
2076 </li>
2077 </dl>
2078 <p>
2079 </p>
2080 <hr />
2081 <h1><a name="miscellaneous_functions">Miscellaneous Functions</a></h1>
2082 <dl>
2083 <dt><strong><a name="item_fbm_compile_x_3cfbm_compile_3e">fbm_compile
2084 </a></strong>
2085
2086 <dd>
2087 <p>Analyses the string in order to make fast searches on it using <code>fbm_instr()</code>
2088 -- the Boyer-Moore algorithm.</p>
2089 </dd>
2090 <dd>
2091 <pre>
2092         void    fbm_compile(SV* sv, U32 flags)</pre>
2093 </dd>
2094 </li>
2095 <dt><strong><a name="item_fbm_instr_x_3cfbm_instr_3e">fbm_instr
2096 </a></strong>
2097
2098 <dd>
2099 <p>Returns the location of the SV in the string delimited by <code>str</code> and
2100 <code>strend</code>.  It returns <code>Nullch</code> if the string can't be found.  The <code>sv</code>
2101 does not have to be fbm_compiled, but the search will not be as fast
2102 then.</p>
2103 </dd>
2104 <dd>
2105 <pre>
2106         char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)</pre>
2107 </dd>
2108 </li>
2109 <dt><strong><a name="item_form_x_3cform_3e">form
2110 </a></strong>
2111
2112 <dd>
2113 <p>Takes a sprintf-style format pattern and conventional
2114 (non-SV) arguments and returns the formatted string.</p>
2115 </dd>
2116 <dd>
2117 <pre>
2118     (char *) Perl_form(pTHX_ const char* pat, ...)</pre>
2119 </dd>
2120 <dd>
2121 <p>can be used any place a string (char *) is required:</p>
2122 </dd>
2123 <dd>
2124 <pre>
2125     char * s = Perl_form(&quot;%d.%d&quot;,major,minor);</pre>
2126 </dd>
2127 <dd>
2128 <p>Uses a single private buffer so if you want to format several strings you
2129 must explicitly copy the earlier strings away (and free the copies when you
2130 are done).</p>
2131 </dd>
2132 <dd>
2133 <pre>
2134         char*   form(const char* pat, ...)</pre>
2135 </dd>
2136 </li>
2137 <dt><strong><a name="item_getcwd_sv_x_3cgetcwd_sv_3e">getcwd_sv
2138 </a></strong>
2139
2140 <dd>
2141 <p>Fill the sv with current working directory</p>
2142 </dd>
2143 <dd>
2144 <pre>
2145         int     getcwd_sv(SV* sv)</pre>
2146 </dd>
2147 </li>
2148 <dt><strong><a name="item_streq_x_3cstreq_3e">strEQ
2149 </a></strong>
2150
2151 <dd>
2152 <p>Test two strings to see if they are equal.  Returns true or false.</p>
2153 </dd>
2154 <dd>
2155 <pre>
2156         bool    strEQ(char* s1, char* s2)</pre>
2157 </dd>
2158 </li>
2159 <dt><strong><a name="item_strge_x_3cstrge_3e">strGE
2160 </a></strong>
2161
2162 <dd>
2163 <p>Test two strings to see if the first, <code>s1</code>, is greater than or equal to
2164 the second, <code>s2</code>.  Returns true or false.</p>
2165 </dd>
2166 <dd>
2167 <pre>
2168         bool    strGE(char* s1, char* s2)</pre>
2169 </dd>
2170 </li>
2171 <dt><strong><a name="item_strgt_x_3cstrgt_3e">strGT
2172 </a></strong>
2173
2174 <dd>
2175 <p>Test two strings to see if the first, <code>s1</code>, is greater than the second,
2176 <code>s2</code>.  Returns true or false.</p>
2177 </dd>
2178 <dd>
2179 <pre>
2180         bool    strGT(char* s1, char* s2)</pre>
2181 </dd>
2182 </li>
2183 <dt><strong><a name="item_strle_x_3cstrle_3e">strLE
2184 </a></strong>
2185
2186 <dd>
2187 <p>Test two strings to see if the first, <code>s1</code>, is less than or equal to the
2188 second, <code>s2</code>.  Returns true or false.</p>
2189 </dd>
2190 <dd>
2191 <pre>
2192         bool    strLE(char* s1, char* s2)</pre>
2193 </dd>
2194 </li>
2195 <dt><strong><a name="item_strlt_x_3cstrlt_3e">strLT
2196 </a></strong>
2197
2198 <dd>
2199 <p>Test two strings to see if the first, <code>s1</code>, is less than the second,
2200 <code>s2</code>.  Returns true or false.</p>
2201 </dd>
2202 <dd>
2203 <pre>
2204         bool    strLT(char* s1, char* s2)</pre>
2205 </dd>
2206 </li>
2207 <dt><strong><a name="item_strne_x_3cstrne_3e">strNE
2208 </a></strong>
2209
2210 <dd>
2211 <p>Test two strings to see if they are different.  Returns true or
2212 false.</p>
2213 </dd>
2214 <dd>
2215 <pre>
2216         bool    strNE(char* s1, char* s2)</pre>
2217 </dd>
2218 </li>
2219 <dt><strong><a name="item_strneq_x_3cstrneq_3e">strnEQ
2220 </a></strong>
2221
2222 <dd>
2223 <p>Test two strings to see if they are equal.  The <code>len</code> parameter indicates
2224 the number of bytes to compare.  Returns true or false. (A wrapper for
2225 <code>strncmp</code>).</p>
2226 </dd>
2227 <dd>
2228 <pre>
2229         bool    strnEQ(char* s1, char* s2, STRLEN len)</pre>
2230 </dd>
2231 </li>
2232 <dt><strong><a name="item_strnne_x_3cstrnne_3e">strnNE
2233 </a></strong>
2234
2235 <dd>
2236 <p>Test two strings to see if they are different.  The <code>len</code> parameter
2237 indicates the number of bytes to compare.  Returns true or false. (A
2238 wrapper for <code>strncmp</code>).</p>
2239 </dd>
2240 <dd>
2241 <pre>
2242         bool    strnNE(char* s1, char* s2, STRLEN len)</pre>
2243 </dd>
2244 </li>
2245 <dt><strong><a name="item_sv_nolocking_x_3csv_nolocking_3e">sv_nolocking
2246 </a></strong>
2247
2248 <dd>
2249 <p>Dummy routine which ``locks'' an SV when there is no locking module present.
2250 Exists to avoid test for a NULL function pointer and because it could potentially warn under
2251 some level of strict-ness.</p>
2252 </dd>
2253 <dd>
2254 <pre>
2255         void    sv_nolocking(SV *)</pre>
2256 </dd>
2257 </li>
2258 <dt><strong><a name="item_sv_nosharing_x_3csv_nosharing_3e">sv_nosharing
2259 </a></strong>
2260
2261 <dd>
2262 <p>Dummy routine which ``shares'' an SV when there is no sharing module present.
2263 Exists to avoid test for a NULL function pointer and because it could potentially warn under
2264 some level of strict-ness.</p>
2265 </dd>
2266 <dd>
2267 <pre>
2268         void    sv_nosharing(SV *)</pre>
2269 </dd>
2270 </li>
2271 <dt><strong><a name="item_sv_nounlocking_x_3csv_nounlocking_3e">sv_nounlocking
2272 </a></strong>
2273
2274 <dd>
2275 <p>Dummy routine which ``unlocks'' an SV when there is no locking module present.
2276 Exists to avoid test for a NULL function pointer and because it could potentially warn under
2277 some level of strict-ness.</p>
2278 </dd>
2279 <dd>
2280 <pre>
2281         void    sv_nounlocking(SV *)</pre>
2282 </dd>
2283 </li>
2284 </dl>
2285 <p>
2286 </p>
2287 <hr />
2288 <h1><a name="numeric_functions">Numeric functions</a></h1>
2289 <dl>
2290 <dt><strong><a name="item_grok_bin_x_3cgrok_bin_3e">grok_bin
2291 </a></strong>
2292
2293 <dd>
2294 <p>converts a string representing a binary number to numeric form.</p>
2295 </dd>
2296 <dd>
2297 <p>On entry <em>start</em> and <em>*len</em> give the string to scan, <em>*flags</em> gives
2298 conversion flags, and <em>result</em> should be NULL or a pointer to an NV.
2299 The scan stops at the end of the string, or the first invalid character.
2300 Unless <code>PERL_SCAN_SILENT_ILLDIGIT</code> is set in <em>*flags</em>, encountering an
2301 invalid character will also trigger a warning.
2302 On return <em>*len</em> is set to the length of the scanned string,
2303 and <em>*flags</em> gives output flags.</p>
2304 </dd>
2305 <dd>
2306 <p>If the value is &lt;= <code>UV_MAX</code> it is returned as a UV, the output flags are clear,
2307 and nothing is written to <em>*result</em>. If the value is &gt; UV_MAX <code>grok_bin</code>
2308 returns UV_MAX, sets <code>PERL_SCAN_GREATER_THAN_UV_MAX</code> in the output flags,
2309 and writes the value to <em>*result</em> (or the value is discarded if <em>result</em>
2310 is NULL).</p>
2311 </dd>
2312 <dd>
2313 <p>The binary number may optionally be prefixed with ``0b'' or ``b'' unless
2314 <code>PERL_SCAN_DISALLOW_PREFIX</code> is set in <em>*flags</em> on entry. If
2315 <code>PERL_SCAN_ALLOW_UNDERSCORES</code> is set in <em>*flags</em> then the binary
2316 number may use '_' characters to separate digits.</p>
2317 </dd>
2318 <dd>
2319 <pre>
2320         UV      grok_bin(char* start, STRLEN* len, I32* flags, NV *result)</pre>
2321 </dd>
2322 </li>
2323 <dt><strong><a name="item_grok_hex_x_3cgrok_hex_3e">grok_hex
2324 </a></strong>
2325
2326 <dd>
2327 <p>converts a string representing a hex number to numeric form.</p>
2328 </dd>
2329 <dd>
2330 <p>On entry <em>start</em> and <em>*len</em> give the string to scan, <em>*flags</em> gives
2331 conversion flags, and <em>result</em> should be NULL or a pointer to an NV.
2332 The scan stops at the end of the string, or the first invalid character.
2333 Unless <code>PERL_SCAN_SILENT_ILLDIGIT</code> is set in <em>*flags</em>, encountering an
2334 invalid character will also trigger a warning.
2335 On return <em>*len</em> is set to the length of the scanned string,
2336 and <em>*flags</em> gives output flags.</p>
2337 </dd>
2338 <dd>
2339 <p>If the value is &lt;= UV_MAX it is returned as a UV, the output flags are clear,
2340 and nothing is written to <em>*result</em>. If the value is &gt; UV_MAX <code>grok_hex</code>
2341 returns UV_MAX, sets <code>PERL_SCAN_GREATER_THAN_UV_MAX</code> in the output flags,
2342 and writes the value to <em>*result</em> (or the value is discarded if <em>result</em>
2343 is NULL).</p>
2344 </dd>
2345 <dd>
2346 <p>The hex number may optionally be prefixed with ``0x'' or ``x'' unless
2347 <code>PERL_SCAN_DISALLOW_PREFIX</code> is set in <em>*flags</em> on entry. If
2348 <code>PERL_SCAN_ALLOW_UNDERSCORES</code> is set in <em>*flags</em> then the hex
2349 number may use '_' characters to separate digits.</p>
2350 </dd>
2351 <dd>
2352 <pre>
2353         UV      grok_hex(char* start, STRLEN* len, I32* flags, NV *result)</pre>
2354 </dd>
2355 </li>
2356 <dt><strong><a name="item_grok_number_x_3cgrok_number_3e">grok_number
2357 </a></strong>
2358
2359 <dd>
2360 <p>Recognise (or not) a number.  The type of the number is returned
2361 (0 if unrecognised), otherwise it is a bit-ORed combination of
2362 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2363 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).</p>
2364 </dd>
2365 <dd>
2366 <p>If the value of the number can fit an in UV, it is returned in the *valuep
2367 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2368 will never be set unless *valuep is valid, but *valuep may have been assigned
2369 to during processing even though IS_NUMBER_IN_UV is not set on return.
2370 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2371 valuep is non-NULL, but no actual assignment (or SEGV) will occur.</p>
2372 </dd>
2373 <dd>
2374 <p>IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2375 seen (in which case *valuep gives the true value truncated to an integer), and
2376 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2377 absolute value).  IS_NUMBER_IN_UV is not set if e notation was used or the
2378 number is larger than a UV.</p>
2379 </dd>
2380 <dd>
2381 <pre>
2382         int     grok_number(const char *pv, STRLEN len, UV *valuep)</pre>
2383 </dd>
2384 </li>
2385 <dt><strong><a name="item_grok_numeric_radix_x_3cgrok_numeric_radix_3e">grok_numeric_radix
2386 </a></strong>
2387
2388 <dd>
2389 <p>Scan and skip for a numeric decimal separator (radix).</p>
2390 </dd>
2391 <dd>
2392 <pre>
2393         bool    grok_numeric_radix(const char **sp, const char *send)</pre>
2394 </dd>
2395 </li>
2396 <dt><strong><a name="item_grok_oct_x_3cgrok_oct_3e">grok_oct
2397 </a></strong>
2398
2399 <dd>
2400 <p>converts a string representing an octal number to numeric form.</p>
2401 </dd>
2402 <dd>
2403 <p>On entry <em>start</em> and <em>*len</em> give the string to scan, <em>*flags</em> gives
2404 conversion flags, and <em>result</em> should be NULL or a pointer to an NV.
2405 The scan stops at the end of the string, or the first invalid character.
2406 Unless <code>PERL_SCAN_SILENT_ILLDIGIT</code> is set in <em>*flags</em>, encountering an
2407 invalid character will also trigger a warning.
2408 On return <em>*len</em> is set to the length of the scanned string,
2409 and <em>*flags</em> gives output flags.</p>
2410 </dd>
2411 <dd>
2412 <p>If the value is &lt;= UV_MAX it is returned as a UV, the output flags are clear,
2413 and nothing is written to <em>*result</em>. If the value is &gt; UV_MAX <code>grok_oct</code>
2414 returns UV_MAX, sets <code>PERL_SCAN_GREATER_THAN_UV_MAX</code> in the output flags,
2415 and writes the value to <em>*result</em> (or the value is discarded if <em>result</em>
2416 is NULL).</p>
2417 </dd>
2418 <dd>
2419 <p>If <code>PERL_SCAN_ALLOW_UNDERSCORES</code> is set in <em>*flags</em> then the octal
2420 number may use '_' characters to separate digits.</p>
2421 </dd>
2422 <dd>
2423 <pre>
2424         UV      grok_oct(char* start, STRLEN* len_p, I32* flags, NV *result)</pre>
2425 </dd>
2426 </li>
2427 <dt><strong><a name="item_scan_bin_x_3cscan_bin_3e">scan_bin
2428 </a></strong>
2429
2430 <dd>
2431 <p>For backwards compatibility. Use <code>grok_bin</code> instead.</p>
2432 </dd>
2433 <dd>
2434 <pre>
2435         NV      scan_bin(char* start, STRLEN len, STRLEN* retlen)</pre>
2436 </dd>
2437 </li>
2438 <dt><strong><a name="item_scan_hex_x_3cscan_hex_3e">scan_hex
2439 </a></strong>
2440
2441 <dd>
2442 <p>For backwards compatibility. Use <code>grok_hex</code> instead.</p>
2443 </dd>
2444 <dd>
2445 <pre>
2446         NV      scan_hex(char* start, STRLEN len, STRLEN* retlen)</pre>
2447 </dd>
2448 </li>
2449 <dt><strong><a name="item_scan_oct_x_3cscan_oct_3e">scan_oct
2450 </a></strong>
2451
2452 <dd>
2453 <p>For backwards compatibility. Use <code>grok_oct</code> instead.</p>
2454 </dd>
2455 <dd>
2456 <pre>
2457         NV      scan_oct(char* start, STRLEN len, STRLEN* retlen)</pre>
2458 </dd>
2459 </li>
2460 </dl>
2461 <p>
2462 </p>
2463 <hr />
2464 <h1><a name="optree_manipulation_functions">Optree Manipulation Functions</a></h1>
2465 <dl>
2466 <dt><strong><a name="item_cv_const_sv_x_3ccv_const_sv_3e">cv_const_sv
2467 </a></strong>
2468
2469 <dd>
2470 <p>If <code>cv</code> is a constant sub eligible for inlining. returns the constant
2471 value returned by the sub.  Otherwise, returns NULL.</p>
2472 </dd>
2473 <dd>
2474 <p>Constant subs can be created with <code>newCONSTSUB</code> or as described in
2475 <a href="file://C|\msysgit\mingw\html/pod/perlsub.html#constant_functions">Constant Functions in the perlsub manpage</a>.</p>
2476 </dd>
2477 <dd>
2478 <pre>
2479         SV*     cv_const_sv(CV* cv)</pre>
2480 </dd>
2481 </li>
2482 <dt><strong><a name="item_newconstsub_x_3cnewconstsub_3e">newCONSTSUB
2483 </a></strong>
2484
2485 <dd>
2486 <p>Creates a constant sub equivalent to Perl <code>sub FOO () { 123 }</code> which is
2487 eligible for inlining at compile-time.</p>
2488 </dd>
2489 <dd>
2490 <pre>
2491         CV*     newCONSTSUB(HV* stash, char* name, SV* sv)</pre>
2492 </dd>
2493 </li>
2494 <dt><strong><a name="item_newxs_x_3cnewxs_3e">newXS
2495 </a></strong>
2496
2497 <dd>
2498 <p>Used by <code>xsubpp</code> to hook up XSUBs as Perl subs.</p>
2499 </dd>
2500 </li>
2501 </dl>
2502 <p>
2503 </p>
2504 <hr />
2505 <h1><a name="pad_data_structures">Pad Data Structures</a></h1>
2506 <dl>
2507 <dt><strong><a name="item_pad_sv_x_3cpad_sv_3e">pad_sv
2508 </a></strong>
2509
2510 <dd>
2511 <p>Get the value at offset po in the current pad.
2512 Use macro PAD_SV instead of calling this function directly.</p>
2513 </dd>
2514 <dd>
2515 <pre>
2516         SV*     pad_sv(PADOFFSET po)</pre>
2517 </dd>
2518 </li>
2519 </dl>
2520 <p>
2521 </p>
2522 <hr />
2523 <h1><a name="stack_manipulation_macros">Stack Manipulation Macros</a></h1>
2524 <dl>
2525 <dt><strong><a name="item_dmark_x_3cdmark_3e">dMARK
2526 </a></strong>
2527
2528 <dd>
2529 <p>Declare a stack marker variable, <code>mark</code>, for the XSUB.  See <code>MARK</code> and
2530 <code>dORIGMARK</code>.</p>
2531 </dd>
2532 <dd>
2533 <pre>
2534                 dMARK;</pre>
2535 </dd>
2536 </li>
2537 <dt><strong><a name="item_dorigmark_x_3cdorigmark_3e">dORIGMARK
2538 </a></strong>
2539
2540 <dd>
2541 <p>Saves the original stack mark for the XSUB.  See <code>ORIGMARK</code>.</p>
2542 </dd>
2543 <dd>
2544 <pre>
2545                 dORIGMARK;</pre>
2546 </dd>
2547 </li>
2548 <dt><strong><a name="item_dsp_x_3cdsp_3e">dSP
2549 </a></strong>
2550
2551 <dd>
2552 <p>Declares a local copy of perl's stack pointer for the XSUB, available via
2553 the <code>SP</code> macro.  See <code>SP</code>.</p>
2554 </dd>
2555 <dd>
2556 <pre>
2557                 dSP;</pre>
2558 </dd>
2559 </li>
2560 <dt><strong><a name="item_extend_x_3cextend_3e">EXTEND
2561 </a></strong>
2562
2563 <dd>
2564 <p>Used to extend the argument stack for an XSUB's return values. Once
2565 used, guarantees that there is room for at least <code>nitems</code> to be pushed
2566 onto the stack.</p>
2567 </dd>
2568 <dd>
2569 <pre>
2570         void    EXTEND(SP, int nitems)</pre>
2571 </dd>
2572 </li>
2573 <dt><strong><a name="item_mark_x_3cmark_3e">MARK
2574 </a></strong>
2575
2576 <dd>
2577 <p>Stack marker variable for the XSUB.  See <code>dMARK</code>.</p>
2578 </dd>
2579 </li>
2580 <dt><strong><a name="item_mpushi_x_3cmpushi_3e">mPUSHi
2581 </a></strong>
2582
2583 <dd>
2584 <p>Push an integer onto the stack.  The stack must have room for this element.
2585 Handles 'set' magic.  Does not use <code>TARG</code>.  See also <code>PUSHi</code>, <code>mXPUSHi</code>
2586 and <code>XPUSHi</code>.</p>
2587 </dd>
2588 <dd>
2589 <pre>
2590         void    mPUSHi(IV iv)</pre>
2591 </dd>
2592 </li>
2593 <dt><strong><a name="item_mpushn_x_3cmpushn_3e">mPUSHn
2594 </a></strong>
2595
2596 <dd>
2597 <p>Push a double onto the stack.  The stack must have room for this element.
2598 Handles 'set' magic.  Does not use <code>TARG</code>.  See also <code>PUSHn</code>, <code>mXPUSHn</code>
2599 and <code>XPUSHn</code>.</p>
2600 </dd>
2601 <dd>
2602 <pre>
2603         void    mPUSHn(NV nv)</pre>
2604 </dd>
2605 </li>
2606 <dt><strong><a name="item_mpushp_x_3cmpushp_3e">mPUSHp
2607 </a></strong>
2608
2609 <dd>
2610 <p>Push a string onto the stack.  The stack must have room for this element.
2611 The <code>len</code> indicates the length of the string.  Handles 'set' magic.  Does
2612 not use <code>TARG</code>.  See also <code>PUSHp</code>, <code>mXPUSHp</code> and <code>XPUSHp</code>.</p>
2613 </dd>
2614 <dd>
2615 <pre>
2616         void    mPUSHp(char* str, STRLEN len)</pre>
2617 </dd>
2618 </li>
2619 <dt><strong><a name="item_mpushu_x_3cmpushu_3e">mPUSHu
2620 </a></strong>
2621
2622 <dd>
2623 <p>Push an unsigned integer onto the stack.  The stack must have room for this
2624 element.  Handles 'set' magic.  Does not use <code>TARG</code>.  See also <code>PUSHu</code>,
2625 <code>mXPUSHu</code> and <code>XPUSHu</code>.</p>
2626 </dd>
2627 <dd>
2628 <pre>
2629         void    mPUSHu(UV uv)</pre>
2630 </dd>
2631 </li>
2632 <dt><strong><a name="item_mxpushi_x_3cmxpushi_3e">mXPUSHi
2633 </a></strong>
2634
2635 <dd>
2636 <p>Push an integer onto the stack, extending the stack if necessary.  Handles
2637 'set' magic.  Does not use <code>TARG</code>.  See also <code>XPUSHi</code>, <code>mPUSHi</code> and
2638 <code>PUSHi</code>.</p>
2639 </dd>
2640 <dd>
2641 <pre>
2642         void    mXPUSHi(IV iv)</pre>
2643 </dd>
2644 </li>
2645 <dt><strong><a name="item_mxpushn_x_3cmxpushn_3e">mXPUSHn
2646 </a></strong>
2647
2648 <dd>
2649 <p>Push a double onto the stack, extending the stack if necessary.  Handles
2650 'set' magic.  Does not use <code>TARG</code>.  See also <code>XPUSHn</code>, <code>mPUSHn</code> and
2651 <code>PUSHn</code>.</p>
2652 </dd>
2653 <dd>
2654 <pre>
2655         void    mXPUSHn(NV nv)</pre>
2656 </dd>
2657 </li>
2658 <dt><strong><a name="item_mxpushp_x_3cmxpushp_3e">mXPUSHp
2659 </a></strong>
2660
2661 <dd>
2662 <p>Push a string onto the stack, extending the stack if necessary.  The <code>len</code>
2663 indicates the length of the string.  Handles 'set' magic.  Does not use
2664 <code>TARG</code>.  See also <code>XPUSHp</code>, <code>mPUSHp</code> and <code>PUSHp</code>.</p>
2665 </dd>
2666 <dd>
2667 <pre>
2668         void    mXPUSHp(char* str, STRLEN len)</pre>
2669 </dd>
2670 </li>
2671 <dt><strong><a name="item_mxpushu_x_3cmxpushu_3e">mXPUSHu
2672 </a></strong>
2673
2674 <dd>
2675 <p>Push an unsigned integer onto the stack, extending the stack if necessary.
2676 Handles 'set' magic.  Does not use <code>TARG</code>.  See also <code>XPUSHu</code>, <code>mPUSHu</code>
2677 and <code>PUSHu</code>.</p>
2678 </dd>
2679 <dd>
2680 <pre>
2681         void    mXPUSHu(UV uv)</pre>
2682 </dd>
2683 </li>
2684 <dt><strong><a name="item_origmark_x_3corigmark_3e">ORIGMARK
2685 </a></strong>
2686
2687 <dd>
2688 <p>The original stack mark for the XSUB.  See <code>dORIGMARK</code>.</p>
2689 </dd>
2690 </li>
2691 <dt><strong><a name="item_popi_x_3cpopi_3e">POPi
2692 </a></strong>
2693
2694 <dd>
2695 <p>Pops an integer off the stack.</p>
2696 </dd>
2697 <dd>
2698 <pre>
2699         IV      POPi</pre>
2700 </dd>
2701 </li>
2702 <dt><strong><a name="item_popl_x_3cpopl_3e">POPl
2703 </a></strong>
2704
2705 <dd>
2706 <p>Pops a long off the stack.</p>
2707 </dd>
2708 <dd>
2709 <pre>
2710         long    POPl</pre>
2711 </dd>
2712 </li>
2713 <dt><strong><a name="item_popn_x_3cpopn_3e">POPn
2714 </a></strong>
2715
2716 <dd>
2717 <p>Pops a double off the stack.</p>
2718 </dd>
2719 <dd>
2720 <pre>
2721         NV      POPn</pre>
2722 </dd>
2723 </li>
2724 <dt><strong><a name="item_popp_x_3cpopp_3e">POPp
2725 </a></strong>
2726
2727 <dd>
2728 <p>Pops a string off the stack. Deprecated. New code should use POPpx.</p>
2729 </dd>
2730 <dd>
2731 <pre>
2732         char*   POPp</pre>
2733 </dd>
2734 </li>
2735 <dt><strong><a name="item_poppbytex_x_3cpoppbytex_3e">POPpbytex
2736 </a></strong>
2737
2738 <dd>
2739 <p>Pops a string off the stack which must consist of bytes i.e. characters &lt; 256.</p>
2740 </dd>
2741 <dd>
2742 <pre>
2743         char*   POPpbytex</pre>
2744 </dd>
2745 </li>
2746 <dt><strong><a name="item_poppx_x_3cpoppx_3e">POPpx
2747 </a></strong>
2748
2749 <dd>
2750 <p>Pops a string off the stack.</p>
2751 </dd>
2752 <dd>
2753 <pre>
2754         char*   POPpx</pre>
2755 </dd>
2756 </li>
2757 <dt><strong><a name="item_pops_x_3cpops_3e">POPs
2758 </a></strong>
2759
2760 <dd>
2761 <p>Pops an SV off the stack.</p>
2762 </dd>
2763 <dd>
2764 <pre>
2765         SV*     POPs</pre>
2766 </dd>
2767 </li>
2768 <dt><strong><a name="item_pushi_x_3cpushi_3e">PUSHi
2769 </a></strong>
2770
2771 <dd>
2772 <p>Push an integer onto the stack.  The stack must have room for this element.
2773 Handles 'set' magic.  Uses <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code> should be
2774 called to declare it.  Do not call multiple <code>TARG</code>-oriented macros to
2775 return lists from XSUB's - see <code>mPUSHi</code> instead.  See also <code>XPUSHi</code> and
2776 <code>mXPUSHi</code>.</p>
2777 </dd>
2778 <dd>
2779 <pre>
2780         void    PUSHi(IV iv)</pre>
2781 </dd>
2782 </li>
2783 <dt><strong><a name="item_pushmark_x_3cpushmark_3e">PUSHMARK
2784 </a></strong>
2785
2786 <dd>
2787 <p>Opening bracket for arguments on a callback.  See <code>PUTBACK</code> and
2788 <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
2789 </dd>
2790 <dd>
2791 <pre>
2792         void    PUSHMARK(SP)</pre>
2793 </dd>
2794 </li>
2795 <dt><strong><a name="item_pushmortal_x_3cpushmortal_3e">PUSHmortal
2796 </a></strong>
2797
2798 <dd>
2799 <p>Push a new mortal SV onto the stack.  The stack must have room for this
2800 element.  Does not handle 'set' magic.  Does not use <code>TARG</code>.  See also
2801 <code>PUSHs</code>, <code>XPUSHmortal</code> and <code>XPUSHs</code>.</p>
2802 </dd>
2803 <dd>
2804 <pre>
2805         void    PUSHmortal()</pre>
2806 </dd>
2807 </li>
2808 <dt><strong><a name="item_pushn_x_3cpushn_3e">PUSHn
2809 </a></strong>
2810
2811 <dd>
2812 <p>Push a double onto the stack.  The stack must have room for this element.
2813 Handles 'set' magic.  Uses <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code> should be
2814 called to declare it.  Do not call multiple <code>TARG</code>-oriented macros to
2815 return lists from XSUB's - see <code>mPUSHn</code> instead.  See also <code>XPUSHn</code> and
2816 <code>mXPUSHn</code>.</p>
2817 </dd>
2818 <dd>
2819 <pre>
2820         void    PUSHn(NV nv)</pre>
2821 </dd>
2822 </li>
2823 <dt><strong><a name="item_pushp_x_3cpushp_3e">PUSHp
2824 </a></strong>
2825
2826 <dd>
2827 <p>Push a string onto the stack.  The stack must have room for this element.
2828 The <code>len</code> indicates the length of the string.  Handles 'set' magic.  Uses
2829 <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code> should be called to declare it.  Do not
2830 call multiple <code>TARG</code>-oriented macros to return lists from XSUB's - see
2831 <code>mPUSHp</code> instead.  See also <code>XPUSHp</code> and <code>mXPUSHp</code>.</p>
2832 </dd>
2833 <dd>
2834 <pre>
2835         void    PUSHp(char* str, STRLEN len)</pre>
2836 </dd>
2837 </li>
2838 <dt><strong><a name="item_pushs_x_3cpushs_3e">PUSHs
2839 </a></strong>
2840
2841 <dd>
2842 <p>Push an SV onto the stack.  The stack must have room for this element.
2843 Does not handle 'set' magic.  Does not use <code>TARG</code>.  See also <code>PUSHmortal</code>,
2844 <code>XPUSHs</code> and <code>XPUSHmortal</code>.</p>
2845 </dd>
2846 <dd>
2847 <pre>
2848         void    PUSHs(SV* sv)</pre>
2849 </dd>
2850 </li>
2851 <dt><strong><a name="item_pushu_x_3cpushu_3e">PUSHu
2852 </a></strong>
2853
2854 <dd>
2855 <p>Push an unsigned integer onto the stack.  The stack must have room for this
2856 element.  Handles 'set' magic.  Uses <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code>
2857 should be called to declare it.  Do not call multiple <code>TARG</code>-oriented
2858 macros to return lists from XSUB's - see <code>mPUSHu</code> instead.  See also
2859 <code>XPUSHu</code> and <code>mXPUSHu</code>.</p>
2860 </dd>
2861 <dd>
2862 <pre>
2863         void    PUSHu(UV uv)</pre>
2864 </dd>
2865 </li>
2866 <dt><strong><a name="item_putback_x_3cputback_3e">PUTBACK
2867 </a></strong>
2868
2869 <dd>
2870 <p>Closing bracket for XSUB arguments.  This is usually handled by <code>xsubpp</code>.
2871 See <code>PUSHMARK</code> and <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a> for other uses.</p>
2872 </dd>
2873 <dd>
2874 <pre>
2875                 PUTBACK;</pre>
2876 </dd>
2877 </li>
2878 <dt><strong><a name="item_sp_x_3csp_3e">SP
2879 </a></strong>
2880
2881 <dd>
2882 <p>Stack pointer.  This is usually handled by <code>xsubpp</code>.  See <code>dSP</code> and
2883 <code>SPAGAIN</code>.</p>
2884 </dd>
2885 </li>
2886 <dt><strong><a name="item_spagain_x_3cspagain_3e">SPAGAIN
2887 </a></strong>
2888
2889 <dd>
2890 <p>Refetch the stack pointer.  Used after a callback.  See <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a>.</p>
2891 </dd>
2892 <dd>
2893 <pre>
2894                 SPAGAIN;</pre>
2895 </dd>
2896 </li>
2897 <dt><strong><a name="item_xpushi_x_3cxpushi_3e">XPUSHi
2898 </a></strong>
2899
2900 <dd>
2901 <p>Push an integer onto the stack, extending the stack if necessary.  Handles
2902 'set' magic.  Uses <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code> should be called to
2903 declare it.  Do not call multiple <code>TARG</code>-oriented macros to return lists
2904 from XSUB's - see <code>mXPUSHi</code> instead.  See also <code>PUSHi</code> and <code>mPUSHi</code>.</p>
2905 </dd>
2906 <dd>
2907 <pre>
2908         void    XPUSHi(IV iv)</pre>
2909 </dd>
2910 </li>
2911 <dt><strong><a name="item_xpushmortal_x_3cxpushmortal_3e">XPUSHmortal
2912 </a></strong>
2913
2914 <dd>
2915 <p>Push a new mortal SV onto the stack, extending the stack if necessary.  Does
2916 not handle 'set' magic.  Does not use <code>TARG</code>.  See also <code>XPUSHs</code>,
2917 <code>PUSHmortal</code> and <code>PUSHs</code>.</p>
2918 </dd>
2919 <dd>
2920 <pre>
2921         void    XPUSHmortal()</pre>
2922 </dd>
2923 </li>
2924 <dt><strong><a name="item_xpushn_x_3cxpushn_3e">XPUSHn
2925 </a></strong>
2926
2927 <dd>
2928 <p>Push a double onto the stack, extending the stack if necessary.  Handles
2929 'set' magic.  Uses <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code> should be called to
2930 declare it.  Do not call multiple <code>TARG</code>-oriented macros to return lists
2931 from XSUB's - see <code>mXPUSHn</code> instead.  See also <code>PUSHn</code> and <code>mPUSHn</code>.</p>
2932 </dd>
2933 <dd>
2934 <pre>
2935         void    XPUSHn(NV nv)</pre>
2936 </dd>
2937 </li>
2938 <dt><strong><a name="item_xpushp_x_3cxpushp_3e">XPUSHp
2939 </a></strong>
2940
2941 <dd>
2942 <p>Push a string onto the stack, extending the stack if necessary.  The <code>len</code>
2943 indicates the length of the string.  Handles 'set' magic.  Uses <code>TARG</code>, so
2944 <code>dTARGET</code> or <code>dXSTARG</code> should be called to declare it.  Do not call
2945 multiple <code>TARG</code>-oriented macros to return lists from XSUB's - see
2946 <code>mXPUSHp</code> instead.  See also <code>PUSHp</code> and <code>mPUSHp</code>.</p>
2947 </dd>
2948 <dd>
2949 <pre>
2950         void    XPUSHp(char* str, STRLEN len)</pre>
2951 </dd>
2952 </li>
2953 <dt><strong><a name="item_xpushs_x_3cxpushs_3e">XPUSHs
2954 </a></strong>
2955
2956 <dd>
2957 <p>Push an SV onto the stack, extending the stack if necessary.  Does not
2958 handle 'set' magic.  Does not use <code>TARG</code>.  See also <code>XPUSHmortal</code>,
2959 <code>PUSHs</code> and <code>PUSHmortal</code>.</p>
2960 </dd>
2961 <dd>
2962 <pre>
2963         void    XPUSHs(SV* sv)</pre>
2964 </dd>
2965 </li>
2966 <dt><strong><a name="item_xpushu_x_3cxpushu_3e">XPUSHu
2967 </a></strong>
2968
2969 <dd>
2970 <p>Push an unsigned integer onto the stack, extending the stack if necessary.
2971 Handles 'set' magic.  Uses <code>TARG</code>, so <code>dTARGET</code> or <code>dXSTARG</code> should be
2972 called to declare it.  Do not call multiple <code>TARG</code>-oriented macros to
2973 return lists from XSUB's - see <code>mXPUSHu</code> instead.  See also <code>PUSHu</code> and
2974 <code>mPUSHu</code>.</p>
2975 </dd>
2976 <dd>
2977 <pre>
2978         void    XPUSHu(UV uv)</pre>
2979 </dd>
2980 </li>
2981 <dt><strong><a name="item_xsreturn_x_3cxsreturn_3e">XSRETURN
2982 </a></strong>
2983
2984 <dd>
2985 <p>Return from XSUB, indicating number of items on the stack.  This is usually
2986 handled by <code>xsubpp</code>.</p>
2987 </dd>
2988 <dd>
2989 <pre>
2990         void    XSRETURN(int nitems)</pre>
2991 </dd>
2992 </li>
2993 <dt><strong><a name="item_xsreturn_empty_x_3cxsreturn_empty_3e">XSRETURN_EMPTY
2994 </a></strong>
2995
2996 <dd>
2997 <p>Return an empty list from an XSUB immediately.</p>
2998 </dd>
2999 <dd>
3000 <pre>
3001                 XSRETURN_EMPTY;</pre>
3002 </dd>
3003 </li>
3004 <dt><strong><a name="item_xsreturn_iv_x_3cxsreturn_iv_3e">XSRETURN_IV
3005 </a></strong>
3006
3007 <dd>
3008 <p>Return an integer from an XSUB immediately.  Uses <code>XST_mIV</code>.</p>
3009 </dd>
3010 <dd>
3011 <pre>
3012         void    XSRETURN_IV(IV iv)</pre>
3013 </dd>
3014 </li>
3015 <dt><strong><a name="item_xsreturn_no_x_3cxsreturn_no_3e">XSRETURN_NO
3016 </a></strong>
3017
3018 <dd>
3019 <p>Return <code>&amp;PL_sv_no</code> from an XSUB immediately.  Uses <code>XST_mNO</code>.</p>
3020 </dd>
3021 <dd>
3022 <pre>
3023                 XSRETURN_NO;</pre>
3024 </dd>
3025 </li>
3026 <dt><strong><a name="item_xsreturn_nv_x_3cxsreturn_nv_3e">XSRETURN_NV
3027 </a></strong>
3028
3029 <dd>
3030 <p>Return a double from an XSUB immediately.  Uses <code>XST_mNV</code>.</p>
3031 </dd>
3032 <dd>
3033 <pre>
3034         void    XSRETURN_NV(NV nv)</pre>
3035 </dd>
3036 </li>
3037 <dt><strong><a name="item_xsreturn_pv_x_3cxsreturn_pv_3e">XSRETURN_PV
3038 </a></strong>
3039
3040 <dd>
3041 <p>Return a copy of a string from an XSUB immediately.  Uses <code>XST_mPV</code>.</p>
3042 </dd>
3043 <dd>
3044 <pre>
3045         void    XSRETURN_PV(char* str)</pre>
3046 </dd>
3047 </li>
3048 <dt><strong><a name="item_xsreturn_undef_x_3cxsreturn_undef_3e">XSRETURN_UNDEF
3049 </a></strong>
3050
3051 <dd>
3052 <p>Return <code>&amp;PL_sv_undef</code> from an XSUB immediately.  Uses <code>XST_mUNDEF</code>.</p>
3053 </dd>
3054 <dd>
3055 <pre>
3056                 XSRETURN_UNDEF;</pre>
3057 </dd>
3058 </li>
3059 <dt><strong><a name="item_xsreturn_uv_x_3cxsreturn_uv_3e">XSRETURN_UV
3060 </a></strong>
3061
3062 <dd>
3063 <p>Return an integer from an XSUB immediately.  Uses <code>XST_mUV</code>.</p>
3064 </dd>
3065 <dd>
3066 <pre>
3067         void    XSRETURN_UV(IV uv)</pre>
3068 </dd>
3069 </li>
3070 <dt><strong><a name="item_xsreturn_yes_x_3cxsreturn_yes_3e">XSRETURN_YES
3071 </a></strong>
3072
3073 <dd>
3074 <p>Return <code>&amp;PL_sv_yes</code> from an XSUB immediately.  Uses <code>XST_mYES</code>.</p>
3075 </dd>
3076 <dd>
3077 <pre>
3078                 XSRETURN_YES;</pre>
3079 </dd>
3080 </li>
3081 <dt><strong><a name="item_xst_miv_x_3cxst_miv_3e">XST_mIV
3082 </a></strong>
3083
3084 <dd>
3085 <p>Place an integer into the specified position <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pos"><code>pos</code></a> on the stack.  The
3086 value is stored in a new mortal SV.</p>
3087 </dd>
3088 <dd>
3089 <pre>
3090         void    XST_mIV(int pos, IV iv)</pre>
3091 </dd>
3092 </li>
3093 <dt><strong><a name="item_xst_mno_x_3cxst_mno_3e">XST_mNO
3094 </a></strong>
3095
3096 <dd>
3097 <p>Place <code>&amp;PL_sv_no</code> into the specified position <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pos"><code>pos</code></a> on the
3098 stack.</p>
3099 </dd>
3100 <dd>
3101 <pre>
3102         void    XST_mNO(int pos)</pre>
3103 </dd>
3104 </li>
3105 <dt><strong><a name="item_xst_mnv_x_3cxst_mnv_3e">XST_mNV
3106 </a></strong>
3107
3108 <dd>
3109 <p>Place a double into the specified position <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pos"><code>pos</code></a> on the stack.  The value
3110 is stored in a new mortal SV.</p>
3111 </dd>
3112 <dd>
3113 <pre>
3114         void    XST_mNV(int pos, NV nv)</pre>
3115 </dd>
3116 </li>
3117 <dt><strong><a name="item_xst_mpv_x_3cxst_mpv_3e">XST_mPV
3118 </a></strong>
3119
3120 <dd>
3121 <p>Place a copy of a string into the specified position <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pos"><code>pos</code></a> on the stack.
3122 The value is stored in a new mortal SV.</p>
3123 </dd>
3124 <dd>
3125 <pre>
3126         void    XST_mPV(int pos, char* str)</pre>
3127 </dd>
3128 </li>
3129 <dt><strong><a name="item_xst_mundef_x_3cxst_mundef_3e">XST_mUNDEF
3130 </a></strong>
3131
3132 <dd>
3133 <p>Place <code>&amp;PL_sv_undef</code> into the specified position <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pos"><code>pos</code></a> on the
3134 stack.</p>
3135 </dd>
3136 <dd>
3137 <pre>
3138         void    XST_mUNDEF(int pos)</pre>
3139 </dd>
3140 </li>
3141 <dt><strong><a name="item_xst_myes_x_3cxst_myes_3e">XST_mYES
3142 </a></strong>
3143
3144 <dd>
3145 <p>Place <code>&amp;PL_sv_yes</code> into the specified position <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_pos"><code>pos</code></a> on the
3146 stack.</p>
3147 </dd>
3148 <dd>
3149 <pre>
3150         void    XST_mYES(int pos)</pre>
3151 </dd>
3152 </li>
3153 </dl>
3154 <p>
3155 </p>
3156 <hr />
3157 <h1><a name="sv_flags">SV Flags</a></h1>
3158 <dl>
3159 <dt><strong><a name="item_svtype_x_3csvtype_3e">svtype
3160 </a></strong>
3161
3162 <dd>
3163 <p>An enum of flags for Perl types.  These are found in the file <strong>sv.h</strong>
3164 in the <code>svtype</code> enum.  Test these flags with the <code>SvTYPE</code> macro.</p>
3165 </dd>
3166 </li>
3167 <dt><strong><a name="item_svt_iv_x_3csvt_iv_3e">SVt_IV
3168 </a></strong>
3169
3170 <dd>
3171 <p>Integer type flag for scalars.  See <code>svtype</code>.</p>
3172 </dd>
3173 </li>
3174 <dt><strong><a name="item_svt_nv_x_3csvt_nv_3e">SVt_NV
3175 </a></strong>
3176
3177 <dd>
3178 <p>Double type flag for scalars.  See <code>svtype</code>.</p>
3179 </dd>
3180 </li>
3181 <dt><strong><a name="item_svt_pv_x_3csvt_pv_3e">SVt_PV
3182 </a></strong>
3183
3184 <dd>
3185 <p>Pointer type flag for scalars.  See <code>svtype</code>.</p>
3186 </dd>
3187 </li>
3188 <dt><strong><a name="item_svt_pvav_x_3csvt_pvav_3e">SVt_PVAV
3189 </a></strong>
3190
3191 <dd>
3192 <p>Type flag for arrays.  See <code>svtype</code>.</p>
3193 </dd>
3194 </li>
3195 <dt><strong><a name="item_svt_pvcv_x_3csvt_pvcv_3e">SVt_PVCV
3196 </a></strong>
3197
3198 <dd>
3199 <p>Type flag for code refs.  See <code>svtype</code>.</p>
3200 </dd>
3201 </li>
3202 <dt><strong><a name="item_svt_pvhv_x_3csvt_pvhv_3e">SVt_PVHV
3203 </a></strong>
3204
3205 <dd>
3206 <p>Type flag for hashes.  See <code>svtype</code>.</p>
3207 </dd>
3208 </li>
3209 <dt><strong><a name="item_svt_pvmg_x_3csvt_pvmg_3e">SVt_PVMG
3210 </a></strong>
3211
3212 <dd>
3213 <p>Type flag for blessed scalars.  See <code>svtype</code>.</p>
3214 </dd>
3215 </li>
3216 </dl>
3217 <p>
3218 </p>
3219 <hr />
3220 <h1><a name="sv_manipulation_functions">SV Manipulation Functions</a></h1>
3221 <dl>
3222 <dt><strong><a name="item_get_sv_x_3cget_sv_3e">get_sv
3223 </a></strong>
3224
3225 <dd>
3226 <p>Returns the SV of the specified Perl scalar.  If <code>create</code> is set and the
3227 Perl variable does not exist then it will be created.  If <code>create</code> is not
3228 set and the variable does not exist then NULL is returned.</p>
3229 </dd>
3230 <dd>
3231 <p>NOTE: the perl_ form of this function is deprecated.</p>
3232 </dd>
3233 <dd>
3234 <pre>
3235         SV*     get_sv(const char* name, I32 create)</pre>
3236 </dd>
3237 </li>
3238 <dt><strong><a name="item_looks_like_number_x_3clooks_like_number_3e">looks_like_number
3239 </a></strong>
3240
3241 <dd>
3242 <p>Test if the content of an SV looks like a number (or is a number).
3243 <code>Inf</code> and <code>Infinity</code> are treated as numbers (so will not issue a
3244 non-numeric warning), even if your <code>atof()</code> doesn't grok them.</p>
3245 </dd>
3246 <dd>
3247 <pre>
3248         I32     looks_like_number(SV* sv)</pre>
3249 </dd>
3250 </li>
3251 <dt><strong><a name="item_newrv_inc_x_3cnewrv_inc_3e">newRV_inc
3252 </a></strong>
3253
3254 <dd>
3255 <p>Creates an RV wrapper for an SV.  The reference count for the original SV is
3256 incremented.</p>
3257 </dd>
3258 <dd>
3259 <pre>
3260         SV*     newRV_inc(SV* sv)</pre>
3261 </dd>
3262 </li>
3263 <dt><strong><a name="item_newrv_noinc_x_3cnewrv_noinc_3e">newRV_noinc
3264 </a></strong>
3265
3266 <dd>
3267 <p>Creates an RV wrapper for an SV.  The reference count for the original
3268 SV is <strong>not</strong> incremented.</p>
3269 </dd>
3270 <dd>
3271 <pre>
3272         SV*     newRV_noinc(SV *sv)</pre>
3273 </dd>
3274 </li>
3275 <dt><strong><a name="item_newsv_x_3cnewsv_3e">NEWSV
3276 </a></strong>
3277
3278 <dd>
3279 <p>Creates a new SV.  A non-zero <code>len</code> parameter indicates the number of
3280 bytes of preallocated string space the SV should have.  An extra byte for a
3281 tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
3282 space is allocated.)  The reference count for the new SV is set to 1.
3283 <code>id</code> is an integer id between 0 and 1299 (used to identify leaks).</p>
3284 </dd>
3285 <dd>
3286 <pre>
3287         SV*     NEWSV(int id, STRLEN len)</pre>
3288 </dd>
3289 </li>
3290 <dt><strong><a name="item_newsv_x_3cnewsv_3e">newSV
3291 </a></strong>
3292
3293 <dd>
3294 <p>Create a new null SV, or if len &gt; 0, create a new empty SVt_PV type SV
3295 with an initial PV allocation of len+1. Normally accessed via the <code>NEWSV</code>
3296 macro.</p>
3297 </dd>
3298 <dd>
3299 <pre>
3300         SV*     newSV(STRLEN len)</pre>
3301 </dd>
3302 </li>
3303 <dt><strong><a name="item_newsvhek_x_3cnewsvhek_3e">newSVhek
3304 </a></strong>
3305
3306 <dd>
3307 <p>Creates a new SV from the hash key structure.  It will generate scalars that
3308 point to the shared string table where possible. Returns a new (undefined)
3309 SV if the hek is NULL.</p>
3310 </dd>
3311 <dd>
3312 <pre>
3313         SV*     newSVhek(const HEK *hek)</pre>
3314 </dd>
3315 </li>
3316 <dt><strong><a name="item_newsviv_x_3cnewsviv_3e">newSViv
3317 </a></strong>
3318
3319 <dd>
3320 <p>Creates a new SV and copies an integer into it.  The reference count for the
3321 SV is set to 1.</p>
3322 </dd>
3323 <dd>
3324 <pre>
3325         SV*     newSViv(IV i)</pre>
3326 </dd>
3327 </li>
3328 <dt><strong><a name="item_newsvnv_x_3cnewsvnv_3e">newSVnv
3329 </a></strong>
3330
3331 <dd>
3332 <p>Creates a new SV and copies a floating point value into it.
3333 The reference count for the SV is set to 1.</p>
3334 </dd>
3335 <dd>
3336 <pre>
3337         SV*     newSVnv(NV n)</pre>
3338 </dd>
3339 </li>
3340 <dt><strong><a name="item_newsvpv_x_3cnewsvpv_3e">newSVpv
3341 </a></strong>
3342
3343 <dd>
3344 <p>Creates a new SV and copies a string into it.  The reference count for the
3345 SV is set to 1.  If <code>len</code> is zero, Perl will compute the length using
3346 strlen().  For efficiency, consider using <code>newSVpvn</code> instead.</p>
3347 </dd>
3348 <dd>
3349 <pre>
3350         SV*     newSVpv(const char* s, STRLEN len)</pre>
3351 </dd>
3352 </li>
3353 <dt><strong><a name="item_newsvpvf_x_3cnewsvpvf_3e">newSVpvf
3354 </a></strong>
3355
3356 <dd>
3357 <p>Creates a new SV and initializes it with the string formatted like
3358 <code>sprintf</code>.</p>
3359 </dd>
3360 <dd>
3361 <pre>
3362         SV*     newSVpvf(const char* pat, ...)</pre>
3363 </dd>
3364 </li>
3365 <dt><strong><a name="item_newsvpvn_x_3cnewsvpvn_3e">newSVpvn
3366 </a></strong>
3367
3368 <dd>
3369 <p>Creates a new SV and copies a string into it.  The reference count for the
3370 SV is set to 1.  Note that if <code>len</code> is zero, Perl will create a zero length
3371 string.  You are responsible for ensuring that the source string is at least
3372 <code>len</code> bytes long.  If the <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> argument is NULL the new SV will be undefined.</p>
3373 </dd>
3374 <dd>
3375 <pre>
3376         SV*     newSVpvn(const char* s, STRLEN len)</pre>
3377 </dd>
3378 </li>
3379 <dt><strong><a name="item_newsvpvn_share_x_3cnewsvpvn_share_3e">newSVpvn_share
3380 </a></strong>
3381
3382 <dd>
3383 <p>Creates a new SV with its SvPVX_const pointing to a shared string in the string
3384 table. If the string does not already exist in the table, it is created
3385 first.  Turns on READONLY and FAKE.  The string's hash is stored in the UV
3386 slot of the SV; if the <code>hash</code> parameter is non-zero, that value is used;
3387 otherwise the hash is computed.  The idea here is that as the string table
3388 is used for shared hash keys these strings will have SvPVX_const == HeKEY and
3389 hash lookup will avoid string compare.</p>
3390 </dd>
3391 <dd>
3392 <pre>
3393         SV*     newSVpvn_share(const char* s, I32 len, U32 hash)</pre>
3394 </dd>
3395 </li>
3396 <dt><strong><a name="item_newsvrv_x_3cnewsvrv_3e">newSVrv
3397 </a></strong>
3398
3399 <dd>
3400 <p>Creates a new SV for the RV, <code>rv</code>, to point to.  If <code>rv</code> is not an RV then
3401 it will be upgraded to one.  If <code>classname</code> is non-null then the new SV will
3402 be blessed in the specified package.  The new SV is returned and its
3403 reference count is 1.</p>
3404 </dd>
3405 <dd>
3406 <pre>
3407         SV*     newSVrv(SV* rv, const char* classname)</pre>
3408 </dd>
3409 </li>
3410 <dt><strong><a name="item_newsvsv_x_3cnewsvsv_3e">newSVsv
3411 </a></strong>
3412
3413 <dd>
3414 <p>Creates a new SV which is an exact duplicate of the original SV.
3415 (Uses <code>sv_setsv</code>).</p>
3416 </dd>
3417 <dd>
3418 <pre>
3419         SV*     newSVsv(SV* old)</pre>
3420 </dd>
3421 </li>
3422 <dt><strong><a name="item_newsvuv_x_3cnewsvuv_3e">newSVuv
3423 </a></strong>
3424
3425 <dd>
3426 <p>Creates a new SV and copies an unsigned integer into it.
3427 The reference count for the SV is set to 1.</p>
3428 </dd>
3429 <dd>
3430 <pre>
3431         SV*     newSVuv(UV u)</pre>
3432 </dd>
3433 </li>
3434 <dt><strong><a name="item_svcur_x_3csvcur_3e">SvCUR
3435 </a></strong>
3436
3437 <dd>
3438 <p>Returns the length of the string which is in the SV.  See <code>SvLEN</code>.</p>
3439 </dd>
3440 <dd>
3441 <pre>
3442         STRLEN  SvCUR(SV* sv)</pre>
3443 </dd>
3444 </li>
3445 <dt><strong><a name="item_svcur_set_x_3csvcur_set_3e">SvCUR_set
3446 </a></strong>
3447
3448 <dd>
3449 <p>Set the current length of the string which is in the SV.  See <code>SvCUR</code>
3450 and <code>SvIV_set</code>.</p>
3451 </dd>
3452 <dd>
3453 <pre>
3454         void    SvCUR_set(SV* sv, STRLEN len)</pre>
3455 </dd>
3456 </li>
3457 <dt><strong><a name="item_svend_x_3csvend_3e">SvEND
3458 </a></strong>
3459
3460 <dd>
3461 <p>Returns a pointer to the last character in the string which is in the SV.
3462 See <code>SvCUR</code>.  Access the character as *(SvEND(sv)).</p>
3463 </dd>
3464 <dd>
3465 <pre>
3466         char*   SvEND(SV* sv)</pre>
3467 </dd>
3468 </li>
3469 <dt><strong><a name="item_svgrow_x_3csvgrow_3e">SvGROW
3470 </a></strong>
3471
3472 <dd>
3473 <p>Expands the character buffer in the SV so that it has room for the
3474 indicated number of bytes (remember to reserve space for an extra trailing
3475 NUL character).  Calls <code>sv_grow</code> to perform the expansion if necessary.
3476 Returns a pointer to the character buffer.</p>
3477 </dd>
3478 <dd>
3479 <pre>
3480         char *  SvGROW(SV* sv, STRLEN len)</pre>
3481 </dd>
3482 </li>
3483 <dt><strong><a name="item_sviok_x_3csviok_3e">SvIOK
3484 </a></strong>
3485
3486 <dd>
3487 <p>Returns a boolean indicating whether the SV contains an integer.</p>
3488 </dd>
3489 <dd>
3490 <pre>
3491         bool    SvIOK(SV* sv)</pre>
3492 </dd>
3493 </li>
3494 <dt><strong><a name="item_sviokp_x_3csviokp_3e">SvIOKp
3495 </a></strong>
3496
3497 <dd>
3498 <p>Returns a boolean indicating whether the SV contains an integer.  Checks
3499 the <strong>private</strong> setting.  Use <code>SvIOK</code>.</p>
3500 </dd>
3501 <dd>
3502 <pre>
3503         bool    SvIOKp(SV* sv)</pre>
3504 </dd>
3505 </li>
3506 <dt><strong><a name="item_sviok_notuv_x_3csviok_notuv_3e">SvIOK_notUV
3507 </a></strong>
3508
3509 <dd>
3510 <p>Returns a boolean indicating whether the SV contains a signed integer.</p>
3511 </dd>
3512 <dd>
3513 <pre>
3514         bool    SvIOK_notUV(SV* sv)</pre>
3515 </dd>
3516 </li>
3517 <dt><strong><a name="item_sviok_off_x_3csviok_off_3e">SvIOK_off
3518 </a></strong>
3519
3520 <dd>
3521 <p>Unsets the IV status of an SV.</p>
3522 </dd>
3523 <dd>
3524 <pre>
3525         void    SvIOK_off(SV* sv)</pre>
3526 </dd>
3527 </li>
3528 <dt><strong><a name="item_sviok_on_x_3csviok_on_3e">SvIOK_on
3529 </a></strong>
3530
3531 <dd>
3532 <p>Tells an SV that it is an integer.</p>
3533 </dd>
3534 <dd>
3535 <pre>
3536         void    SvIOK_on(SV* sv)</pre>
3537 </dd>
3538 </li>
3539 <dt><strong><a name="item_sviok_only_x_3csviok_only_3e">SvIOK_only
3540 </a></strong>
3541
3542 <dd>
3543 <p>Tells an SV that it is an integer and disables all other OK bits.</p>
3544 </dd>
3545 <dd>
3546 <pre>
3547         void    SvIOK_only(SV* sv)</pre>
3548 </dd>
3549 </li>
3550 <dt><strong><a name="item_sviok_only_uv_x_3csviok_only_uv_3e">SvIOK_only_UV
3551 </a></strong>
3552
3553 <dd>
3554 <p>Tells and SV that it is an unsigned integer and disables all other OK bits.</p>
3555 </dd>
3556 <dd>
3557 <pre>
3558         void    SvIOK_only_UV(SV* sv)</pre>
3559 </dd>
3560 </li>
3561 <dt><strong><a name="item_sviok_uv_x_3csviok_uv_3e">SvIOK_UV
3562 </a></strong>
3563
3564 <dd>
3565 <p>Returns a boolean indicating whether the SV contains an unsigned integer.</p>
3566 </dd>
3567 <dd>
3568 <pre>
3569         bool    SvIOK_UV(SV* sv)</pre>
3570 </dd>
3571 </li>
3572 <dt><strong><a name="item_sviscow_x_3csviscow_3e">SvIsCOW
3573 </a></strong>
3574
3575 <dd>
3576 <p>Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
3577 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
3578 COW)</p>
3579 </dd>
3580 <dd>
3581 <pre>
3582         bool    SvIsCOW(SV* sv)</pre>
3583 </dd>
3584 </li>
3585 <dt><strong><a name="item_sviscow_shared_hash_x_3csviscow_shared_hash_3e">SvIsCOW_shared_hash
3586 </a></strong>
3587
3588 <dd>
3589 <p>Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
3590 scalar.</p>
3591 </dd>
3592 <dd>
3593 <pre>
3594         bool    SvIsCOW_shared_hash(SV* sv)</pre>
3595 </dd>
3596 </li>
3597 <dt><strong><a name="item_sviv_x_3csviv_3e">SvIV
3598 </a></strong>
3599
3600 <dd>
3601 <p>Coerces the given SV to an integer and returns it. See  <code>SvIVx</code> for a
3602 version which guarantees to evaluate sv only once.</p>
3603 </dd>
3604 <dd>
3605 <pre>
3606         IV      SvIV(SV* sv)</pre>
3607 </dd>
3608 </li>
3609 <dt><strong><a name="item_svivx_x_3csvivx_3e">SvIVX
3610 </a></strong>
3611
3612 <dd>
3613 <p>Returns the raw value in the SV's IV slot, without checks or conversions.
3614 Only use when you are sure SvIOK is true. See also <code>SvIV()</code>.</p>
3615 </dd>
3616 <dd>
3617 <pre>
3618         IV      SvIVX(SV* sv)</pre>
3619 </dd>
3620 </li>
3621 <dt><strong><a name="item_svivx_x_3csvivx_3e">SvIVx
3622 </a></strong>
3623
3624 <dd>
3625 <p>Coerces the given SV to an integer and returns it. Guarantees to evaluate
3626 sv only once. Use the more efficient <code>SvIV</code> otherwise.</p>
3627 </dd>
3628 <dd>
3629 <pre>
3630         IV      SvIVx(SV* sv)</pre>
3631 </dd>
3632 </li>
3633 <dt><strong><a name="item_sviv_set_x_3csviv_set_3e">SvIV_set
3634 </a></strong>
3635
3636 <dd>
3637 <p>Set the value of the IV pointer in sv to val.  It is possible to perform
3638 the same function of this macro with an lvalue assignment to <code>SvIVX</code>.
3639 With future Perls, however, it will be more efficient to use
3640 <code>SvIV_set</code> instead of the lvalue assignment to <code>SvIVX</code>.</p>
3641 </dd>
3642 <dd>
3643 <pre>
3644         void    SvIV_set(SV* sv, IV val)</pre>
3645 </dd>
3646 </li>
3647 <dt><strong><a name="item_svlen_x_3csvlen_3e">SvLEN
3648 </a></strong>
3649
3650 <dd>
3651 <p>Returns the size of the string buffer in the SV, not including any part
3652 attributable to <code>SvOOK</code>.  See <code>SvCUR</code>.</p>
3653 </dd>
3654 <dd>
3655 <pre>
3656         STRLEN  SvLEN(SV* sv)</pre>
3657 </dd>
3658 </li>
3659 <dt><strong><a name="item_svlen_set_x_3csvlen_set_3e">SvLEN_set
3660 </a></strong>
3661
3662 <dd>
3663 <p>Set the actual length of the string which is in the SV.  See <code>SvIV_set</code>.</p>
3664 </dd>
3665 <dd>
3666 <pre>
3667         void    SvLEN_set(SV* sv, STRLEN len)</pre>
3668 </dd>
3669 </li>
3670 <dt><strong><a name="item_svmagic_set_x_3csvmagic_set_3e">SvMAGIC_set
3671 </a></strong>
3672
3673 <dd>
3674 <p>Set the value of the MAGIC pointer in sv to val.  See <code>SvIV_set</code>.</p>
3675 </dd>
3676 <dd>
3677 <pre>
3678         void    SvMAGIC_set(SV* sv, MAGIC* val)</pre>
3679 </dd>
3680 </li>
3681 <dt><strong><a name="item_svniok_x_3csvniok_3e">SvNIOK
3682 </a></strong>
3683
3684 <dd>
3685 <p>Returns a boolean indicating whether the SV contains a number, integer or
3686 double.</p>
3687 </dd>
3688 <dd>
3689 <pre>
3690         bool    SvNIOK(SV* sv)</pre>
3691 </dd>
3692 </li>
3693 <dt><strong><a name="item_svniokp_x_3csvniokp_3e">SvNIOKp
3694 </a></strong>
3695
3696 <dd>
3697 <p>Returns a boolean indicating whether the SV contains a number, integer or
3698 double.  Checks the <strong>private</strong> setting.  Use <code>SvNIOK</code>.</p>
3699 </dd>
3700 <dd>
3701 <pre>
3702         bool    SvNIOKp(SV* sv)</pre>
3703 </dd>
3704 </li>
3705 <dt><strong><a name="item_svniok_off_x_3csvniok_off_3e">SvNIOK_off
3706 </a></strong>
3707
3708 <dd>
3709 <p>Unsets the NV/IV status of an SV.</p>
3710 </dd>
3711 <dd>
3712 <pre>
3713         void    SvNIOK_off(SV* sv)</pre>
3714 </dd>
3715 </li>
3716 <dt><strong><a name="item_svnok_x_3csvnok_3e">SvNOK
3717 </a></strong>
3718
3719 <dd>
3720 <p>Returns a boolean indicating whether the SV contains a double.</p>
3721 </dd>
3722 <dd>
3723 <pre>
3724         bool    SvNOK(SV* sv)</pre>
3725 </dd>
3726 </li>
3727 <dt><strong><a name="item_svnokp_x_3csvnokp_3e">SvNOKp
3728 </a></strong>
3729
3730 <dd>
3731 <p>Returns a boolean indicating whether the SV contains a double.  Checks the
3732 <strong>private</strong> setting.  Use <code>SvNOK</code>.</p>
3733 </dd>
3734 <dd>
3735 <pre>
3736         bool    SvNOKp(SV* sv)</pre>
3737 </dd>
3738 </li>
3739 <dt><strong><a name="item_svnok_off_x_3csvnok_off_3e">SvNOK_off
3740 </a></strong>
3741
3742 <dd>
3743 <p>Unsets the NV status of an SV.</p>
3744 </dd>
3745 <dd>
3746 <pre>
3747         void    SvNOK_off(SV* sv)</pre>
3748 </dd>
3749 </li>
3750 <dt><strong><a name="item_svnok_on_x_3csvnok_on_3e">SvNOK_on
3751 </a></strong>
3752
3753 <dd>
3754 <p>Tells an SV that it is a double.</p>
3755 </dd>
3756 <dd>
3757 <pre>
3758         void    SvNOK_on(SV* sv)</pre>
3759 </dd>
3760 </li>
3761 <dt><strong><a name="item_svnok_only_x_3csvnok_only_3e">SvNOK_only
3762 </a></strong>
3763
3764 <dd>
3765 <p>Tells an SV that it is a double and disables all other OK bits.</p>
3766 </dd>
3767 <dd>
3768 <pre>
3769         void    SvNOK_only(SV* sv)</pre>
3770 </dd>
3771 </li>
3772 <dt><strong><a name="item_svnv_x_3csvnv_3e">SvNV
3773 </a></strong>
3774
3775 <dd>
3776 <p>Coerce the given SV to a double and return it. See  <code>SvNVx</code> for a version
3777 which guarantees to evaluate sv only once.</p>
3778 </dd>
3779 <dd>
3780 <pre>
3781         NV      SvNV(SV* sv)</pre>
3782 </dd>
3783 </li>
3784 <dt><strong><a name="item_svnvx_x_3csvnvx_3e">SvNVX
3785 </a></strong>
3786
3787 <dd>
3788 <p>Returns the raw value in the SV's NV slot, without checks or conversions.
3789 Only use when you are sure SvNOK is true. See also <code>SvNV()</code>.</p>
3790 </dd>
3791 <dd>
3792 <pre>
3793         NV      SvNVX(SV* sv)</pre>
3794 </dd>
3795 </li>
3796 <dt><strong><a name="item_svnvx_x_3csvnvx_3e">SvNVx
3797 </a></strong>
3798
3799 <dd>
3800 <p>Coerces the given SV to a double and returns it. Guarantees to evaluate
3801 sv only once. Use the more efficient <code>SvNV</code> otherwise.</p>
3802 </dd>
3803 <dd>
3804 <pre>
3805         NV      SvNVx(SV* sv)</pre>
3806 </dd>
3807 </li>
3808 <dt><strong><a name="item_svnv_set_x_3csvnv_set_3e">SvNV_set
3809 </a></strong>
3810
3811 <dd>
3812 <p>Set the value of the NV pointer in sv to val.  See <code>SvIV_set</code>.</p>
3813 </dd>
3814 <dd>
3815 <pre>
3816         void    SvNV_set(SV* sv, NV val)</pre>
3817 </dd>
3818 </li>
3819 <dt><strong><a name="item_svok_x_3csvok_3e">SvOK
3820 </a></strong>
3821
3822 <dd>
3823 <p>Returns a boolean indicating whether the value is an SV. It also tells
3824 whether the value is defined or not.</p>
3825 </dd>
3826 <dd>
3827 <pre>
3828         bool    SvOK(SV* sv)</pre>
3829 </dd>
3830 </li>
3831 <dt><strong><a name="item_svook_x_3csvook_3e">SvOOK
3832 </a></strong>
3833
3834 <dd>
3835 <p>Returns a boolean indicating whether the SvIVX is a valid offset value for
3836 the SvPVX.  This hack is used internally to speed up removal of characters
3837 from the beginning of a SvPV.  When SvOOK is true, then the start of the
3838 allocated string buffer is really (SvPVX - SvIVX).</p>
3839 </dd>
3840 <dd>
3841 <pre>
3842         bool    SvOOK(SV* sv)</pre>
3843 </dd>
3844 </li>
3845 <dt><strong><a name="item_svpok_x_3csvpok_3e">SvPOK
3846 </a></strong>
3847
3848 <dd>
3849 <p>Returns a boolean indicating whether the SV contains a character
3850 string.</p>
3851 </dd>
3852 <dd>
3853 <pre>
3854         bool    SvPOK(SV* sv)</pre>
3855 </dd>
3856 </li>
3857 <dt><strong><a name="item_svpokp_x_3csvpokp_3e">SvPOKp
3858 </a></strong>
3859
3860 <dd>
3861 <p>Returns a boolean indicating whether the SV contains a character string.
3862 Checks the <strong>private</strong> setting.  Use <code>SvPOK</code>.</p>
3863 </dd>
3864 <dd>
3865 <pre>
3866         bool    SvPOKp(SV* sv)</pre>
3867 </dd>
3868 </li>
3869 <dt><strong><a name="item_svpok_off_x_3csvpok_off_3e">SvPOK_off
3870 </a></strong>
3871
3872 <dd>
3873 <p>Unsets the PV status of an SV.</p>
3874 </dd>
3875 <dd>
3876 <pre>
3877         void    SvPOK_off(SV* sv)</pre>
3878 </dd>
3879 </li>
3880 <dt><strong><a name="item_svpok_on_x_3csvpok_on_3e">SvPOK_on
3881 </a></strong>
3882
3883 <dd>
3884 <p>Tells an SV that it is a string.</p>
3885 </dd>
3886 <dd>
3887 <pre>
3888         void    SvPOK_on(SV* sv)</pre>
3889 </dd>
3890 </li>
3891 <dt><strong><a name="item_svpok_only_x_3csvpok_only_3e">SvPOK_only
3892 </a></strong>
3893
3894 <dd>
3895 <p>Tells an SV that it is a string and disables all other OK bits.
3896 Will also turn off the UTF-8 status.</p>
3897 </dd>
3898 <dd>
3899 <pre>
3900         void    SvPOK_only(SV* sv)</pre>
3901 </dd>
3902 </li>
3903 <dt><strong><a name="item_svpok_only_utf8_x_3csvpok_only_utf8_3e">SvPOK_only_UTF8
3904 </a></strong>
3905
3906 <dd>
3907 <p>Tells an SV that it is a string and disables all other OK bits,
3908 and leaves the UTF-8 status as it was.</p>
3909 </dd>
3910 <dd>
3911 <pre>
3912         void    SvPOK_only_UTF8(SV* sv)</pre>
3913 </dd>
3914 </li>
3915 <dt><strong><a name="item_svpv_x_3csvpv_3e">SvPV
3916 </a></strong>
3917
3918 <dd>
3919 <p>Returns a pointer to the string in the SV, or a stringified form of
3920 the SV if the SV does not contain a string.  The SV may cache the
3921 stringified version becoming <code>SvPOK</code>.  Handles 'get' magic. See also
3922 <code>SvPVx</code> for a version which guarantees to evaluate sv only once.</p>
3923 </dd>
3924 <dd>
3925 <pre>
3926         char*   SvPV(SV* sv, STRLEN len)</pre>
3927 </dd>
3928 </li>
3929 <dt><strong><a name="item_svpvbyte_x_3csvpvbyte_3e">SvPVbyte
3930 </a></strong>
3931
3932 <dd>
3933 <p>Like <code>SvPV</code>, but converts sv to byte representation first if necessary.</p>
3934 </dd>
3935 <dd>
3936 <pre>
3937         char*   SvPVbyte(SV* sv, STRLEN len)</pre>
3938 </dd>
3939 </li>
3940 <dt><strong><a name="item_svpvbytex_x_3csvpvbytex_3e">SvPVbytex
3941 </a></strong>
3942
3943 <dd>
3944 <p>Like <code>SvPV</code>, but converts sv to byte representation first if necessary.
3945 Guarantees to evaluate sv only once; use the more efficient <code>SvPVbyte</code>
3946 otherwise.</p>
3947 </dd>
3948 <dd>
3949 <pre>
3950         char*   SvPVbytex(SV* sv, STRLEN len)</pre>
3951 </dd>
3952 </li>
3953 <dt><strong><a name="item_svpvbytex_force_x_3csvpvbytex_force_3e">SvPVbytex_force
3954 </a></strong>
3955
3956 <dd>
3957 <p>Like <code>SvPV_force</code>, but converts sv to byte representation first if necessary.
3958 Guarantees to evaluate sv only once; use the more efficient <code>SvPVbyte_force</code>
3959 otherwise.</p>
3960 </dd>
3961 <dd>
3962 <pre>
3963         char*   SvPVbytex_force(SV* sv, STRLEN len)</pre>
3964 </dd>
3965 </li>
3966 <dt><strong><a name="item_svpvbyte_force_x_3csvpvbyte_force_3e">SvPVbyte_force
3967 </a></strong>
3968
3969 <dd>
3970 <p>Like <code>SvPV_force</code>, but converts sv to byte representation first if necessary.</p>
3971 </dd>
3972 <dd>
3973 <pre>
3974         char*   SvPVbyte_force(SV* sv, STRLEN len)</pre>
3975 </dd>
3976 </li>
3977 <dt><strong><a name="item_svpvbyte_nolen_x_3csvpvbyte_nolen_3e">SvPVbyte_nolen
3978 </a></strong>
3979
3980 <dd>
3981 <p>Like <code>SvPV_nolen</code>, but converts sv to byte representation first if necessary.</p>
3982 </dd>
3983 <dd>
3984 <pre>
3985         char*   SvPVbyte_nolen(SV* sv)</pre>
3986 </dd>
3987 </li>
3988 <dt><strong><a name="item_svpvutf8_x_3csvpvutf8_3e">SvPVutf8
3989 </a></strong>
3990
3991 <dd>
3992 <p>Like <code>SvPV</code>, but converts sv to utf8 first if necessary.</p>
3993 </dd>
3994 <dd>
3995 <pre>
3996         char*   SvPVutf8(SV* sv, STRLEN len)</pre>
3997 </dd>
3998 </li>
3999 <dt><strong><a name="item_svpvutf8x_x_3csvpvutf8x_3e">SvPVutf8x
4000 </a></strong>
4001
4002 <dd>
4003 <p>Like <code>SvPV</code>, but converts sv to utf8 first if necessary.
4004 Guarantees to evaluate sv only once; use the more efficient <code>SvPVutf8</code>
4005 otherwise.</p>
4006 </dd>
4007 <dd>
4008 <pre>
4009         char*   SvPVutf8x(SV* sv, STRLEN len)</pre>
4010 </dd>
4011 </li>
4012 <dt><strong><a name="item_svpvutf8x_force_x_3csvpvutf8x_force_3e">SvPVutf8x_force
4013 </a></strong>
4014
4015 <dd>
4016 <p>Like <code>SvPV_force</code>, but converts sv to utf8 first if necessary.
4017 Guarantees to evaluate sv only once; use the more efficient <code>SvPVutf8_force</code>
4018 otherwise.</p>
4019 </dd>
4020 <dd>
4021 <pre>
4022         char*   SvPVutf8x_force(SV* sv, STRLEN len)</pre>
4023 </dd>
4024 </li>
4025 <dt><strong><a name="item_svpvutf8_force_x_3csvpvutf8_force_3e">SvPVutf8_force
4026 </a></strong>
4027
4028 <dd>
4029 <p>Like <code>SvPV_force</code>, but converts sv to utf8 first if necessary.</p>
4030 </dd>
4031 <dd>
4032 <pre>
4033         char*   SvPVutf8_force(SV* sv, STRLEN len)</pre>
4034 </dd>
4035 </li>
4036 <dt><strong><a name="item_svpvutf8_nolen_x_3csvpvutf8_nolen_3e">SvPVutf8_nolen
4037 </a></strong>
4038
4039 <dd>
4040 <p>Like <code>SvPV_nolen</code>, but converts sv to utf8 first if necessary.</p>
4041 </dd>
4042 <dd>
4043 <pre>
4044         char*   SvPVutf8_nolen(SV* sv)</pre>
4045 </dd>
4046 </li>
4047 <dt><strong><a name="item_svpvx_x_3csvpvx_3e">SvPVX
4048 </a></strong>
4049
4050 <dd>
4051 <p>Returns a pointer to the physical string in the SV.  The SV must contain a
4052 string.</p>
4053 </dd>
4054 <dd>
4055 <pre>
4056         char*   SvPVX(SV* sv)</pre>
4057 </dd>
4058 </li>
4059 <dt><strong><a name="item_svpvx_x_3csvpvx_3e">SvPVx
4060 </a></strong>
4061
4062 <dd>
4063 <p>A version of <code>SvPV</code> which guarantees to evaluate sv only once.</p>
4064 </dd>
4065 <dd>
4066 <pre>
4067         char*   SvPVx(SV* sv, STRLEN len)</pre>
4068 </dd>
4069 </li>
4070 <dt><strong><a name="item_svpv_force_x_3csvpv_force_3e">SvPV_force
4071 </a></strong>
4072
4073 <dd>
4074 <p>Like <code>SvPV</code> but will force the SV into containing just a string
4075 (<code>SvPOK_only</code>).  You want force if you are going to update the <code>SvPVX</code>
4076 directly.</p>
4077 </dd>
4078 <dd>
4079 <pre>
4080         char*   SvPV_force(SV* sv, STRLEN len)</pre>
4081 </dd>
4082 </li>
4083 <dt><strong><a name="item_svpv_force_nomg_x_3csvpv_force_nomg_3e">SvPV_force_nomg
4084 </a></strong>
4085
4086 <dd>
4087 <p>Like <code>SvPV</code> but will force the SV into containing just a string
4088 (<code>SvPOK_only</code>).  You want force if you are going to update the <code>SvPVX</code>
4089 directly. Doesn't process magic.</p>
4090 </dd>
4091 <dd>
4092 <pre>
4093         char*   SvPV_force_nomg(SV* sv, STRLEN len)</pre>
4094 </dd>
4095 </li>
4096 <dt><strong><a name="item_svpv_nolen_x_3csvpv_nolen_3e">SvPV_nolen
4097 </a></strong>
4098
4099 <dd>
4100 <p>Returns a pointer to the string in the SV, or a stringified form of
4101 the SV if the SV does not contain a string.  The SV may cache the
4102 stringified form becoming <code>SvPOK</code>.  Handles 'get' magic.</p>
4103 </dd>
4104 <dd>
4105 <pre>
4106         char*   SvPV_nolen(SV* sv)</pre>
4107 </dd>
4108 </li>
4109 <dt><strong><a name="item_svpv_set_x_3csvpv_set_3e">SvPV_set
4110 </a></strong>
4111
4112 <dd>
4113 <p>Set the value of the PV pointer in sv to val.  See <code>SvIV_set</code>.</p>
4114 </dd>
4115 <dd>
4116 <pre>
4117         void    SvPV_set(SV* sv, char* val)</pre>
4118 </dd>
4119 </li>
4120 <dt><strong><a name="item_svrefcnt_x_3csvrefcnt_3e">SvREFCNT
4121 </a></strong>
4122
4123 <dd>
4124 <p>Returns the value of the object's reference count.</p>
4125 </dd>
4126 <dd>
4127 <pre>
4128         U32     SvREFCNT(SV* sv)</pre>
4129 </dd>
4130 </li>
4131 <dt><strong><a name="item_svrefcnt_dec_x_3csvrefcnt_dec_3e">SvREFCNT_dec
4132 </a></strong>
4133
4134 <dd>
4135 <p>Decrements the reference count of the given SV.</p>
4136 </dd>
4137 <dd>
4138 <pre>
4139         void    SvREFCNT_dec(SV* sv)</pre>
4140 </dd>
4141 </li>
4142 <dt><strong><a name="item_svrefcnt_inc_x_3csvrefcnt_inc_3e">SvREFCNT_inc
4143 </a></strong>
4144
4145 <dd>
4146 <p>Increments the reference count of the given SV.</p>
4147 </dd>
4148 <dd>
4149 <pre>
4150         SV*     SvREFCNT_inc(SV* sv)</pre>
4151 </dd>
4152 </li>
4153 <dt><strong><a name="item_svrok_x_3csvrok_3e">SvROK
4154 </a></strong>
4155
4156 <dd>
4157 <p>Tests if the SV is an RV.</p>
4158 </dd>
4159 <dd>
4160 <pre>
4161         bool    SvROK(SV* sv)</pre>
4162 </dd>
4163 </li>
4164 <dt><strong><a name="item_svrok_off_x_3csvrok_off_3e">SvROK_off
4165 </a></strong>
4166
4167 <dd>
4168 <p>Unsets the RV status of an SV.</p>
4169 </dd>
4170 <dd>
4171 <pre>
4172         void    SvROK_off(SV* sv)</pre>
4173 </dd>
4174 </li>
4175 <dt><strong><a name="item_svrok_on_x_3csvrok_on_3e">SvROK_on
4176 </a></strong>
4177
4178 <dd>
4179 <p>Tells an SV that it is an RV.</p>
4180 </dd>
4181 <dd>
4182 <pre>
4183         void    SvROK_on(SV* sv)</pre>
4184 </dd>
4185 </li>
4186 <dt><strong><a name="item_svrv_x_3csvrv_3e">SvRV
4187 </a></strong>
4188
4189 <dd>
4190 <p>Dereferences an RV to return the SV.</p>
4191 </dd>
4192 <dd>
4193 <pre>
4194         SV*     SvRV(SV* sv)</pre>
4195 </dd>
4196 </li>
4197 <dt><strong><a name="item_svrv_set_x_3csvrv_set_3e">SvRV_set
4198 </a></strong>
4199
4200 <dd>
4201 <p>Set the value of the RV pointer in sv to val.  See <code>SvIV_set</code>.</p>
4202 </dd>
4203 <dd>
4204 <pre>
4205         void    SvRV_set(SV* sv, SV* val)</pre>
4206 </dd>
4207 </li>
4208 <dt><strong><a name="item_svstash_x_3csvstash_3e">SvSTASH
4209 </a></strong>
4210
4211 <dd>
4212 <p>Returns the stash of the SV.</p>
4213 </dd>
4214 <dd>
4215 <pre>
4216         HV*     SvSTASH(SV* sv)</pre>
4217 </dd>
4218 </li>
4219 <dt><strong><a name="item_svstash_set_x_3csvstash_set_3e">SvSTASH_set
4220 </a></strong>
4221
4222 <dd>
4223 <p>Set the value of the STASH pointer in sv to val.  See <code>SvIV_set</code>.</p>
4224 </dd>
4225 <dd>
4226 <pre>
4227         void    SvSTASH_set(SV* sv, STASH* val)</pre>
4228 </dd>
4229 </li>
4230 <dt><strong><a name="item_svtaint_x_3csvtaint_3e">SvTAINT
4231 </a></strong>
4232
4233 <dd>
4234 <p>Taints an SV if tainting is enabled.</p>
4235 </dd>
4236 <dd>
4237 <pre>
4238         void    SvTAINT(SV* sv)</pre>
4239 </dd>
4240 </li>
4241 <dt><strong><a name="item_svtainted_x_3csvtainted_3e">SvTAINTED
4242 </a></strong>
4243
4244 <dd>
4245 <p>Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4246 not.</p>
4247 </dd>
4248 <dd>
4249 <pre>
4250         bool    SvTAINTED(SV* sv)</pre>
4251 </dd>
4252 </li>
4253 <dt><strong><a name="item_svtainted_off_x_3csvtainted_off_3e">SvTAINTED_off
4254 </a></strong>
4255
4256 <dd>
4257 <p>Untaints an SV. Be <em>very</em> careful with this routine, as it short-circuits
4258 some of Perl's fundamental security features. XS module authors should not
4259 use this function unless they fully understand all the implications of
4260 unconditionally untainting the value. Untainting should be done in the
4261 standard perl fashion, via a carefully crafted regexp, rather than directly
4262 untainting variables.</p>
4263 </dd>
4264 <dd>
4265 <pre>
4266         void    SvTAINTED_off(SV* sv)</pre>
4267 </dd>
4268 </li>
4269 <dt><strong><a name="item_svtainted_on_x_3csvtainted_on_3e">SvTAINTED_on
4270 </a></strong>
4271
4272 <dd>
4273 <p>Marks an SV as tainted if tainting is enabled.</p>
4274 </dd>
4275 <dd>
4276 <pre>
4277         void    SvTAINTED_on(SV* sv)</pre>
4278 </dd>
4279 </li>
4280 <dt><strong><a name="item_svtrue_x_3csvtrue_3e">SvTRUE
4281 </a></strong>
4282
4283 <dd>
4284 <p>Returns a boolean indicating whether Perl would evaluate the SV as true or
4285 false, defined or undefined.  Does not handle 'get' magic.</p>
4286 </dd>
4287 <dd>
4288 <pre>
4289         bool    SvTRUE(SV* sv)</pre>
4290 </dd>
4291 </li>
4292 <dt><strong><a name="item_svtype_x_3csvtype_3e">SvTYPE
4293 </a></strong>
4294
4295 <dd>
4296 <p>Returns the type of the SV.  See <code>svtype</code>.</p>
4297 </dd>
4298 <dd>
4299 <pre>
4300         svtype  SvTYPE(SV* sv)</pre>
4301 </dd>
4302 </li>
4303 <dt><strong><a name="item_svuok_x_3csvuok_3e">SvUOK
4304 </a></strong>
4305
4306 <dd>
4307 <p>Returns a boolean indicating whether the SV contains an unsigned integer.</p>
4308 </dd>
4309 <dd>
4310 <pre>
4311         void    SvUOK(SV* sv)</pre>
4312 </dd>
4313 </li>
4314 <dt><strong><a name="item_svupgrade_x_3csvupgrade_3e">SvUPGRADE
4315 </a></strong>
4316
4317 <dd>
4318 <p>Used to upgrade an SV to a more complex form.  Uses <code>sv_upgrade</code> to
4319 perform the upgrade if necessary.  See <code>svtype</code>.</p>
4320 </dd>
4321 <dd>
4322 <pre>
4323         void    SvUPGRADE(SV* sv, svtype type)</pre>
4324 </dd>
4325 </li>
4326 <dt><strong><a name="item_svutf8_x_3csvutf8_3e">SvUTF8
4327 </a></strong>
4328
4329 <dd>
4330 <p>Returns a boolean indicating whether the SV contains UTF-8 encoded data.</p>
4331 </dd>
4332 <dd>
4333 <pre>
4334         bool    SvUTF8(SV* sv)</pre>
4335 </dd>
4336 </li>
4337 <dt><strong><a name="item_svutf8_off_x_3csvutf8_off_3e">SvUTF8_off
4338 </a></strong>
4339
4340 <dd>
4341 <p>Unsets the UTF-8 status of an SV.</p>
4342 </dd>
4343 <dd>
4344 <pre>
4345         void    SvUTF8_off(SV *sv)</pre>
4346 </dd>
4347 </li>
4348 <dt><strong><a name="item_svutf8_on_x_3csvutf8_on_3e">SvUTF8_on
4349 </a></strong>
4350
4351 <dd>
4352 <p>Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
4353 Do not use frivolously.</p>
4354 </dd>
4355 <dd>
4356 <pre>
4357         void    SvUTF8_on(SV *sv)</pre>
4358 </dd>
4359 </li>
4360 <dt><strong><a name="item_svuv_x_3csvuv_3e">SvUV
4361 </a></strong>
4362
4363 <dd>
4364 <p>Coerces the given SV to an unsigned integer and returns it.  See <code>SvUVx</code>
4365 for a version which guarantees to evaluate sv only once.</p>
4366 </dd>
4367 <dd>
4368 <pre>
4369         UV      SvUV(SV* sv)</pre>
4370 </dd>
4371 </li>
4372 <dt><strong><a name="item_svuvx_x_3csvuvx_3e">SvUVX
4373 </a></strong>
4374
4375 <dd>
4376 <p>Returns the raw value in the SV's UV slot, without checks or conversions.
4377 Only use when you are sure SvIOK is true. See also <code>SvUV()</code>.</p>
4378 </dd>
4379 <dd>
4380 <pre>
4381         UV      SvUVX(SV* sv)</pre>
4382 </dd>
4383 </li>
4384 <dt><strong><a name="item_svuvx_x_3csvuvx_3e">SvUVx
4385 </a></strong>
4386
4387 <dd>
4388 <p>Coerces the given SV to an unsigned integer and returns it. Guarantees to
4389 evaluate sv only once. Use the more efficient <code>SvUV</code> otherwise.</p>
4390 </dd>
4391 <dd>
4392 <pre>
4393         UV      SvUVx(SV* sv)</pre>
4394 </dd>
4395 </li>
4396 <dt><strong><a name="item_svuv_set_x_3csvuv_set_3e">SvUV_set
4397 </a></strong>
4398
4399 <dd>
4400 <p>Set the value of the UV pointer in sv to val.  See <code>SvIV_set</code>.</p>
4401 </dd>
4402 <dd>
4403 <pre>
4404         void    SvUV_set(SV* sv, UV val)</pre>
4405 </dd>
4406 </li>
4407 <dt><strong><a name="item_sv_2bool_x_3csv_2bool_3e">sv_2bool
4408 </a></strong>
4409
4410 <dd>
4411 <p>This function is only called on magical items, and is only used by
4412 <code>sv_true()</code> or its macro equivalent.</p>
4413 </dd>
4414 <dd>
4415 <pre>
4416         bool    sv_2bool(SV* sv)</pre>
4417 </dd>
4418 </li>
4419 <dt><strong><a name="item_sv_2cv_x_3csv_2cv_3e">sv_2cv
4420 </a></strong>
4421
4422 <dd>
4423 <p>Using various gambits, try to get a CV from an SV; in addition, try if
4424 possible to set <code>*st</code> and <code>*gvp</code> to the stash and GV associated with it.</p>
4425 </dd>
4426 <dd>
4427 <pre>
4428         CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)</pre>
4429 </dd>
4430 </li>
4431 <dt><strong><a name="item_sv_2io_x_3csv_2io_3e">sv_2io
4432 </a></strong>
4433
4434 <dd>
4435 <p>Using various gambits, try to get an IO from an SV: the IO slot if its a
4436 GV; or the recursive result if we're an RV; or the IO slot of the symbol
4437 named after the PV if we're a string.</p>
4438 </dd>
4439 <dd>
4440 <pre>
4441         IO*     sv_2io(SV* sv)</pre>
4442 </dd>
4443 </li>
4444 <dt><strong><a name="item_sv_2iv_x_3csv_2iv_3e">sv_2iv
4445 </a></strong>
4446
4447 <dd>
4448 <p>Return the integer value of an SV, doing any necessary string conversion,
4449 magic etc. Normally used via the <code>SvIV(sv)</code> and <code>SvIVx(sv)</code> macros.</p>
4450 </dd>
4451 <dd>
4452 <pre>
4453         IV      sv_2iv(SV* sv)</pre>
4454 </dd>
4455 </li>
4456 <dt><strong><a name="item_sv_2mortal_x_3csv_2mortal_3e">sv_2mortal
4457 </a></strong>
4458
4459 <dd>
4460 <p>Marks an existing SV as mortal.  The SV will be destroyed ``soon'', either
4461 by an explicit call to FREETMPS, or by an implicit call at places such as
4462 statement boundaries.  <code>SvTEMP()</code> is turned on which means that the SV's
4463 string buffer can be ``stolen'' if this SV is copied. See also <code>sv_newmortal</code>
4464 and <code>sv_mortalcopy</code>.</p>
4465 </dd>
4466 <dd>
4467 <pre>
4468         SV*     sv_2mortal(SV* sv)</pre>
4469 </dd>
4470 </li>
4471 <dt><strong><a name="item_sv_2nv_x_3csv_2nv_3e">sv_2nv
4472 </a></strong>
4473
4474 <dd>
4475 <p>Return the num value of an SV, doing any necessary string or integer
4476 conversion, magic etc. Normally used via the <code>SvNV(sv)</code> and <code>SvNVx(sv)</code>
4477 macros.</p>
4478 </dd>
4479 <dd>
4480 <pre>
4481         NV      sv_2nv(SV* sv)</pre>
4482 </dd>
4483 </li>
4484 <dt><strong><a name="item_sv_2pvbyte_x_3csv_2pvbyte_3e">sv_2pvbyte
4485 </a></strong>
4486
4487 <dd>
4488 <p>Return a pointer to the byte-encoded representation of the SV, and set *lp
4489 to its length.  May cause the SV to be downgraded from UTF-8 as a
4490 side-effect.</p>
4491 </dd>
4492 <dd>
4493 <p>Usually accessed via the <code>SvPVbyte</code> macro.</p>
4494 </dd>
4495 <dd>
4496 <pre>
4497         char*   sv_2pvbyte(SV* sv, STRLEN* lp)</pre>
4498 </dd>
4499 </li>
4500 <dt><strong><a name="item_sv_2pvbyte_nolen_x_3csv_2pvbyte_nolen_3e">sv_2pvbyte_nolen
4501 </a></strong>
4502
4503 <dd>
4504 <p>Return a pointer to the byte-encoded representation of the SV.
4505 May cause the SV to be downgraded from UTF-8 as a side-effect.</p>
4506 </dd>
4507 <dd>
4508 <p>Usually accessed via the <code>SvPVbyte_nolen</code> macro.</p>
4509 </dd>
4510 <dd>
4511 <pre>
4512         char*   sv_2pvbyte_nolen(SV* sv)</pre>
4513 </dd>
4514 </li>
4515 <dt><strong><a name="item_sv_2pvutf8_x_3csv_2pvutf8_3e">sv_2pvutf8
4516 </a></strong>
4517
4518 <dd>
4519 <p>Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
4520 to its length.  May cause the SV to be upgraded to UTF-8 as a side-effect.</p>
4521 </dd>
4522 <dd>
4523 <p>Usually accessed via the <code>SvPVutf8</code> macro.</p>
4524 </dd>
4525 <dd>
4526 <pre>
4527         char*   sv_2pvutf8(SV* sv, STRLEN* lp)</pre>
4528 </dd>
4529 </li>
4530 <dt><strong><a name="item_sv_2pvutf8_nolen_x_3csv_2pvutf8_nolen_3e">sv_2pvutf8_nolen
4531 </a></strong>
4532
4533 <dd>
4534 <p>Return a pointer to the UTF-8-encoded representation of the SV.
4535 May cause the SV to be upgraded to UTF-8 as a side-effect.</p>
4536 </dd>
4537 <dd>
4538 <p>Usually accessed via the <code>SvPVutf8_nolen</code> macro.</p>
4539 </dd>
4540 <dd>
4541 <pre>
4542         char*   sv_2pvutf8_nolen(SV* sv)</pre>
4543 </dd>
4544 </li>
4545 <dt><strong><a name="item_sv_2pv_flags_x_3csv_2pv_flags_3e">sv_2pv_flags
4546 </a></strong>
4547
4548 <dd>
4549 <p>Returns a pointer to the string value of an SV, and sets *lp to its length.
4550 If flags includes SV_GMAGIC, does an <code>mg_get()</code> first. Coerces sv to a string
4551 if necessary.
4552 Normally invoked via the <code>SvPV_flags</code> macro. <code>sv_2pv()</code> and <code>sv_2pv_nomg</code>
4553 usually end up here too.</p>
4554 </dd>
4555 <dd>
4556 <pre>
4557         char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)</pre>
4558 </dd>
4559 </li>
4560 <dt><strong><a name="item_sv_2pv_nolen_x_3csv_2pv_nolen_3e">sv_2pv_nolen
4561 </a></strong>
4562
4563 <dd>
4564 <p>Like <code>sv_2pv()</code>, but doesn't return the length too. You should usually
4565 use the macro wrapper <code>SvPV_nolen(sv)</code> instead.
4566         char*   sv_2pv_nolen(SV* sv)</p>
4567 </dd>
4568 </li>
4569 <dt><strong><a name="item_sv_2uv_x_3csv_2uv_3e">sv_2uv
4570 </a></strong>
4571
4572 <dd>
4573 <p>Return the unsigned integer value of an SV, doing any necessary string
4574 conversion, magic etc. Normally used via the <code>SvUV(sv)</code> and <code>SvUVx(sv)</code>
4575 macros.</p>
4576 </dd>
4577 <dd>
4578 <pre>
4579         UV      sv_2uv(SV* sv)</pre>
4580 </dd>
4581 </li>
4582 <dt><strong><a name="item_sv_backoff_x_3csv_backoff_3e">sv_backoff
4583 </a></strong>
4584
4585 <dd>
4586 <p>Remove any string offset. You should normally use the <code>SvOOK_off</code> macro
4587 wrapper instead.</p>
4588 </dd>
4589 <dd>
4590 <pre>
4591         int     sv_backoff(SV* sv)</pre>
4592 </dd>
4593 </li>
4594 <dt><strong><a name="item_sv_bless_x_3csv_bless_3e">sv_bless
4595 </a></strong>
4596
4597 <dd>
4598 <p>Blesses an SV into a specified package.  The SV must be an RV.  The package
4599 must be designated by its stash (see <code>gv_stashpv()</code>).  The reference count
4600 of the SV is unaffected.</p>
4601 </dd>
4602 <dd>
4603 <pre>
4604         SV*     sv_bless(SV* sv, HV* stash)</pre>
4605 </dd>
4606 </li>
4607 <dt><strong><a name="item_sv_catpv_x_3csv_catpv_3e">sv_catpv
4608 </a></strong>
4609
4610 <dd>
4611 <p>Concatenates the string onto the end of the string which is in the SV.
4612 If the SV has the UTF-8 status set, then the bytes appended should be
4613 valid UTF-8.  Handles 'get' magic, but not 'set' magic.  See <code>sv_catpv_mg</code>.</p>
4614 </dd>
4615 <dd>
4616 <pre>
4617         void    sv_catpv(SV* sv, const char* ptr)</pre>
4618 </dd>
4619 </li>
4620 <dt><strong><a name="item_sv_catpvf_x_3csv_catpvf_3e">sv_catpvf
4621 </a></strong>
4622
4623 <dd>
4624 <p>Processes its arguments like <code>sprintf</code> and appends the formatted
4625 output to an SV.  If the appended data contains ``wide'' characters
4626 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
4627 and characters &gt;255 formatted with %c), the original SV might get
4628 upgraded to UTF-8.  Handles 'get' magic, but not 'set' magic.  See
4629 <code>sv_catpvf_mg</code>. If the original SV was UTF-8, the pattern should be
4630 valid UTF-8; if the original SV was bytes, the pattern should be too.</p>
4631 </dd>
4632 <dd>
4633 <pre>
4634         void    sv_catpvf(SV* sv, const char* pat, ...)</pre>
4635 </dd>
4636 </li>
4637 <dt><strong><a name="item_sv_catpvf_mg_x_3csv_catpvf_mg_3e">sv_catpvf_mg
4638 </a></strong>
4639
4640 <dd>
4641 <p>Like <code>sv_catpvf</code>, but also handles 'set' magic.</p>
4642 </dd>
4643 <dd>
4644 <pre>
4645         void    sv_catpvf_mg(SV *sv, const char* pat, ...)</pre>
4646 </dd>
4647 </li>
4648 <dt><strong><a name="item_sv_catpvn_x_3csv_catpvn_3e">sv_catpvn
4649 </a></strong>
4650
4651 <dd>
4652 <p>Concatenates the string onto the end of the string which is in the SV.  The
4653 <code>len</code> indicates number of bytes to copy.  If the SV has the UTF-8
4654 status set, then the bytes appended should be valid UTF-8.
4655 Handles 'get' magic, but not 'set' magic.  See <code>sv_catpvn_mg</code>.</p>
4656 </dd>
4657 <dd>
4658 <pre>
4659         void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)</pre>
4660 </dd>
4661 </li>
4662 <dt><strong><a name="item_sv_catpvn_flags_x_3csv_catpvn_flags_3e">sv_catpvn_flags
4663 </a></strong>
4664
4665 <dd>
4666 <p>Concatenates the string onto the end of the string which is in the SV.  The
4667 <code>len</code> indicates number of bytes to copy.  If the SV has the UTF-8
4668 status set, then the bytes appended should be valid UTF-8.
4669 If <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> has <code>SV_GMAGIC</code> bit set, will <code>mg_get</code> on <code>dsv</code> if
4670 appropriate, else not. <code>sv_catpvn</code> and <code>sv_catpvn_nomg</code> are implemented
4671 in terms of this function.</p>
4672 </dd>
4673 <dd>
4674 <pre>
4675         void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)</pre>
4676 </dd>
4677 </li>
4678 <dt><strong><a name="item_sv_catpvn_mg_x_3csv_catpvn_mg_3e">sv_catpvn_mg
4679 </a></strong>
4680
4681 <dd>
4682 <p>Like <code>sv_catpvn</code>, but also handles 'set' magic.</p>
4683 </dd>
4684 <dd>
4685 <pre>
4686         void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)</pre>
4687 </dd>
4688 </li>
4689 <dt><strong><a name="item_sv_catpvn_nomg_x_3csv_catpvn_nomg_3e">sv_catpvn_nomg
4690 </a></strong>
4691
4692 <dd>
4693 <p>Like <code>sv_catpvn</code> but doesn't process magic.</p>
4694 </dd>
4695 <dd>
4696 <pre>
4697         void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)</pre>
4698 </dd>
4699 </li>
4700 <dt><strong><a name="item_sv_catpv_mg_x_3csv_catpv_mg_3e">sv_catpv_mg
4701 </a></strong>
4702
4703 <dd>
4704 <p>Like <code>sv_catpv</code>, but also handles 'set' magic.</p>
4705 </dd>
4706 <dd>
4707 <pre>
4708         void    sv_catpv_mg(SV *sv, const char *ptr)</pre>
4709 </dd>
4710 </li>
4711 <dt><strong><a name="item_sv_catsv_x_3csv_catsv_3e">sv_catsv
4712 </a></strong>
4713
4714 <dd>
4715 <p>Concatenates the string from SV <code>ssv</code> onto the end of the string in
4716 SV <code>dsv</code>.  Modifies <code>dsv</code> but not <code>ssv</code>.  Handles 'get' magic, but
4717 not 'set' magic.  See <code>sv_catsv_mg</code>.</p>
4718 </dd>
4719 <dd>
4720 <pre>
4721         void    sv_catsv(SV* dsv, SV* ssv)</pre>
4722 </dd>
4723 </li>
4724 <dt><strong><a name="item_sv_catsv_flags_x_3csv_catsv_flags_3e">sv_catsv_flags
4725 </a></strong>
4726
4727 <dd>
4728 <p>Concatenates the string from SV <code>ssv</code> onto the end of the string in
4729 SV <code>dsv</code>.  Modifies <code>dsv</code> but not <code>ssv</code>.  If <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> has <code>SV_GMAGIC</code>
4730 bit set, will <code>mg_get</code> on the SVs if appropriate, else not. <code>sv_catsv</code>
4731 and <code>sv_catsv_nomg</code> are implemented in terms of this function.</p>
4732 </dd>
4733 <dd>
4734 <pre>
4735         void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)</pre>
4736 </dd>
4737 </li>
4738 <dt><strong><a name="item_sv_catsv_mg_x_3csv_catsv_mg_3e">sv_catsv_mg
4739 </a></strong>
4740
4741 <dd>
4742 <p>Like <code>sv_catsv</code>, but also handles 'set' magic.</p>
4743 </dd>
4744 <dd>
4745 <pre>
4746         void    sv_catsv_mg(SV *dstr, SV *sstr)</pre>
4747 </dd>
4748 </li>
4749 <dt><strong><a name="item_sv_catsv_nomg_x_3csv_catsv_nomg_3e">sv_catsv_nomg
4750 </a></strong>
4751
4752 <dd>
4753 <p>Like <code>sv_catsv</code> but doesn't process magic.</p>
4754 </dd>
4755 <dd>
4756 <pre>
4757         void    sv_catsv_nomg(SV* dsv, SV* ssv)</pre>
4758 </dd>
4759 </li>
4760 <dt><strong><a name="item_sv_chop_x_3csv_chop_3e">sv_chop
4761 </a></strong>
4762
4763 <dd>
4764 <p>Efficient removal of characters from the beginning of the string buffer.
4765 <code>SvPOK(sv)</code> must be true and the <code>ptr</code> must be a pointer to somewhere inside
4766 the string buffer.  The <code>ptr</code> becomes the first character of the adjusted
4767 string. Uses the ``OOK hack''.
4768 Beware: after this function returns, <code>ptr</code> and <code>SvPVX_const(sv)</code> may no longer
4769 refer to the same chunk of data.</p>
4770 </dd>
4771 <dd>
4772 <pre>
4773         void    sv_chop(SV* sv, char* ptr)</pre>
4774 </dd>
4775 </li>
4776 <dt><strong><a name="item_sv_clear_x_3csv_clear_3e">sv_clear
4777 </a></strong>
4778
4779 <dd>
4780 <p>Clear an SV: call any destructors, free up any memory used by the body,
4781 and free the body itself. The SV's head is <em>not</em> freed, although
4782 its type is set to all 1's so that it won't inadvertently be assumed
4783 to be live during global destruction etc.
4784 This function should only be called when REFCNT is zero. Most of the time
4785 you'll want to call <code>sv_free()</code> (or its macro wrapper <code>SvREFCNT_dec</code>)
4786 instead.</p>
4787 </dd>
4788 <dd>
4789 <pre>
4790         void    sv_clear(SV* sv)</pre>
4791 </dd>
4792 </li>
4793 <dt><strong><a name="item_sv_cmp_x_3csv_cmp_3e">sv_cmp
4794 </a></strong>
4795
4796 <dd>
4797 <p>Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
4798 string in <code>sv1</code> is less than, equal to, or greater than the string in
4799 <code>sv2</code>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
4800 coerce its args to strings if necessary.  See also <code>sv_cmp_locale</code>.</p>
4801 </dd>
4802 <dd>
4803 <pre>
4804         I32     sv_cmp(SV* sv1, SV* sv2)</pre>
4805 </dd>
4806 </li>
4807 <dt><strong><a name="item_sv_cmp_locale_x_3csv_cmp_locale_3e">sv_cmp_locale
4808 </a></strong>
4809
4810 <dd>
4811 <p>Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
4812 'use bytes' aware, handles get magic, and will coerce its args to strings
4813 if necessary.  See also <code>sv_cmp_locale</code>.  See also <code>sv_cmp</code>.</p>
4814 </dd>
4815 <dd>
4816 <pre>
4817         I32     sv_cmp_locale(SV* sv1, SV* sv2)</pre>
4818 </dd>
4819 </li>
4820 <dt><strong><a name="item_sv_collxfrm_x_3csv_collxfrm_3e">sv_collxfrm
4821 </a></strong>
4822
4823 <dd>
4824 <p>Add Collate Transform magic to an SV if it doesn't already have it.</p>
4825 </dd>
4826 <dd>
4827 <p>Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
4828 scalar data of the variable, but transformed to such a format that a normal
4829 memory comparison can be used to compare the data according to the locale
4830 settings.</p>
4831 </dd>
4832 <dd>
4833 <pre>
4834         char*   sv_collxfrm(SV* sv, STRLEN* nxp)</pre>
4835 </dd>
4836 </li>
4837 <dt><strong><a name="item_sv_copypv_x_3csv_copypv_3e">sv_copypv
4838 </a></strong>
4839
4840 <dd>
4841 <p>Copies a stringified representation of the source SV into the
4842 destination SV.  Automatically performs any necessary mg_get and
4843 coercion of numeric values into strings.  Guaranteed to preserve
4844 UTF-8 flag even from overloaded objects.  Similar in nature to
4845 sv_2pv[_flags] but operates directly on an SV instead of just the
4846 string.  Mostly uses sv_2pv_flags to do its work, except when that
4847 would lose the UTF-8'ness of the PV.</p>
4848 </dd>
4849 <dd>
4850 <pre>
4851         void    sv_copypv(SV* dsv, SV* ssv)</pre>
4852 </dd>
4853 </li>
4854 <dt><strong><a name="item_sv_dec_x_3csv_dec_3e">sv_dec
4855 </a></strong>
4856
4857 <dd>
4858 <p>Auto-decrement of the value in the SV, doing string to numeric conversion
4859 if necessary. Handles 'get' magic.</p>
4860 </dd>
4861 <dd>
4862 <pre>
4863         void    sv_dec(SV* sv)</pre>
4864 </dd>
4865 </li>
4866 <dt><strong><a name="item_sv_derived_from_x_3csv_derived_from_3e">sv_derived_from
4867 </a></strong>
4868
4869 <dd>
4870 <p>Returns a boolean indicating whether the SV is derived from the specified
4871 class.  This is the function that implements <code>UNIVERSAL::isa</code>.  It works
4872 for class names as well as for objects.</p>
4873 </dd>
4874 <dd>
4875 <pre>
4876         bool    sv_derived_from(SV* sv, const char* name)</pre>
4877 </dd>
4878 </li>
4879 <dt><strong><a name="item_sv_eq_x_3csv_eq_3e">sv_eq
4880 </a></strong>
4881
4882 <dd>
4883 <p>Returns a boolean indicating whether the strings in the two SVs are
4884 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
4885 coerce its args to strings if necessary.</p>
4886 </dd>
4887 <dd>
4888 <pre>
4889         I32     sv_eq(SV* sv1, SV* sv2)</pre>
4890 </dd>
4891 </li>
4892 <dt><strong><a name="item_sv_force_normal_x_3csv_force_normal_3e">sv_force_normal
4893 </a></strong>
4894
4895 <dd>
4896 <p>Undo various types of fakery on an SV: if the PV is a shared string, make
4897 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
4898 an xpvmg. See also <code>sv_force_normal_flags</code>.</p>
4899 </dd>
4900 <dd>
4901 <pre>
4902         void    sv_force_normal(SV *sv)</pre>
4903 </dd>
4904 </li>
4905 <dt><strong><a name="item_sv_force_normal_flags_x_3csv_force_normal_flags_3e">sv_force_normal_flags
4906 </a></strong>
4907
4908 <dd>
4909 <p>Undo various types of fakery on an SV: if the PV is a shared string, make
4910 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
4911 an xpvmg. The <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> parameter gets passed to  <code>sv_unref_flags()</code>
4912 when unrefing. <code>sv_force_normal</code> calls this function with flags set to 0.</p>
4913 </dd>
4914 <dd>
4915 <pre>
4916         void    sv_force_normal_flags(SV *sv, U32 flags)</pre>
4917 </dd>
4918 </li>
4919 <dt><strong><a name="item_sv_free_x_3csv_free_3e">sv_free
4920 </a></strong>
4921
4922 <dd>
4923 <p>Decrement an SV's reference count, and if it drops to zero, call
4924 <code>sv_clear</code> to invoke destructors and free up any memory used by
4925 the body; finally, deallocate the SV's head itself.
4926 Normally called via a wrapper macro <code>SvREFCNT_dec</code>.</p>
4927 </dd>
4928 <dd>
4929 <pre>
4930         void    sv_free(SV* sv)</pre>
4931 </dd>
4932 </li>
4933 <dt><strong><a name="item_sv_gets_x_3csv_gets_3e">sv_gets
4934 </a></strong>
4935
4936 <dd>
4937 <p>Get a line from the filehandle and store it into the SV, optionally
4938 appending to the currently-stored string.</p>
4939 </dd>
4940 <dd>
4941 <pre>
4942         char*   sv_gets(SV* sv, PerlIO* fp, I32 append)</pre>
4943 </dd>
4944 </li>
4945 <dt><strong><a name="item_sv_grow_x_3csv_grow_3e">sv_grow
4946 </a></strong>
4947
4948 <dd>
4949 <p>Expands the character buffer in the SV.  If necessary, uses <code>sv_unref</code> and
4950 upgrades the SV to <code>SVt_PV</code>.  Returns a pointer to the character buffer.
4951 Use the <code>SvGROW</code> wrapper instead.</p>
4952 </dd>
4953 <dd>
4954 <pre>
4955         char*   sv_grow(SV* sv, STRLEN newlen)</pre>
4956 </dd>
4957 </li>
4958 <dt><strong><a name="item_sv_inc_x_3csv_inc_3e">sv_inc
4959 </a></strong>
4960
4961 <dd>
4962 <p>Auto-increment of the value in the SV, doing string to numeric conversion
4963 if necessary. Handles 'get' magic.</p>
4964 </dd>
4965 <dd>
4966 <pre>
4967         void    sv_inc(SV* sv)</pre>
4968 </dd>
4969 </li>
4970 <dt><strong><a name="item_sv_insert_x_3csv_insert_3e">sv_insert
4971 </a></strong>
4972
4973 <dd>
4974 <p>Inserts a string at the specified offset/length within the SV. Similar to
4975 the Perl <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item_substr"><code>substr()</code></a> function.</p>
4976 </dd>
4977 <dd>
4978 <pre>
4979         void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)</pre>
4980 </dd>
4981 </li>
4982 <dt><strong><a name="item_sv_isa_x_3csv_isa_3e">sv_isa
4983 </a></strong>
4984
4985 <dd>
4986 <p>Returns a boolean indicating whether the SV is blessed into the specified
4987 class.  This does not check for subtypes; use <code>sv_derived_from</code> to verify
4988 an inheritance relationship.</p>
4989 </dd>
4990 <dd>
4991 <pre>
4992         int     sv_isa(SV* sv, const char* name)</pre>
4993 </dd>
4994 </li>
4995 <dt><strong><a name="item_sv_isobject_x_3csv_isobject_3e">sv_isobject
4996 </a></strong>
4997
4998 <dd>
4999 <p>Returns a boolean indicating whether the SV is an RV pointing to a blessed
5000 object.  If the SV is not an RV, or if the object is not blessed, then this
5001 will return false.</p>
5002 </dd>
5003 <dd>
5004 <pre>
5005         int     sv_isobject(SV* sv)</pre>
5006 </dd>
5007 </li>
5008 <dt><strong><a name="item_sv_iv_x_3csv_iv_3e">sv_iv
5009 </a></strong>
5010
5011 <dd>
5012 <p>A private implementation of the <code>SvIVx</code> macro for compilers which can't
5013 cope with complex macro expressions. Always use the macro instead.</p>
5014 </dd>
5015 <dd>
5016 <pre>
5017         IV      sv_iv(SV* sv)</pre>
5018 </dd>
5019 </li>
5020 <dt><strong><a name="item_sv_len_x_3csv_len_3e">sv_len
5021 </a></strong>
5022
5023 <dd>
5024 <p>Returns the length of the string in the SV. Handles magic and type
5025 coercion.  See also <code>SvCUR</code>, which gives raw access to the xpv_cur slot.</p>
5026 </dd>
5027 <dd>
5028 <pre>
5029         STRLEN  sv_len(SV* sv)</pre>
5030 </dd>
5031 </li>
5032 <dt><strong><a name="item_sv_len_utf8_x_3csv_len_utf8_3e">sv_len_utf8
5033 </a></strong>
5034
5035 <dd>
5036 <p>Returns the number of characters in the string in an SV, counting wide
5037 UTF-8 bytes as a single character. Handles magic and type coercion.</p>
5038 </dd>
5039 <dd>
5040 <pre>
5041         STRLEN  sv_len_utf8(SV* sv)</pre>
5042 </dd>
5043 </li>
5044 <dt><strong><a name="item_sv_magic_x_3csv_magic_3e">sv_magic
5045 </a></strong>
5046
5047 <dd>
5048 <p>Adds magic to an SV. First upgrades <code>sv</code> to type <code>SVt_PVMG</code> if necessary,
5049 then adds a new magic item of type <code>how</code> to the head of the magic list.</p>
5050 </dd>
5051 <dd>
5052 <p>See <code>sv_magicext</code> (which <code>sv_magic</code> now calls) for a description of the
5053 handling of the <code>name</code> and <code>namlen</code> arguments.</p>
5054 </dd>
5055 <dd>
5056 <p>You need to use <code>sv_magicext</code> to add magic to SvREADONLY SVs and also
5057 to add more than one instance of the same 'how'.</p>
5058 </dd>
5059 <dd>
5060 <pre>
5061         void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)</pre>
5062 </dd>
5063 </li>
5064 <dt><strong><a name="item_sv_magicext_x_3csv_magicext_3e">sv_magicext
5065 </a></strong>
5066
5067 <dd>
5068 <p>Adds magic to an SV, upgrading it if necessary. Applies the
5069 supplied vtable and returns a pointer to the magic added.</p>
5070 </dd>
5071 <dd>
5072 <p>Note that <code>sv_magicext</code> will allow things that <code>sv_magic</code> will not.
5073 In particular, you can add magic to SvREADONLY SVs, and add more than
5074 one instance of the same 'how'.</p>
5075 </dd>
5076 <dd>
5077 <p>If <code>namlen</code> is greater than zero then a <code>savepvn</code> <em>copy</em> of <code>name</code> is
5078 stored, if <code>namlen</code> is zero then <code>name</code> is stored as-is and - as another
5079 special case - if <code>(name &amp;&amp; namlen == HEf_SVKEY)</code> then <code>name</code> is assumed
5080 to contain an <code>SV*</code> and is stored as-is with its REFCNT incremented.</p>
5081 </dd>
5082 <dd>
5083 <p>(This is now used as a subroutine by <code>sv_magic</code>.)</p>
5084 </dd>
5085 <dd>
5086 <pre>
5087         MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen)</pre>
5088 </dd>
5089 </li>
5090 <dt><strong><a name="item_sv_mortalcopy_x_3csv_mortalcopy_3e">sv_mortalcopy
5091 </a></strong>
5092
5093 <dd>
5094 <p>Creates a new SV which is a copy of the original SV (using <code>sv_setsv</code>).
5095 The new SV is marked as mortal. It will be destroyed ``soon'', either by an
5096 explicit call to FREETMPS, or by an implicit call at places such as
5097 statement boundaries.  See also <code>sv_newmortal</code> and <code>sv_2mortal</code>.</p>
5098 </dd>
5099 <dd>
5100 <pre>
5101         SV*     sv_mortalcopy(SV* oldsv)</pre>
5102 </dd>
5103 </li>
5104 <dt><strong><a name="item_sv_newmortal_x_3csv_newmortal_3e">sv_newmortal
5105 </a></strong>
5106
5107 <dd>
5108 <p>Creates a new null SV which is mortal.  The reference count of the SV is
5109 set to 1. It will be destroyed ``soon'', either by an explicit call to
5110 FREETMPS, or by an implicit call at places such as statement boundaries.
5111 See also <code>sv_mortalcopy</code> and <code>sv_2mortal</code>.</p>
5112 </dd>
5113 <dd>
5114 <pre>
5115         SV*     sv_newmortal()</pre>
5116 </dd>
5117 </li>
5118 <dt><strong><a name="item_sv_newref_x_3csv_newref_3e">sv_newref
5119 </a></strong>
5120
5121 <dd>
5122 <p>Increment an SV's reference count. Use the <code>SvREFCNT_inc()</code> wrapper
5123 instead.</p>
5124 </dd>
5125 <dd>
5126 <pre>
5127         SV*     sv_newref(SV* sv)</pre>
5128 </dd>
5129 </li>
5130 <dt><strong><a name="item_sv_nv_x_3csv_nv_3e">sv_nv
5131 </a></strong>
5132
5133 <dd>
5134 <p>A private implementation of the <code>SvNVx</code> macro for compilers which can't
5135 cope with complex macro expressions. Always use the macro instead.</p>
5136 </dd>
5137 <dd>
5138 <pre>
5139         NV      sv_nv(SV* sv)</pre>
5140 </dd>
5141 </li>
5142 <dt><strong><a name="item_sv_pos_b2u_x_3csv_pos_b2u_3e">sv_pos_b2u
5143 </a></strong>
5144
5145 <dd>
5146 <p>Converts the value pointed to by offsetp from a count of bytes from the
5147 start of the string, to a count of the equivalent number of UTF-8 chars.
5148 Handles magic and type coercion.</p>
5149 </dd>
5150 <dd>
5151 <pre>
5152         void    sv_pos_b2u(SV* sv, I32* offsetp)</pre>
5153 </dd>
5154 </li>
5155 <dt><strong><a name="item_sv_pos_u2b_x_3csv_pos_u2b_3e">sv_pos_u2b
5156 </a></strong>
5157
5158 <dd>
5159 <p>Converts the value pointed to by offsetp from a count of UTF-8 chars from
5160 the start of the string, to a count of the equivalent number of bytes; if
5161 lenp is non-zero, it does the same to lenp, but this time starting from
5162 the offset, rather than from the start of the string. Handles magic and
5163 type coercion.</p>
5164 </dd>
5165 <dd>
5166 <pre>
5167         void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)</pre>
5168 </dd>
5169 </li>
5170 <dt><strong><a name="item_sv_pv_x_3csv_pv_3e">sv_pv
5171 </a></strong>
5172
5173 <dd>
5174 <p>Use the <code>SvPV_nolen</code> macro instead</p>
5175 </dd>
5176 <dd>
5177 <pre>
5178         char*   sv_pv(SV *sv)</pre>
5179 </dd>
5180 </li>
5181 <dt><strong><a name="item_sv_pvbyte_x_3csv_pvbyte_3e">sv_pvbyte
5182 </a></strong>
5183
5184 <dd>
5185 <p>Use <code>SvPVbyte_nolen</code> instead.</p>
5186 </dd>
5187 <dd>
5188 <pre>
5189         char*   sv_pvbyte(SV *sv)</pre>
5190 </dd>
5191 </li>
5192 <dt><strong><a name="item_sv_pvbyten_x_3csv_pvbyten_3e">sv_pvbyten
5193 </a></strong>
5194
5195 <dd>
5196 <p>A private implementation of the <code>SvPVbyte</code> macro for compilers
5197 which can't cope with complex macro expressions. Always use the macro
5198 instead.</p>
5199 </dd>
5200 <dd>
5201 <pre>
5202         char*   sv_pvbyten(SV *sv, STRLEN *len)</pre>
5203 </dd>
5204 </li>
5205 <dt><strong><a name="item_sv_pvbyten_force_x_3csv_pvbyten_force_3e">sv_pvbyten_force
5206 </a></strong>
5207
5208 <dd>
5209 <p>A private implementation of the <code>SvPVbytex_force</code> macro for compilers
5210 which can't cope with complex macro expressions. Always use the macro
5211 instead.</p>
5212 </dd>
5213 <dd>
5214 <pre>
5215         char*   sv_pvbyten_force(SV* sv, STRLEN* lp)</pre>
5216 </dd>
5217 </li>
5218 <dt><strong><a name="item_sv_pvn_x_3csv_pvn_3e">sv_pvn
5219 </a></strong>
5220
5221 <dd>
5222 <p>A private implementation of the <code>SvPV</code> macro for compilers which can't
5223 cope with complex macro expressions. Always use the macro instead.</p>
5224 </dd>
5225 <dd>
5226 <pre>
5227         char*   sv_pvn(SV *sv, STRLEN *len)</pre>
5228 </dd>
5229 </li>
5230 <dt><strong><a name="item_sv_pvn_force_x_3csv_pvn_force_3e">sv_pvn_force
5231 </a></strong>
5232
5233 <dd>
5234 <p>Get a sensible string out of the SV somehow.
5235 A private implementation of the <code>SvPV_force</code> macro for compilers which
5236 can't cope with complex macro expressions. Always use the macro instead.</p>
5237 </dd>
5238 <dd>
5239 <pre>
5240         char*   sv_pvn_force(SV* sv, STRLEN* lp)</pre>
5241 </dd>
5242 </li>
5243 <dt><strong><a name="item_sv_pvn_force_flags_x_3csv_pvn_force_flags_3e">sv_pvn_force_flags
5244 </a></strong>
5245
5246 <dd>
5247 <p>Get a sensible string out of the SV somehow.
5248 If <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> has <code>SV_GMAGIC</code> bit set, will <code>mg_get</code> on <code>sv</code> if
5249 appropriate, else not. <code>sv_pvn_force</code> and <code>sv_pvn_force_nomg</code> are
5250 implemented in terms of this function.
5251 You normally want to use the various wrapper macros instead: see
5252 <code>SvPV_force</code> and <code>SvPV_force_nomg</code></p>
5253 </dd>
5254 <dd>
5255 <pre>
5256         char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)</pre>
5257 </dd>
5258 </li>
5259 <dt><strong><a name="item_sv_pvutf8_x_3csv_pvutf8_3e">sv_pvutf8
5260 </a></strong>
5261
5262 <dd>
5263 <p>Use the <code>SvPVutf8_nolen</code> macro instead</p>
5264 </dd>
5265 <dd>
5266 <pre>
5267         char*   sv_pvutf8(SV *sv)</pre>
5268 </dd>
5269 </li>
5270 <dt><strong><a name="item_sv_pvutf8n_x_3csv_pvutf8n_3e">sv_pvutf8n
5271 </a></strong>
5272
5273 <dd>
5274 <p>A private implementation of the <code>SvPVutf8</code> macro for compilers
5275 which can't cope with complex macro expressions. Always use the macro
5276 instead.</p>
5277 </dd>
5278 <dd>
5279 <pre>
5280         char*   sv_pvutf8n(SV *sv, STRLEN *len)</pre>
5281 </dd>
5282 </li>
5283 <dt><strong><a name="item_sv_pvutf8n_force_x_3csv_pvutf8n_force_3e">sv_pvutf8n_force
5284 </a></strong>
5285
5286 <dd>
5287 <p>A private implementation of the <code>SvPVutf8_force</code> macro for compilers
5288 which can't cope with complex macro expressions. Always use the macro
5289 instead.</p>
5290 </dd>
5291 <dd>
5292 <pre>
5293         char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)</pre>
5294 </dd>
5295 </li>
5296 <dt><strong><a name="item_sv_reftype_x_3csv_reftype_3e">sv_reftype
5297 </a></strong>
5298
5299 <dd>
5300 <p>Returns a string describing what the SV is a reference to.</p>
5301 </dd>
5302 <dd>
5303 <pre>
5304         char*   sv_reftype(SV* sv, int ob)</pre>
5305 </dd>
5306 </li>
5307 <dt><strong><a name="item_sv_replace_x_3csv_replace_3e">sv_replace
5308 </a></strong>
5309
5310 <dd>
5311 <p>Make the first argument a copy of the second, then delete the original.
5312 The target SV physically takes over ownership of the body of the source SV
5313 and inherits its flags; however, the target keeps any magic it owns,
5314 and any magic in the source is discarded.
5315 Note that this is a rather specialist SV copying operation; most of the
5316 time you'll want to use <code>sv_setsv</code> or one of its many macro front-ends.</p>
5317 </dd>
5318 <dd>
5319 <pre>
5320         void    sv_replace(SV* sv, SV* nsv)</pre>
5321 </dd>
5322 </li>
5323 <dt><strong><a name="item_sv_report_used_x_3csv_report_used_3e">sv_report_used
5324 </a></strong>
5325
5326 <dd>
5327 <p>Dump the contents of all SVs not yet freed. (Debugging aid).</p>
5328 </dd>
5329 <dd>
5330 <pre>
5331         void    sv_report_used()</pre>
5332 </dd>
5333 </li>
5334 <dt><strong><a name="item_sv_reset_x_3csv_reset_3e">sv_reset
5335 </a></strong>
5336
5337 <dd>
5338 <p>Underlying implementation for the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_reset"><code>reset</code></a> Perl function.
5339 Note that the perl-level function is vaguely deprecated.</p>
5340 </dd>
5341 <dd>
5342 <pre>
5343         void    sv_reset(char* s, HV* stash)</pre>
5344 </dd>
5345 </li>
5346 <dt><strong><a name="item_sv_rvweaken_x_3csv_rvweaken_3e">sv_rvweaken
5347 </a></strong>
5348
5349 <dd>
5350 <p>Weaken a reference: set the <code>SvWEAKREF</code> flag on this RV; give the
5351 referred-to SV <code>PERL_MAGIC_backref</code> magic if it hasn't already; and
5352 push a back-reference to this RV onto the array of backreferences
5353 associated with that magic.</p>
5354 </dd>
5355 <dd>
5356 <pre>
5357         SV*     sv_rvweaken(SV *sv)</pre>
5358 </dd>
5359 </li>
5360 <dt><strong><a name="item_sv_setiv_x_3csv_setiv_3e">sv_setiv
5361 </a></strong>
5362
5363 <dd>
5364 <p>Copies an integer into the given SV, upgrading first if necessary.
5365 Does not handle 'set' magic.  See also <code>sv_setiv_mg</code>.</p>
5366 </dd>
5367 <dd>
5368 <pre>
5369         void    sv_setiv(SV* sv, IV num)</pre>
5370 </dd>
5371 </li>
5372 <dt><strong><a name="item_sv_setiv_mg_x_3csv_setiv_mg_3e">sv_setiv_mg
5373 </a></strong>
5374
5375 <dd>
5376 <p>Like <code>sv_setiv</code>, but also handles 'set' magic.</p>
5377 </dd>
5378 <dd>
5379 <pre>
5380         void    sv_setiv_mg(SV *sv, IV i)</pre>
5381 </dd>
5382 </li>
5383 <dt><strong><a name="item_sv_setnv_x_3csv_setnv_3e">sv_setnv
5384 </a></strong>
5385
5386 <dd>
5387 <p>Copies a double into the given SV, upgrading first if necessary.
5388 Does not handle 'set' magic.  See also <code>sv_setnv_mg</code>.</p>
5389 </dd>
5390 <dd>
5391 <pre>
5392         void    sv_setnv(SV* sv, NV num)</pre>
5393 </dd>
5394 </li>
5395 <dt><strong><a name="item_sv_setnv_mg_x_3csv_setnv_mg_3e">sv_setnv_mg
5396 </a></strong>
5397
5398 <dd>
5399 <p>Like <code>sv_setnv</code>, but also handles 'set' magic.</p>
5400 </dd>
5401 <dd>
5402 <pre>
5403         void    sv_setnv_mg(SV *sv, NV num)</pre>
5404 </dd>
5405 </li>
5406 <dt><strong><a name="item_sv_setpv_x_3csv_setpv_3e">sv_setpv
5407 </a></strong>
5408
5409 <dd>
5410 <p>Copies a string into an SV.  The string must be null-terminated.  Does not
5411 handle 'set' magic.  See <code>sv_setpv_mg</code>.</p>
5412 </dd>
5413 <dd>
5414 <pre>
5415         void    sv_setpv(SV* sv, const char* ptr)</pre>
5416 </dd>
5417 </li>
5418 <dt><strong><a name="item_sv_setpvf_x_3csv_setpvf_3e">sv_setpvf
5419 </a></strong>
5420
5421 <dd>
5422 <p>Works like <code>sv_catpvf</code> but copies the text into the SV instead of
5423 appending it.  Does not handle 'set' magic.  See <code>sv_setpvf_mg</code>.</p>
5424 </dd>
5425 <dd>
5426 <pre>
5427         void    sv_setpvf(SV* sv, const char* pat, ...)</pre>
5428 </dd>
5429 </li>
5430 <dt><strong><a name="item_sv_setpvf_mg_x_3csv_setpvf_mg_3e">sv_setpvf_mg
5431 </a></strong>
5432
5433 <dd>
5434 <p>Like <code>sv_setpvf</code>, but also handles 'set' magic.</p>
5435 </dd>
5436 <dd>
5437 <pre>
5438         void    sv_setpvf_mg(SV *sv, const char* pat, ...)</pre>
5439 </dd>
5440 </li>
5441 <dt><strong><a name="item_sv_setpviv_x_3csv_setpviv_3e">sv_setpviv
5442 </a></strong>
5443
5444 <dd>
5445 <p>Copies an integer into the given SV, also updating its string value.
5446 Does not handle 'set' magic.  See <code>sv_setpviv_mg</code>.</p>
5447 </dd>
5448 <dd>
5449 <pre>
5450         void    sv_setpviv(SV* sv, IV num)</pre>
5451 </dd>
5452 </li>
5453 <dt><strong><a name="item_sv_setpviv_mg_x_3csv_setpviv_mg_3e">sv_setpviv_mg
5454 </a></strong>
5455
5456 <dd>
5457 <p>Like <code>sv_setpviv</code>, but also handles 'set' magic.</p>
5458 </dd>
5459 <dd>
5460 <pre>
5461         void    sv_setpviv_mg(SV *sv, IV iv)</pre>
5462 </dd>
5463 </li>
5464 <dt><strong><a name="item_sv_setpvn_x_3csv_setpvn_3e">sv_setpvn
5465 </a></strong>
5466
5467 <dd>
5468 <p>Copies a string into an SV.  The <code>len</code> parameter indicates the number of
5469 bytes to be copied.  If the <code>ptr</code> argument is NULL the SV will become
5470 undefined.  Does not handle 'set' magic.  See <code>sv_setpvn_mg</code>.</p>
5471 </dd>
5472 <dd>
5473 <pre>
5474         void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)</pre>
5475 </dd>
5476 </li>
5477 <dt><strong><a name="item_sv_setpvn_mg_x_3csv_setpvn_mg_3e">sv_setpvn_mg
5478 </a></strong>
5479
5480 <dd>
5481 <p>Like <code>sv_setpvn</code>, but also handles 'set' magic.</p>
5482 </dd>
5483 <dd>
5484 <pre>
5485         void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)</pre>
5486 </dd>
5487 </li>
5488 <dt><strong><a name="item_sv_setpv_mg_x_3csv_setpv_mg_3e">sv_setpv_mg
5489 </a></strong>
5490
5491 <dd>
5492 <p>Like <code>sv_setpv</code>, but also handles 'set' magic.</p>
5493 </dd>
5494 <dd>
5495 <pre>
5496         void    sv_setpv_mg(SV *sv, const char *ptr)</pre>
5497 </dd>
5498 </li>
5499 <dt><strong><a name="item_sv_setref_iv_x_3csv_setref_iv_3e">sv_setref_iv
5500 </a></strong>
5501
5502 <dd>
5503 <p>Copies an integer into a new SV, optionally blessing the SV.  The <code>rv</code>
5504 argument will be upgraded to an RV.  That RV will be modified to point to
5505 the new SV.  The <code>classname</code> argument indicates the package for the
5506 blessing.  Set <code>classname</code> to <code>Nullch</code> to avoid the blessing.  The new SV
5507 will have a reference count of 1, and the RV will be returned.</p>
5508 </dd>
5509 <dd>
5510 <pre>
5511         SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)</pre>
5512 </dd>
5513 </li>
5514 <dt><strong><a name="item_sv_setref_nv_x_3csv_setref_nv_3e">sv_setref_nv
5515 </a></strong>
5516
5517 <dd>
5518 <p>Copies a double into a new SV, optionally blessing the SV.  The <code>rv</code>
5519 argument will be upgraded to an RV.  That RV will be modified to point to
5520 the new SV.  The <code>classname</code> argument indicates the package for the
5521 blessing.  Set <code>classname</code> to <code>Nullch</code> to avoid the blessing.  The new SV
5522 will have a reference count of 1, and the RV will be returned.</p>
5523 </dd>
5524 <dd>
5525 <pre>
5526         SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)</pre>
5527 </dd>
5528 </li>
5529 <dt><strong><a name="item_sv_setref_pv_x_3csv_setref_pv_3e">sv_setref_pv
5530 </a></strong>
5531
5532 <dd>
5533 <p>Copies a pointer into a new SV, optionally blessing the SV.  The <code>rv</code>
5534 argument will be upgraded to an RV.  That RV will be modified to point to
5535 the new SV.  If the <code>pv</code> argument is NULL then <code>PL_sv_undef</code> will be placed
5536 into the SV.  The <code>classname</code> argument indicates the package for the
5537 blessing.  Set <code>classname</code> to <code>Nullch</code> to avoid the blessing.  The new SV
5538 will have a reference count of 1, and the RV will be returned.</p>
5539 </dd>
5540 <dd>
5541 <p>Do not use with other Perl types such as HV, AV, SV, CV, because those
5542 objects will become corrupted by the pointer copy process.</p>
5543 </dd>
5544 <dd>
5545 <p>Note that <code>sv_setref_pvn</code> copies the string while this copies the pointer.</p>
5546 </dd>
5547 <dd>
5548 <pre>
5549         SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)</pre>
5550 </dd>
5551 </li>
5552 <dt><strong><a name="item_sv_setref_pvn_x_3csv_setref_pvn_3e">sv_setref_pvn
5553 </a></strong>
5554
5555 <dd>
5556 <p>Copies a string into a new SV, optionally blessing the SV.  The length of the
5557 string must be specified with <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_n"><code>n</code></a>.  The <code>rv</code> argument will be upgraded to
5558 an RV.  That RV will be modified to point to the new SV.  The <code>classname</code>
5559 argument indicates the package for the blessing.  Set <code>classname</code> to
5560 <code>Nullch</code> to avoid the blessing.  The new SV will have a reference count
5561 of 1, and the RV will be returned.</p>
5562 </dd>
5563 <dd>
5564 <p>Note that <code>sv_setref_pv</code> copies the pointer while this copies the string.</p>
5565 </dd>
5566 <dd>
5567 <pre>
5568         SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)</pre>
5569 </dd>
5570 </li>
5571 <dt><strong><a name="item_sv_setref_uv_x_3csv_setref_uv_3e">sv_setref_uv
5572 </a></strong>
5573
5574 <dd>
5575 <p>Copies an unsigned integer into a new SV, optionally blessing the SV.  The <code>rv</code>
5576 argument will be upgraded to an RV.  That RV will be modified to point to
5577 the new SV.  The <code>classname</code> argument indicates the package for the
5578 blessing.  Set <code>classname</code> to <code>Nullch</code> to avoid the blessing.  The new SV
5579 will have a reference count of 1, and the RV will be returned.</p>
5580 </dd>
5581 <dd>
5582 <pre>
5583         SV*     sv_setref_uv(SV* rv, const char* classname, UV uv)</pre>
5584 </dd>
5585 </li>
5586 <dt><strong><a name="item_sv_setsv_x_3csv_setsv_3e">sv_setsv
5587 </a></strong>
5588
5589 <dd>
5590 <p>Copies the contents of the source SV <code>ssv</code> into the destination SV
5591 <code>dsv</code>.  The source SV may be destroyed if it is mortal, so don't use this
5592 function if the source SV needs to be reused. Does not handle 'set' magic.
5593 Loosely speaking, it performs a copy-by-value, obliterating any previous
5594 content of the destination.</p>
5595 </dd>
5596 <dd>
5597 <p>You probably want to use one of the assortment of wrappers, such as
5598 <code>SvSetSV</code>, <code>SvSetSV_nosteal</code>, <code>SvSetMagicSV</code> and
5599 <code>SvSetMagicSV_nosteal</code>.</p>
5600 </dd>
5601 <dd>
5602 <pre>
5603         void    sv_setsv(SV* dsv, SV* ssv)</pre>
5604 </dd>
5605 </li>
5606 <dt><strong><a name="item_sv_setsv_flags_x_3csv_setsv_flags_3e">sv_setsv_flags
5607 </a></strong>
5608
5609 <dd>
5610 <p>Copies the contents of the source SV <code>ssv</code> into the destination SV
5611 <code>dsv</code>.  The source SV may be destroyed if it is mortal, so don't use this
5612 function if the source SV needs to be reused. Does not handle 'set' magic.
5613 Loosely speaking, it performs a copy-by-value, obliterating any previous
5614 content of the destination.
5615 If the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> parameter has the <code>SV_GMAGIC</code> bit set, will <code>mg_get</code> on
5616 <code>ssv</code> if appropriate, else not. If the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> parameter has the
5617 <code>NOSTEAL</code> bit set then the buffers of temps will not be stolen. &lt;sv_setsv&gt;
5618 and <code>sv_setsv_nomg</code> are implemented in terms of this function.</p>
5619 </dd>
5620 <dd>
5621 <p>You probably want to use one of the assortment of wrappers, such as
5622 <code>SvSetSV</code>, <code>SvSetSV_nosteal</code>, <code>SvSetMagicSV</code> and
5623 <code>SvSetMagicSV_nosteal</code>.</p>
5624 </dd>
5625 <dd>
5626 <p>This is the primary function for copying scalars, and most other
5627 copy-ish functions and macros use this underneath.</p>
5628 </dd>
5629 <dd>
5630 <pre>
5631         void    sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)</pre>
5632 </dd>
5633 </li>
5634 <dt><strong><a name="item_sv_setsv_mg_x_3csv_setsv_mg_3e">sv_setsv_mg
5635 </a></strong>
5636
5637 <dd>
5638 <p>Like <code>sv_setsv</code>, but also handles 'set' magic.</p>
5639 </dd>
5640 <dd>
5641 <pre>
5642         void    sv_setsv_mg(SV *dstr, SV *sstr)</pre>
5643 </dd>
5644 </li>
5645 <dt><strong><a name="item_sv_setsv_nomg_x_3csv_setsv_nomg_3e">sv_setsv_nomg
5646 </a></strong>
5647
5648 <dd>
5649 <p>Like <code>sv_setsv</code> but doesn't process magic.</p>
5650 </dd>
5651 <dd>
5652 <pre>
5653         void    sv_setsv_nomg(SV* dsv, SV* ssv)</pre>
5654 </dd>
5655 </li>
5656 <dt><strong><a name="item_sv_setuv_x_3csv_setuv_3e">sv_setuv
5657 </a></strong>
5658
5659 <dd>
5660 <p>Copies an unsigned integer into the given SV, upgrading first if necessary.
5661 Does not handle 'set' magic.  See also <code>sv_setuv_mg</code>.</p>
5662 </dd>
5663 <dd>
5664 <pre>
5665         void    sv_setuv(SV* sv, UV num)</pre>
5666 </dd>
5667 </li>
5668 <dt><strong><a name="item_sv_setuv_mg_x_3csv_setuv_mg_3e">sv_setuv_mg
5669 </a></strong>
5670
5671 <dd>
5672 <p>Like <code>sv_setuv</code>, but also handles 'set' magic.</p>
5673 </dd>
5674 <dd>
5675 <pre>
5676         void    sv_setuv_mg(SV *sv, UV u)</pre>
5677 </dd>
5678 </li>
5679 <dt><strong><a name="item_sv_taint_x_3csv_taint_3e">sv_taint
5680 </a></strong>
5681
5682 <dd>
5683 <p><table cellspacing="0" cellpadding="0"><tr><td>Taint an SV. Use <code>SvTAINTED_on</code> instead.
5684 <tr><td><td>void<td>sv_taint(SV* sv)</table></p>
5685 </dd>
5686 </li>
5687 <dt><strong><a name="item_sv_tainted_x_3csv_tainted_3e">sv_tainted
5688 </a></strong>
5689
5690 <dd>
5691 <p><table cellspacing="0" cellpadding="0"><tr><td>Test an SV for taintedness. Use <code>SvTAINTED</code> instead.
5692 <tr><td><td>bool<td>sv_tainted(SV* sv)</table></p>
5693 </dd>
5694 </li>
5695 <dt><strong><a name="item_sv_true_x_3csv_true_3e">sv_true
5696 </a></strong>
5697
5698 <dd>
5699 <p>Returns true if the SV has a true value by Perl's rules.
5700 Use the <code>SvTRUE</code> macro instead, which may call <code>sv_true()</code> or may
5701 instead use an in-line version.</p>
5702 </dd>
5703 <dd>
5704 <pre>
5705         I32     sv_true(SV *sv)</pre>
5706 </dd>
5707 </li>
5708 <dt><strong><a name="item_sv_unmagic_x_3csv_unmagic_3e">sv_unmagic
5709 </a></strong>
5710
5711 <dd>
5712 <p>Removes all magic of type <code>type</code> from an SV.</p>
5713 </dd>
5714 <dd>
5715 <pre>
5716         int     sv_unmagic(SV* sv, int type)</pre>
5717 </dd>
5718 </li>
5719 <dt><strong><a name="item_sv_unref_x_3csv_unref_3e">sv_unref
5720 </a></strong>
5721
5722 <dd>
5723 <p>Unsets the RV status of the SV, and decrements the reference count of
5724 whatever was being referenced by the RV.  This can almost be thought of
5725 as a reversal of <code>newSVrv</code>.  This is <code>sv_unref_flags</code> with the <code>flag</code>
5726 being zero.  See <code>SvROK_off</code>.</p>
5727 </dd>
5728 <dd>
5729 <pre>
5730         void    sv_unref(SV* sv)</pre>
5731 </dd>
5732 </li>
5733 <dt><strong><a name="item_sv_unref_flags_x_3csv_unref_flags_3e">sv_unref_flags
5734 </a></strong>
5735
5736 <dd>
5737 <p>Unsets the RV status of the SV, and decrements the reference count of
5738 whatever was being referenced by the RV.  This can almost be thought of
5739 as a reversal of <code>newSVrv</code>.  The <code>cflags</code> argument can contain
5740 <code>SV_IMMEDIATE_UNREF</code> to force the reference count to be decremented
5741 (otherwise the decrementing is conditional on the reference count being
5742 different from one or the reference being a readonly SV).
5743 See <code>SvROK_off</code>.</p>
5744 </dd>
5745 <dd>
5746 <pre>
5747         void    sv_unref_flags(SV* sv, U32 flags)</pre>
5748 </dd>
5749 </li>
5750 <dt><strong><a name="item_sv_untaint_x_3csv_untaint_3e">sv_untaint
5751 </a></strong>
5752
5753 <dd>
5754 <p><table cellspacing="0" cellpadding="0"><tr><td>Untaint an SV. Use <code>SvTAINTED_off</code> instead.
5755 <tr><td><td>void<td>sv_untaint(SV* sv)</table></p>
5756 </dd>
5757 </li>
5758 <dt><strong><a name="item_sv_upgrade_x_3csv_upgrade_3e">sv_upgrade
5759 </a></strong>
5760
5761 <dd>
5762 <p>Upgrade an SV to a more complex form.  Generally adds a new body type to the
5763 SV, then copies across as much information as possible from the old body.
5764 You generally want to use the <code>SvUPGRADE</code> macro wrapper. See also <code>svtype</code>.</p>
5765 </dd>
5766 <dd>
5767 <pre>
5768         bool    sv_upgrade(SV* sv, U32 mt)</pre>
5769 </dd>
5770 </li>
5771 <dt><strong><a name="item_sv_usepvn_x_3csv_usepvn_3e">sv_usepvn
5772 </a></strong>
5773
5774 <dd>
5775 <p>Tells an SV to use <code>ptr</code> to find its string value.  Normally the string is
5776 stored inside the SV but sv_usepvn allows the SV to use an outside string.
5777 The <code>ptr</code> should point to memory that was allocated by <code>malloc</code>.  The
5778 string length, <code>len</code>, must be supplied.  This function will realloc the
5779 memory pointed to by <code>ptr</code>, so that pointer should not be freed or used by
5780 the programmer after giving it to sv_usepvn.  Does not handle 'set' magic.
5781 See <code>sv_usepvn_mg</code>.</p>
5782 </dd>
5783 <dd>
5784 <pre>
5785         void    sv_usepvn(SV* sv, char* ptr, STRLEN len)</pre>
5786 </dd>
5787 </li>
5788 <dt><strong><a name="item_sv_usepvn_mg_x_3csv_usepvn_mg_3e">sv_usepvn_mg
5789 </a></strong>
5790
5791 <dd>
5792 <p>Like <code>sv_usepvn</code>, but also handles 'set' magic.</p>
5793 </dd>
5794 <dd>
5795 <pre>
5796         void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)</pre>
5797 </dd>
5798 </li>
5799 <dt><strong><a name="item_sv_utf8_decode_x_3csv_utf8_decode_3e">sv_utf8_decode
5800 </a></strong>
5801
5802 <dd>
5803 <p>If the PV of the SV is an octet sequence in UTF-8
5804 and contains a multiple-byte character, the <code>SvUTF8</code> flag is turned on
5805 so that it looks like a character. If the PV contains only single-byte
5806 characters, the <code>SvUTF8</code> flag stays being off.
5807 Scans PV for validity and returns false if the PV is invalid UTF-8.</p>
5808 </dd>
5809 <dd>
5810 <p>NOTE: this function is experimental and may change or be
5811 removed without notice.</p>
5812 </dd>
5813 <dd>
5814 <pre>
5815         bool    sv_utf8_decode(SV *sv)</pre>
5816 </dd>
5817 </li>
5818 <dt><strong><a name="item_sv_utf8_downgrade_x_3csv_utf8_downgrade_3e">sv_utf8_downgrade
5819 </a></strong>
5820
5821 <dd>
5822 <p>Attempts to convert the PV of an SV from characters to bytes.
5823 If the PV contains a character beyond byte, this conversion will fail;
5824 in this case, either returns false or, if <code>fail_ok</code> is not
5825 true, croaks.</p>
5826 </dd>
5827 <dd>
5828 <p>This is not as a general purpose Unicode to byte encoding interface:
5829 use the Encode extension for that.</p>
5830 </dd>
5831 <dd>
5832 <p>NOTE: this function is experimental and may change or be
5833 removed without notice.</p>
5834 </dd>
5835 <dd>
5836 <pre>
5837         bool    sv_utf8_downgrade(SV *sv, bool fail_ok)</pre>
5838 </dd>
5839 </li>
5840 <dt><strong><a name="item_sv_utf8_encode_x_3csv_utf8_encode_3e">sv_utf8_encode
5841 </a></strong>
5842
5843 <dd>
5844 <p>Converts the PV of an SV to UTF-8, but then turns the <code>SvUTF8</code>
5845 flag off so that it looks like octets again.</p>
5846 </dd>
5847 <dd>
5848 <pre>
5849         void    sv_utf8_encode(SV *sv)</pre>
5850 </dd>
5851 </li>
5852 <dt><strong><a name="item_sv_utf8_upgrade_x_3csv_utf8_upgrade_3e">sv_utf8_upgrade
5853 </a></strong>
5854
5855 <dd>
5856 <p>Converts the PV of an SV to its UTF-8-encoded form.
5857 Forces the SV to string form if it is not already.
5858 Always sets the SvUTF8 flag to avoid future validity checks even
5859 if all the bytes have hibit clear.</p>
5860 </dd>
5861 <dd>
5862 <p>This is not as a general purpose byte encoding to Unicode interface:
5863 use the Encode extension for that.</p>
5864 </dd>
5865 <dd>
5866 <pre>
5867         STRLEN  sv_utf8_upgrade(SV *sv)</pre>
5868 </dd>
5869 </li>
5870 <dt><strong><a name="item_sv_utf8_upgrade_flags_x_3csv_utf8_upgrade_flags_3e">sv_utf8_upgrade_flags
5871 </a></strong>
5872
5873 <dd>
5874 <p>Converts the PV of an SV to its UTF-8-encoded form.
5875 Forces the SV to string form if it is not already.
5876 Always sets the SvUTF8 flag to avoid future validity checks even
5877 if all the bytes have hibit clear. If <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> has <code>SV_GMAGIC</code> bit set,
5878 will <code>mg_get</code> on <code>sv</code> if appropriate, else not. <code>sv_utf8_upgrade</code> and
5879 <code>sv_utf8_upgrade_nomg</code> are implemented in terms of this function.</p>
5880 </dd>
5881 <dd>
5882 <p>This is not as a general purpose byte encoding to Unicode interface:
5883 use the Encode extension for that.</p>
5884 </dd>
5885 <dd>
5886 <pre>
5887         STRLEN  sv_utf8_upgrade_flags(SV *sv, I32 flags)</pre>
5888 </dd>
5889 </li>
5890 <dt><strong><a name="item_sv_uv_x_3csv_uv_3e">sv_uv
5891 </a></strong>
5892
5893 <dd>
5894 <p>A private implementation of the <code>SvUVx</code> macro for compilers which can't
5895 cope with complex macro expressions. Always use the macro instead.</p>
5896 </dd>
5897 <dd>
5898 <pre>
5899         UV      sv_uv(SV* sv)</pre>
5900 </dd>
5901 </li>
5902 <dt><strong><a name="item_sv_vcatpvf_x_3csv_vcatpvf_3e">sv_vcatpvf
5903 </a></strong>
5904
5905 <dd>
5906 <p>Processes its arguments like <code>vsprintf</code> and appends the formatted output
5907 to an SV.  Does not handle 'set' magic.  See <code>sv_vcatpvf_mg</code>.</p>
5908 </dd>
5909 <dd>
5910 <p>Usually used via its frontend <code>sv_catpvf</code>.</p>
5911 </dd>
5912 <dd>
5913 <pre>
5914         void    sv_vcatpvf(SV* sv, const char* pat, va_list* args)</pre>
5915 </dd>
5916 </li>
5917 <dt><strong><a name="item_sv_vcatpvfn_x_3csv_vcatpvfn_3e">sv_vcatpvfn
5918 </a></strong>
5919
5920 <dd>
5921 <p>Processes its arguments like <code>vsprintf</code> and appends the formatted output
5922 to an SV.  Uses an array of SVs if the C style variable argument list is
5923 missing (NULL).  When running with taint checks enabled, indicates via
5924 <code>maybe_tainted</code> if results are untrustworthy (often due to the use of
5925 locales).</p>
5926 </dd>
5927 <dd>
5928 <p>XXX Except that it maybe_tainted is never assigned to.</p>
5929 </dd>
5930 <dd>
5931 <p>Usually used via one of its frontends <code>sv_vcatpvf</code> and <code>sv_vcatpvf_mg</code>.</p>
5932 </dd>
5933 <dd>
5934 <pre>
5935         void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)</pre>
5936 </dd>
5937 </li>
5938 <dt><strong><a name="item_sv_vcatpvf_mg_x_3csv_vcatpvf_mg_3e">sv_vcatpvf_mg
5939 </a></strong>
5940
5941 <dd>
5942 <p>Like <code>sv_vcatpvf</code>, but also handles 'set' magic.</p>
5943 </dd>
5944 <dd>
5945 <p>Usually used via its frontend <code>sv_catpvf_mg</code>.</p>
5946 </dd>
5947 <dd>
5948 <pre>
5949         void    sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)</pre>
5950 </dd>
5951 </li>
5952 <dt><strong><a name="item_sv_vsetpvf_x_3csv_vsetpvf_3e">sv_vsetpvf
5953 </a></strong>
5954
5955 <dd>
5956 <p>Works like <code>sv_vcatpvf</code> but copies the text into the SV instead of
5957 appending it.  Does not handle 'set' magic.  See <code>sv_vsetpvf_mg</code>.</p>
5958 </dd>
5959 <dd>
5960 <p>Usually used via its frontend <code>sv_setpvf</code>.</p>
5961 </dd>
5962 <dd>
5963 <pre>
5964         void    sv_vsetpvf(SV* sv, const char* pat, va_list* args)</pre>
5965 </dd>
5966 </li>
5967 <dt><strong><a name="item_sv_vsetpvfn_x_3csv_vsetpvfn_3e">sv_vsetpvfn
5968 </a></strong>
5969
5970 <dd>
5971 <p>Works like <code>sv_vcatpvfn</code> but copies the text into the SV instead of
5972 appending it.</p>
5973 </dd>
5974 <dd>
5975 <p>Usually used via one of its frontends <code>sv_vsetpvf</code> and <code>sv_vsetpvf_mg</code>.</p>
5976 </dd>
5977 <dd>
5978 <pre>
5979         void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)</pre>
5980 </dd>
5981 </li>
5982 <dt><strong><a name="item_sv_vsetpvf_mg_x_3csv_vsetpvf_mg_3e">sv_vsetpvf_mg
5983 </a></strong>
5984
5985 <dd>
5986 <p>Like <code>sv_vsetpvf</code>, but also handles 'set' magic.</p>
5987 </dd>
5988 <dd>
5989 <p>Usually used via its frontend <code>sv_setpvf_mg</code>.</p>
5990 </dd>
5991 <dd>
5992 <pre>
5993         void    sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)</pre>
5994 </dd>
5995 </li>
5996 </dl>
5997 <p>
5998 </p>
5999 <hr />
6000 <h1><a name="unicode_support">Unicode Support</a></h1>
6001 <dl>
6002 <dt><strong><a name="item_bytes_from_utf8_x_3cbytes_from_utf8_3e">bytes_from_utf8
6003 </a></strong>
6004
6005 <dd>
6006 <p>Converts a string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> of length <code>len</code> from UTF-8 into byte encoding.
6007 Unlike <code>utf8_to_bytes</code> but like <code>bytes_to_utf8</code>, returns a pointer to
6008 the newly-created string, and updates <code>len</code> to contain the new
6009 length.  Returns the original string if no conversion occurs, <code>len</code>
6010 is unchanged. Do nothing if <code>is_utf8</code> points to 0. Sets <code>is_utf8</code> to
6011 0 if <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> is converted or contains all 7bit characters.</p>
6012 </dd>
6013 <dd>
6014 <p>NOTE: this function is experimental and may change or be
6015 removed without notice.</p>
6016 </dd>
6017 <dd>
6018 <pre>
6019         U8*     bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)</pre>
6020 </dd>
6021 </li>
6022 <dt><strong><a name="item_bytes_to_utf8_x_3cbytes_to_utf8_3e">bytes_to_utf8
6023 </a></strong>
6024
6025 <dd>
6026 <p>Converts a string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> of length <code>len</code> from ASCII into UTF-8 encoding.
6027 Returns a pointer to the newly-created string, and sets <code>len</code> to
6028 reflect the new length.</p>
6029 </dd>
6030 <dd>
6031 <p>If you want to convert to UTF-8 from other encodings than ASCII,
6032 see sv_recode_to_utf8().</p>
6033 </dd>
6034 <dd>
6035 <p>NOTE: this function is experimental and may change or be
6036 removed without notice.</p>
6037 </dd>
6038 <dd>
6039 <pre>
6040         U8*     bytes_to_utf8(U8 *s, STRLEN *len)</pre>
6041 </dd>
6042 </li>
6043 <dt><strong><a name="item_ibcmp_utf8_x_3cibcmp_utf8_3e">ibcmp_utf8
6044 </a></strong>
6045
6046 <dd>
6047 <p>Return true if the strings s1 and s2 differ case-insensitively, false
6048 if not (if they are equal case-insensitively).  If u1 is true, the
6049 string s1 is assumed to be in UTF-8-encoded Unicode.  If u2 is true,
6050 the string s2 is assumed to be in UTF-8-encoded Unicode.  If u1 or u2
6051 are false, the respective string is assumed to be in native 8-bit
6052 encoding.</p>
6053 </dd>
6054 <dd>
6055 <p>If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
6056 in there (they will point at the beginning of the <em>next</em> character).
6057 If the pointers behind pe1 or pe2 are non-NULL, they are the end
6058 pointers beyond which scanning will not continue under any
6059 circumstances.  If the byte lengths l1 and l2 are non-zero, s1+l1 and
6060 s2+l2 will be used as goal end pointers that will also stop the scan,
6061 and which qualify towards defining a successful match: all the scans
6062 that define an explicit length must reach their goal pointers for
6063 a match to succeed).</p>
6064 </dd>
6065 <dd>
6066 <p>For case-insensitiveness, the ``casefolding'' of Unicode is used
6067 instead of upper/lowercasing both the characters, see
6068 <a href="http://www.unicode.org/unicode/reports/tr21/">http://www.unicode.org/unicode/reports/tr21/</a> (Case Mappings).</p>
6069 </dd>
6070 <dd>
6071 <pre>
6072         I32     ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)</pre>
6073 </dd>
6074 </li>
6075 <dt><strong><a name="item_is_utf8_char_x_3cis_utf8_char_3e">is_utf8_char
6076 </a></strong>
6077
6078 <dd>
6079 <p>Tests if some arbitrary number of bytes begins in a valid UTF-8
6080 character.  Note that an INVARIANT (i.e. ASCII) character is a valid
6081 UTF-8 character.  The actual number of bytes in the UTF-8 character
6082 will be returned if it is valid, otherwise 0.</p>
6083 </dd>
6084 <dd>
6085 <pre>
6086         STRLEN  is_utf8_char(U8 *p)</pre>
6087 </dd>
6088 </li>
6089 <dt><strong><a name="item_is_utf8_string_x_3cis_utf8_string_3e">is_utf8_string
6090 </a></strong>
6091
6092 <dd>
6093 <p>Returns true if first <code>len</code> bytes of the given string form a valid
6094 UTF-8 string, false otherwise.  Note that 'a valid UTF-8 string' does
6095 not mean 'a string that contains code points above 0x7F encoded in UTF-8'
6096 because a valid ASCII string is a valid UTF-8 string.</p>
6097 </dd>
6098 <dd>
6099 <p>See also <code>is_utf8_string_loclen()</code> and is_utf8_string_loc().</p>
6100 </dd>
6101 <dd>
6102 <pre>
6103         bool    is_utf8_string(U8 *s, STRLEN len)</pre>
6104 </dd>
6105 </li>
6106 <dt><strong><a name="item_is_utf8_string_loc_x_3cis_utf8_string_loc_3e">is_utf8_string_loc
6107 </a></strong>
6108
6109 <dd>
6110 <p>Like <code>is_utf8_string()</code> but stores the location of the failure (in the
6111 case of ``utf8ness failure'') or the location s+len (in the case of
6112 ``utf8ness success'') in the <code>ep</code>.</p>
6113 </dd>
6114 <dd>
6115 <p>See also <code>is_utf8_string_loclen()</code> and is_utf8_string().</p>
6116 </dd>
6117 <dd>
6118 <pre>
6119         bool    is_utf8_string_loc(U8 *s, STRLEN len, U8 **p)</pre>
6120 </dd>
6121 </li>
6122 <dt><strong><a name="item_is_utf8_string_loclen_x_3cis_utf8_string_loclen_3e">is_utf8_string_loclen
6123 </a></strong>
6124
6125 <dd>
6126 <p>Like <code>is_utf8_string()</code> but stores the location of the failure (in the
6127 case of ``utf8ness failure'') or the location s+len (in the case of
6128 ``utf8ness success'') in the <code>ep</code>, and the number of UTF-8
6129 encoded characters in the <code>el</code>.</p>
6130 </dd>
6131 <dd>
6132 <p>See also <code>is_utf8_string_loc()</code> and is_utf8_string().</p>
6133 </dd>
6134 <dd>
6135 <pre>
6136         bool    is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)</pre>
6137 </dd>
6138 </li>
6139 <dt><strong><a name="item_pv_uni_display_x_3cpv_uni_display_3e">pv_uni_display
6140 </a></strong>
6141
6142 <dd>
6143 <p>Build to the scalar dsv a displayable version of the string spv,
6144 length len, the displayable version being at most pvlim bytes long
6145 (if longer, the rest is truncated and ``...'' will be appended).</p>
6146 </dd>
6147 <dd>
6148 <p>The flags argument can have UNI_DISPLAY_ISPRINT set to display
6149 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
6150 to display the \\[nrfta\\] as the backslashed versions (like '\n')
6151 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
6152 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
6153 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.</p>
6154 </dd>
6155 <dd>
6156 <p>The pointer to the PV of the dsv is returned.</p>
6157 </dd>
6158 <dd>
6159 <pre>
6160         char*   pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)</pre>
6161 </dd>
6162 </li>
6163 <dt><strong><a name="item_sv_cat_decode_x_3csv_cat_decode_3e">sv_cat_decode
6164 </a></strong>
6165
6166 <dd>
6167 <p>The encoding is assumed to be an Encode object, the PV of the ssv is
6168 assumed to be octets in that encoding and decoding the input starts
6169 from the position which (PV + *offset) pointed to.  The dsv will be
6170 concatenated the decoded UTF-8 string from ssv.  Decoding will terminate
6171 when the string tstr appears in decoding output or the input ends on
6172 the PV of the ssv. The value which the offset points will be modified
6173 to the last input position on the ssv.</p>
6174 </dd>
6175 <dd>
6176 <p>Returns TRUE if the terminator was found, else returns FALSE.</p>
6177 </dd>
6178 <dd>
6179 <pre>
6180         bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)</pre>
6181 </dd>
6182 </li>
6183 <dt><strong><a name="item_sv_recode_to_utf8_x_3csv_recode_to_utf8_3e">sv_recode_to_utf8
6184 </a></strong>
6185
6186 <dd>
6187 <p>The encoding is assumed to be an Encode object, on entry the PV
6188 of the sv is assumed to be octets in that encoding, and the sv
6189 will be converted into Unicode (and UTF-8).</p>
6190 </dd>
6191 <dd>
6192 <p>If the sv already is UTF-8 (or if it is not POK), or if the encoding
6193 is not a reference, nothing is done to the sv.  If the encoding is not
6194 an <code>Encode::XS</code> Encoding object, bad things will happen.
6195 (See <em>lib/encoding.pm</em> and <a href="file://C|\msysgit\mingw\html/lib/Encode.html">the Encode manpage</a>).</p>
6196 </dd>
6197 <dd>
6198 <p>The PV of the sv is returned.</p>
6199 </dd>
6200 <dd>
6201 <pre>
6202         char*   sv_recode_to_utf8(SV* sv, SV *encoding)</pre>
6203 </dd>
6204 </li>
6205 <dt><strong><a name="item_sv_uni_display_x_3csv_uni_display_3e">sv_uni_display
6206 </a></strong>
6207
6208 <dd>
6209 <p>Build to the scalar dsv a displayable version of the scalar sv,
6210 the displayable version being at most pvlim bytes long
6211 (if longer, the rest is truncated and ``...'' will be appended).</p>
6212 </dd>
6213 <dd>
6214 <p>The flags argument is as in pv_uni_display().</p>
6215 </dd>
6216 <dd>
6217 <p>The pointer to the PV of the dsv is returned.</p>
6218 </dd>
6219 <dd>
6220 <pre>
6221         char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)</pre>
6222 </dd>
6223 </li>
6224 <dt><strong><a name="item_to_utf8_case_x_3cto_utf8_case_3e">to_utf8_case
6225 </a></strong>
6226
6227 <dd>
6228 <p>The ``p'' contains the pointer to the UTF-8 string encoding
6229 the character that is being converted.</p>
6230 </dd>
6231 <dd>
6232 <p>The ``ustrp'' is a pointer to the character buffer to put the
6233 conversion result to.  The ``lenp'' is a pointer to the length
6234 of the result.</p>
6235 </dd>
6236 <dd>
6237 <p>The ``swashp'' is a pointer to the swash to use.</p>
6238 </dd>
6239 <dd>
6240 <p>Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
6241 and loaded by SWASHGET, using lib/utf8_heavy.pl.  The special (usually,
6242 but not always, a multicharacter mapping), is tried first.</p>
6243 </dd>
6244 <dd>
6245 <p>The ``special'' is a string like ``utf8::ToSpecLower'', which means the
6246 hash %utf8::ToSpecLower.  The access to the hash is through
6247 Perl_to_utf8_case().</p>
6248 </dd>
6249 <dd>
6250 <p>The ``normal'' is a string like ``ToLower'' which means the swash
6251 %utf8::ToLower.</p>
6252 </dd>
6253 <dd>
6254 <pre>
6255         UV      to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, char *normal, char *special)</pre>
6256 </dd>
6257 </li>
6258 <dt><strong><a name="item_to_utf8_fold_x_3cto_utf8_fold_3e">to_utf8_fold
6259 </a></strong>
6260
6261 <dd>
6262 <p>Convert the UTF-8 encoded character at p to its foldcase version and
6263 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6264 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6265 foldcase version may be longer than the original character (up to
6266 three characters).</p>
6267 </dd>
6268 <dd>
6269 <p>The first character of the foldcased version is returned
6270 (but note, as explained above, that there may be more.)</p>
6271 </dd>
6272 <dd>
6273 <pre>
6274         UV      to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)</pre>
6275 </dd>
6276 </li>
6277 <dt><strong><a name="item_to_utf8_lower_x_3cto_utf8_lower_3e">to_utf8_lower
6278 </a></strong>
6279
6280 <dd>
6281 <p>Convert the UTF-8 encoded character at p to its lowercase version and
6282 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6283 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6284 lowercase version may be longer than the original character.</p>
6285 </dd>
6286 <dd>
6287 <p>The first character of the lowercased version is returned
6288 (but note, as explained above, that there may be more.)</p>
6289 </dd>
6290 <dd>
6291 <pre>
6292         UV      to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)</pre>
6293 </dd>
6294 </li>
6295 <dt><strong><a name="item_to_utf8_title_x_3cto_utf8_title_3e">to_utf8_title
6296 </a></strong>
6297
6298 <dd>
6299 <p>Convert the UTF-8 encoded character at p to its titlecase version and
6300 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6301 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6302 titlecase version may be longer than the original character.</p>
6303 </dd>
6304 <dd>
6305 <p>The first character of the titlecased version is returned
6306 (but note, as explained above, that there may be more.)</p>
6307 </dd>
6308 <dd>
6309 <pre>
6310         UV      to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)</pre>
6311 </dd>
6312 </li>
6313 <dt><strong><a name="item_to_utf8_upper_x_3cto_utf8_upper_3e">to_utf8_upper
6314 </a></strong>
6315
6316 <dd>
6317 <p>Convert the UTF-8 encoded character at p to its uppercase version and
6318 store that in UTF-8 in ustrp and its length in bytes in lenp.  Note
6319 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
6320 the uppercase version may be longer than the original character.</p>
6321 </dd>
6322 <dd>
6323 <p>The first character of the uppercased version is returned
6324 (but note, as explained above, that there may be more.)</p>
6325 </dd>
6326 <dd>
6327 <pre>
6328         UV      to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)</pre>
6329 </dd>
6330 </li>
6331 <dt><strong><a name="item_utf8n_to_uvchr_x_3cutf8n_to_uvchr_3e">utf8n_to_uvchr
6332 </a></strong>
6333
6334 <dd>
6335 <p>Returns the native character value of the first character in the string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a>
6336 which is assumed to be in UTF-8 encoding; <code>retlen</code> will be set to the
6337 length, in bytes, of that character.</p>
6338 </dd>
6339 <dd>
6340 <p>Allows length and flags to be passed to low level routine.</p>
6341 </dd>
6342 <dd>
6343 <pre>
6344         UV      utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)</pre>
6345 </dd>
6346 </li>
6347 <dt><strong><a name="item_utf8n_to_uvuni_x_3cutf8n_to_uvuni_3e">utf8n_to_uvuni
6348 </a></strong>
6349
6350 <dd>
6351 <p>Bottom level UTF-8 decode routine.
6352 Returns the unicode code point value of the first character in the string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a>
6353 which is assumed to be in UTF-8 encoding and no longer than <code>curlen</code>;
6354 <code>retlen</code> will be set to the length, in bytes, of that character.</p>
6355 </dd>
6356 <dd>
6357 <p>If <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> does not point to a well-formed UTF-8 character, the behaviour
6358 is dependent on the value of <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a>: if it contains UTF8_CHECK_ONLY,
6359 it is assumed that the caller will raise a warning, and this function
6360 will silently just set <code>retlen</code> to <code>-1</code> and return zero.  If the
6361 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> does not contain UTF8_CHECK_ONLY, warnings about
6362 malformations will be given, <code>retlen</code> will be set to the expected
6363 length of the UTF-8 character in bytes, and zero will be returned.</p>
6364 </dd>
6365 <dd>
6366 <p>The <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> can also contain various flags to allow deviations from
6367 the strict UTF-8 encoding (see <em>utf8.h</em>).</p>
6368 </dd>
6369 <dd>
6370 <p>Most code should use <code>utf8_to_uvchr()</code> rather than call this directly.</p>
6371 </dd>
6372 <dd>
6373 <pre>
6374         UV      utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)</pre>
6375 </dd>
6376 </li>
6377 <dt><strong><a name="item_utf8_distance_x_3cutf8_distance_3e">utf8_distance
6378 </a></strong>
6379
6380 <dd>
6381 <p>Returns the number of UTF-8 characters between the UTF-8 pointers <code>a</code>
6382 and <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_b"><code>b</code></a>.</p>
6383 </dd>
6384 <dd>
6385 <p>WARNING: use only if you *know* that the pointers point inside the
6386 same UTF-8 buffer.</p>
6387 </dd>
6388 <dd>
6389 <pre>
6390         IV      utf8_distance(U8 *a, U8 *b)</pre>
6391 </dd>
6392 </li>
6393 <dt><strong><a name="item_utf8_hop_x_3cutf8_hop_3e">utf8_hop
6394 </a></strong>
6395
6396 <dd>
6397 <p>Return the UTF-8 pointer <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> displaced by <code>off</code> characters, either
6398 forward or backward.</p>
6399 </dd>
6400 <dd>
6401 <p>WARNING: do not use the following unless you *know* <code>off</code> is within
6402 the UTF-8 data pointed to by <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> *and* that on entry <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> is aligned
6403 on the first byte of character or just after the last byte of a character.</p>
6404 </dd>
6405 <dd>
6406 <pre>
6407         U8*     utf8_hop(U8 *s, I32 off)</pre>
6408 </dd>
6409 </li>
6410 <dt><strong><a name="item_utf8_length_x_3cutf8_length_3e">utf8_length
6411 </a></strong>
6412
6413 <dd>
6414 <p>Return the length of the UTF-8 char encoded string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> in characters.
6415 Stops at <code>e</code> (inclusive).  If <code>e &lt; s</code> or if the scan would end
6416 up past <code>e</code>, croaks.</p>
6417 </dd>
6418 <dd>
6419 <pre>
6420         STRLEN  utf8_length(U8* s, U8 *e)</pre>
6421 </dd>
6422 </li>
6423 <dt><strong><a name="item_utf8_to_bytes_x_3cutf8_to_bytes_3e">utf8_to_bytes
6424 </a></strong>
6425
6426 <dd>
6427 <p>Converts a string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> of length <code>len</code> from UTF-8 into byte encoding.
6428 Unlike <code>bytes_to_utf8</code>, this over-writes the original string, and
6429 updates len to contain the new length.
6430 Returns zero on failure, setting <code>len</code> to -1.</p>
6431 </dd>
6432 <dd>
6433 <p>NOTE: this function is experimental and may change or be
6434 removed without notice.</p>
6435 </dd>
6436 <dd>
6437 <pre>
6438         U8*     utf8_to_bytes(U8 *s, STRLEN *len)</pre>
6439 </dd>
6440 </li>
6441 <dt><strong><a name="item_utf8_to_uvchr_x_3cutf8_to_uvchr_3e">utf8_to_uvchr
6442 </a></strong>
6443
6444 <dd>
6445 <p>Returns the native character value of the first character in the string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a>
6446 which is assumed to be in UTF-8 encoding; <code>retlen</code> will be set to the
6447 length, in bytes, of that character.</p>
6448 </dd>
6449 <dd>
6450 <p>If <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> does not point to a well-formed UTF-8 character, zero is
6451 returned and retlen is set, if possible, to -1.</p>
6452 </dd>
6453 <dd>
6454 <pre>
6455         UV      utf8_to_uvchr(U8 *s, STRLEN *retlen)</pre>
6456 </dd>
6457 </li>
6458 <dt><strong><a name="item_utf8_to_uvuni_x_3cutf8_to_uvuni_3e">utf8_to_uvuni
6459 </a></strong>
6460
6461 <dd>
6462 <p>Returns the Unicode code point of the first character in the string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a>
6463 which is assumed to be in UTF-8 encoding; <code>retlen</code> will be set to the
6464 length, in bytes, of that character.</p>
6465 </dd>
6466 <dd>
6467 <p>This function should only be used when returned UV is considered
6468 an index into the Unicode semantic tables (e.g. swashes).</p>
6469 </dd>
6470 <dd>
6471 <p>If <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_s"><code>s</code></a> does not point to a well-formed UTF-8 character, zero is
6472 returned and retlen is set, if possible, to -1.</p>
6473 </dd>
6474 <dd>
6475 <pre>
6476         UV      utf8_to_uvuni(U8 *s, STRLEN *retlen)</pre>
6477 </dd>
6478 </li>
6479 <dt><strong><a name="item_uvchr_to_utf8_x_3cuvchr_to_utf8_3e">uvchr_to_utf8
6480 </a></strong>
6481
6482 <dd>
6483 <p>Adds the UTF-8 representation of the Native codepoint <code>uv</code> to the end
6484 of the string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_d"><code>d</code></a>; <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_d"><code>d</code></a> should be have at least <code>UTF8_MAXBYTES+1</code> free
6485 bytes available. The return value is the pointer to the byte after the
6486 end of the new character. In other words,</p>
6487 </dd>
6488 <dd>
6489 <pre>
6490     d = uvchr_to_utf8(d, uv);</pre>
6491 </dd>
6492 <dd>
6493 <p>is the recommended wide native character-aware way of saying</p>
6494 </dd>
6495 <dd>
6496 <pre>
6497     *(d++) = uv;</pre>
6498 </dd>
6499 <dd>
6500 <pre>
6501         U8*     uvchr_to_utf8(U8 *d, UV uv)</pre>
6502 </dd>
6503 </li>
6504 <dt><strong><a name="item_uvuni_to_utf8_flags_x_3cuvuni_to_utf8_flags_3e">uvuni_to_utf8_flags
6505 </a></strong>
6506
6507 <dd>
6508 <p>Adds the UTF-8 representation of the Unicode codepoint <code>uv</code> to the end
6509 of the string <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_d"><code>d</code></a>; <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_d"><code>d</code></a> should be have at least <code>UTF8_MAXBYTES+1</code> free
6510 bytes available. The return value is the pointer to the byte after the
6511 end of the new character. In other words,</p>
6512 </dd>
6513 <dd>
6514 <pre>
6515     d = uvuni_to_utf8_flags(d, uv, flags);</pre>
6516 </dd>
6517 <dd>
6518 <p>or, in most cases,</p>
6519 </dd>
6520 <dd>
6521 <pre>
6522     d = uvuni_to_utf8(d, uv);</pre>
6523 </dd>
6524 <dd>
6525 <p>(which is equivalent to)</p>
6526 </dd>
6527 <dd>
6528 <pre>
6529     d = uvuni_to_utf8_flags(d, uv, 0);</pre>
6530 </dd>
6531 <dd>
6532 <p>is the recommended Unicode-aware way of saying</p>
6533 </dd>
6534 <dd>
6535 <pre>
6536     *(d++) = uv;</pre>
6537 </dd>
6538 <dd>
6539 <pre>
6540         U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)</pre>
6541 </dd>
6542 </li>
6543 </dl>
6544 <p>
6545 </p>
6546 <hr />
6547 <h1><a name="variables_created_by_xsubpp_and_xsubpp_internal_functions">Variables created by <code>xsubpp</code> and <code>xsubpp</code> internal functions</a></h1>
6548 <dl>
6549 <dt><strong><a name="item_ax_x_3cax_3e">ax
6550 </a></strong>
6551
6552 <dd>
6553 <p>Variable which is setup by <code>xsubpp</code> to indicate the stack base offset,
6554 used by the <code>ST</code>, <code>XSprePUSH</code> and <code>XSRETURN</code> macros.  The <code>dMARK</code> macro
6555 must be called prior to setup the <code>MARK</code> variable.</p>
6556 </dd>
6557 <dd>
6558 <pre>
6559         I32     ax</pre>
6560 </dd>
6561 </li>
6562 <dt><strong><a name="item_class_x_3cclass_3e">CLASS
6563 </a></strong>
6564
6565 <dd>
6566 <p>Variable which is setup by <code>xsubpp</code> to indicate the
6567 class name for a C++ XS constructor.  This is always a <code>char*</code>.  See <code>THIS</code>.</p>
6568 </dd>
6569 <dd>
6570 <pre>
6571         char*   CLASS</pre>
6572 </dd>
6573 </li>
6574 <dt><strong><a name="item_dax_x_3cdax_3e">dAX
6575 </a></strong>
6576
6577 <dd>
6578 <p>Sets up the <code>ax</code> variable.
6579 This is usually handled automatically by <code>xsubpp</code> by calling <code>dXSARGS</code>.</p>
6580 </dd>
6581 <dd>
6582 <pre>
6583                 dAX;</pre>
6584 </dd>
6585 </li>
6586 <dt><strong><a name="item_daxmark_x_3cdaxmark_3e">dAXMARK
6587 </a></strong>
6588
6589 <dd>
6590 <p>Sets up the <code>ax</code> variable and stack marker variable <code>mark</code>.
6591 This is usually handled automatically by <code>xsubpp</code> by calling <code>dXSARGS</code>.</p>
6592 </dd>
6593 <dd>
6594 <pre>
6595                 dAXMARK;</pre>
6596 </dd>
6597 </li>
6598 <dt><strong><a name="item_ditems_x_3cditems_3e">dITEMS
6599 </a></strong>
6600
6601 <dd>
6602 <p>Sets up the <code>items</code> variable.
6603 This is usually handled automatically by <code>xsubpp</code> by calling <code>dXSARGS</code>.</p>
6604 </dd>
6605 <dd>
6606 <pre>
6607                 dITEMS;</pre>
6608 </dd>
6609 </li>
6610 <dt><strong><a name="item_dxsargs_x_3cdxsargs_3e">dXSARGS
6611 </a></strong>
6612
6613 <dd>
6614 <p>Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
6615 Sets up the <code>ax</code> and <code>items</code> variables by calling <code>dAX</code> and <code>dITEMS</code>.
6616 This is usually handled automatically by <code>xsubpp</code>.</p>
6617 </dd>
6618 <dd>
6619 <pre>
6620                 dXSARGS;</pre>
6621 </dd>
6622 </li>
6623 <dt><strong><a name="item_dxsi32_x_3cdxsi32_3e">dXSI32
6624 </a></strong>
6625
6626 <dd>
6627 <p>Sets up the <code>ix</code> variable for an XSUB which has aliases.  This is usually
6628 handled automatically by <code>xsubpp</code>.</p>
6629 </dd>
6630 <dd>
6631 <pre>
6632                 dXSI32;</pre>
6633 </dd>
6634 </li>
6635 <dt><strong><a name="item_items_x_3citems_3e">items
6636 </a></strong>
6637
6638 <dd>
6639 <p>Variable which is setup by <code>xsubpp</code> to indicate the number of
6640 items on the stack.  See <a href="file://C|\msysgit\mingw\html/pod/perlxs.html#variablelength_parameter_lists">Variable-length Parameter Lists in the perlxs manpage</a>.</p>
6641 </dd>
6642 <dd>
6643 <pre>
6644         I32     items</pre>
6645 </dd>
6646 </li>
6647 <dt><strong><a name="item_ix_x_3cix_3e">ix
6648 </a></strong>
6649
6650 <dd>
6651 <p>Variable which is setup by <code>xsubpp</code> to indicate which of an
6652 XSUB's aliases was used to invoke it.  See <a href="file://C|\msysgit\mingw\html/pod/perlxs.html#the_alias__keyword">The ALIAS: Keyword in the perlxs manpage</a>.</p>
6653 </dd>
6654 <dd>
6655 <pre>
6656         I32     ix</pre>
6657 </dd>
6658 </li>
6659 <dt><strong><a name="item_newxsproto_x_3cnewxsproto_3e">newXSproto
6660 </a></strong>
6661
6662 <dd>
6663 <p>Used by <code>xsubpp</code> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
6664 the subs.</p>
6665 </dd>
6666 </li>
6667 <dt><strong><a name="item_retval_x_3cretval_3e">RETVAL
6668 </a></strong>
6669
6670 <dd>
6671 <p>Variable which is setup by <code>xsubpp</code> to hold the return value for an
6672 XSUB. This is always the proper type for the XSUB. See
6673 <a href="file://C|\msysgit\mingw\html/pod/perlxs.html#the_retval_variable">The RETVAL Variable in the perlxs manpage</a>.</p>
6674 </dd>
6675 <dd>
6676 <pre>
6677         (whatever)      RETVAL</pre>
6678 </dd>
6679 </li>
6680 <dt><strong><a name="item_st_x_3cst_3e">ST
6681 </a></strong>
6682
6683 <dd>
6684 <p>Used to access elements on the XSUB's stack.</p>
6685 </dd>
6686 <dd>
6687 <pre>
6688         SV*     ST(int ix)</pre>
6689 </dd>
6690 </li>
6691 <dt><strong><a name="item_this_x_3cthis_3e">THIS
6692 </a></strong>
6693
6694 <dd>
6695 <p>Variable which is setup by <code>xsubpp</code> to designate the object in a C++
6696 XSUB.  This is always the proper type for the C++ object.  See <code>CLASS</code> and
6697 <a href="file://C|\msysgit\mingw\html/pod/perlxs.html#using_xs_with_c__">Using XS With C++ in the perlxs manpage</a>.</p>
6698 </dd>
6699 <dd>
6700 <pre>
6701         (whatever)      THIS</pre>
6702 </dd>
6703 </li>
6704 <dt><strong><a name="item_xs_x_3cxs_3e">XS
6705 </a></strong>
6706
6707 <dd>
6708 <p>Macro to declare an XSUB and its C parameter list.  This is handled by
6709 <code>xsubpp</code>.</p>
6710 </dd>
6711 </li>
6712 <dt><strong><a name="item_xs_version_x_3cxs_version_3e">XS_VERSION
6713 </a></strong>
6714
6715 <dd>
6716 <p>The version identifier for an XS module.  This is usually
6717 handled automatically by <code>ExtUtils::MakeMaker</code>.  See <code>XS_VERSION_BOOTCHECK</code>.</p>
6718 </dd>
6719 </li>
6720 <dt><strong><a name="item_xs_version_bootcheck_x_3cxs_version_bootcheck_3e">XS_VERSION_BOOTCHECK
6721 </a></strong>
6722
6723 <dd>
6724 <p>Macro to verify that a PM module's $VERSION variable matches the XS
6725 module's <code>XS_VERSION</code> variable.  This is usually handled automatically by
6726 <code>xsubpp</code>.  See <a href="file://C|\msysgit\mingw\html/pod/perlxs.html#the_versioncheck__keyword">The VERSIONCHECK: Keyword in the perlxs manpage</a>.</p>
6727 </dd>
6728 <dd>
6729 <pre>
6730                 XS_VERSION_BOOTCHECK;</pre>
6731 </dd>
6732 </li>
6733 </dl>
6734 <p>
6735 </p>
6736 <hr />
6737 <h1><a name="warning_and_dieing">Warning and Dieing</a></h1>
6738 <dl>
6739 <dt><strong><a name="item_croak_x_3ccroak_3e">croak
6740 </a></strong>
6741
6742 <dd>
6743 <p>This is the XSUB-writer's interface to Perl's <code>die</code> function.
6744 Normally call this function the same way you call the C <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_printf"><code>printf</code></a>
6745 function.  Calling <code>croak</code> returns control directly to Perl,
6746 sidestepping the normal C order of execution. See <code>warn</code>.</p>
6747 </dd>
6748 <dd>
6749 <p>If you want to throw an exception object, assign the object to
6750 <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item___"><code>$@</code></a> and then pass <code>Nullch</code> to croak():</p>
6751 </dd>
6752 <dd>
6753 <pre>
6754    errsv = get_sv(&quot;@&quot;, TRUE);
6755    sv_setsv(errsv, exception_object);
6756    croak(Nullch);</pre>
6757 </dd>
6758 <dd>
6759 <pre>
6760         void    croak(const char* pat, ...)</pre>
6761 </dd>
6762 </li>
6763 <dt><strong><a name="item_warn_x_3cwarn_3e">warn
6764 </a></strong>
6765
6766 <dd>
6767 <p>This is the XSUB-writer's interface to Perl's <code>warn</code> function.  Call this
6768 function the same way you call the C <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_printf"><code>printf</code></a> function.  See <code>croak</code>.</p>
6769 </dd>
6770 <dd>
6771 <pre>
6772         void    warn(const char* pat, ...)</pre>
6773 </dd>
6774 </li>
6775 </dl>
6776 <p>
6777 </p>
6778 <hr />
6779 <h1><a name="authors">AUTHORS</a></h1>
6780 <p>Until May 1997, this document was maintained by Jeff Okamoto
6781 &lt;<a href="mailto:okamoto@corp.hp.com">okamoto@corp.hp.com</a>&gt;.  It is now maintained as part of Perl itself.</p>
6782 <p>With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
6783 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
6784 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
6785 Stephen McCamant, and Gurusamy Sarathy.</p>
6786 <p>API Listing originally by Dean Roehrich &lt;<a href="mailto:roehrich@cray.com">roehrich@cray.com</a>&gt;.</p>
6787 <p>Updated to be autogenerated from comments in the source by Benjamin Stuhl.</p>
6788 <p>
6789 </p>
6790 <hr />
6791 <h1><a name="see_also">SEE ALSO</a></h1>
6792 <p>perlguts(1), perlxs(1), perlxstut(1), <code>perlintern(1)</code></p>
6793 <table border="0" width="100%" cellspacing="0" cellpadding="3">
6794 <tr><td class="block" style="background-color: #cccccc" valign="middle">
6795 <big><strong><span class="block">&nbsp;perlapi - autogenerated documentation for the perl public API</span></strong></big>
6796 </td></tr>
6797 </table>
6798
6799 </body>
6800
6801 </html>