Debian Codegraph @

upstream/mageia-cauldron/man3pm/Internals.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Internals 3pm"
61 .TH Internals 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Internals \- Reserved special namespace for internals related functions
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 4
71 \& $is_ro= Internals::SvREADONLY($x)
72 \& $refcnt= Internals::SvREFCNT($x)
73 \& hv_clear_placeholders(%hash);
74 \& if (Internals::stack_refcounted & 1) { .... }
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 The Internals namespace is used by the core Perl development team to
79 expose certain low level internals routines for testing and other purposes.
80 .PP
81 In theory these routines were not and are not intended to be used outside
82 of the perl core, and are subject to change and removal at any time.
83 .PP
84 In practice people have come to depend on these over the years, despite
85 being historically undocumented, so we will provide some level of
86 forward compatibility for some time. Nevertheless you can assume that any
87 routine documented here is experimental or deprecated and you should find
88 alternatives to their use.
89 .SS FUNCTIONS
90 .IX Subsection "FUNCTIONS"
91 .ie n .IP "SvREFCNT(THING [, $value])" 4
92 .el .IP "SvREFCNT(THING [, \f(CW$value\fR])" 4
93 .IX Item "SvREFCNT(THING [, $value])"
94 Historically Perl has been a refcounted language. This means that each
95 variable tracks how many things reference it, and when the variable is no
96 longer referenced it will automatically free itself. In theory Perl code
97 should not have to care about this, and in a future version Perl might
98 change to some other strategy, although in practice this is unlikely.
99 .Sp
100 This function allows one to violate the abstraction of variables and get
101 or set the refcount of a variable, and in generally is really only useful
102 in code that is testing refcount behavior.
103 .Sp
104 *NOTE* You are strongly discouraged from using this function in non\-test
105 code and especially discouraged from using the set form of this function.
106 The results of doing so may result in segmentation faults or other undefined
107 behavior.
108 .ie n .IP "SvREADONLY(THING, [, $value])" 4
109 .el .IP "SvREADONLY(THING, [, \f(CW$value\fR])" 4
110 .IX Item "SvREADONLY(THING, [, $value])"
111 Set or get whether a variable is readonly or not. Exactly what the
112 readonly flag means depend on the type of the variable affected and the
113 version of perl used.
114 .Sp
115 You are strongly discouraged from using this function directly. It is used
116 by various core modules, like \f(CW\*(C`Hash::Util\*(C'\fR, and the \f(CW\*(C`constant\*(C'\fR pragma
117 to implement higher\-level behavior which should be used instead.
118 .Sp
119 See the core implementation for the exact meaning of the readonly flag for
120 each internal variable type.
121 .IP hv_clear_placeholders(%hash) 4
122 .IX Item "hv_clear_placeholders(%hash)"
123 Clear any placeholders from a locked hash. Should not be used directly.
124 You should use the wrapper functions provided by Hash::Util instead.
125 As of 5.25 also available as \f(CW Hash::Util::_clear_placeholders(%hash) \fR
126 .IP stack_refcounted 4
127 .IX Item "stack_refcounted"
128 Returns an integer indicating whether the perl binary has been configured
129 and built with an argument stack which reference\-counts any items pushed
130 onto it. The value should be treated as flag bits. Currently only bit 0 is
131 used, indicating that \f(CW\*(C`PERL_RC_STACK\*(C'\fR was enabled during the build.
132 .SH AUTHOR
133 .IX Header "AUTHOR"
134 Perl core development team.
135 .SH "SEE ALSO"
136 .IX Header "SEE ALSO"
137 perlguts
138 Hash::Util
139 constant
140 universal.c