This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta: Blanket entry for memory leaks
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
e14ac59b
RS
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.17.7
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
e14ac59b 12This document describes differences between the 5.17.6 release and the 5.17.7
e08634c5 13release.
6db9054f 14
e14ac59b
RS
15If you are upgrading from an earlier release such as 5.17.5, first read
16L<perl5176delta>, which describes differences between 5.17.5 and 5.17.6.
17
18=head1 Notice
19
20XXX Any important notices here
5faa50e9 21
5d8c8c8a 22=head1 Core Enhancements
4db91b87 23
e14ac59b
RS
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
bde9e88d 27
e14ac59b 28[ List each enhancement as a =head2 entry ]
bde9e88d 29
e14ac59b 30=head1 Security
86148eee 31
e14ac59b
RS
32XXX Any security-related notices go here. In particular, any security
33vulnerabilities closed should be noted here rather than in the
34L</Selected Bug Fixes> section.
86148eee 35
e14ac59b 36[ List each security issue as a =head2 entry ]
9c5f5e7a 37
e14ac59b 38=head1 Incompatible Changes
90249f0a 39
3ef6ec90
TC
40=head2 readline() with C<$/ = \N> now reads N characters, not N bytes
41
42Previously, when reading from a stream with I/O layers such as
43C<encoding>, the readline() function, otherwise known as the C<< <> >>
44operator, would read I<N> bytes from the top-most layer. [perl #79960]
45
46Now, I<N> characters are read instead.
47
48There is no change in behaviour when reading from streams with no
49extra layers, since bytes map exactly to characters.
50
e14ac59b 51XXX For a release on a stable branch, this section aspires to be:
90249f0a 52
e14ac59b
RS
53 There are no changes intentionally incompatible with 5.XXX.XXX
54 If any exist, they are bugs, and we request that you submit a
55 report. See L</Reporting Bugs> below.
4d7cd482 56
e14ac59b 57[ List each incompatible change as a =head2 entry ]
4d7cd482 58
e14ac59b 59=head1 Deprecations
4d7cd482 60
e14ac59b
RS
61XXX Any deprecated features, syntax, modules etc. should be listed here. In
62particular, deprecated modules should be listed here even if they are listed as
63an updated module in the L</Modules and Pragmata> section.
4d7cd482 64
e14ac59b 65[ List each deprecation as a =head2 entry ]
86148eee 66
61b19385
KW
67=head2 Various XS-callable functions are now deprecated
68
69The following functions will be removed from a future version of Perl,
70and should not be used. With participating C compilers (e.g., gcc),
71compiling any file that uses any of these will generate a warning.
72These were not intended for public use; there are equivalent, faster,
73macros for most of them. See L<perlapi/Character classes>:
74C<is_uni_ascii>,
75C<is_uni_ascii_lc>,
76C<is_uni_blank>,
77C<is_uni_blank_lc>,
78C<is_uni_cntrl>,
79C<is_uni_cntrl_lc>,
80C<is_uni_idfirst_lc>,
81C<is_uni_space>,
82C<is_uni_space_lc>,
83C<is_uni_xdigit>,
84C<is_uni_xdigit_lc>,
85C<is_utf8_ascii>,
86C<is_utf8_blank>,
87C<is_utf8_cntrl>,
88C<is_utf8_idcont>,
89C<is_utf8_idfirst>,
90C<is_utf8_perl_space>,
91C<is_utf8_perl_word>,
92C<is_utf8_posix_digit>,
93C<is_utf8_space>,
94C<is_utf8_xdigit>.
95C<is_utf8_xidcont>,
96C<is_utf8_xidfirst>,
97C<to_uni_lower_lc>,
98C<to_uni_title_lc>,
99and
100C<to_uni_upper_lc>.
101
e14ac59b 102=head1 Performance Enhancements
86148eee 103
e14ac59b
RS
104XXX Changes which enhance performance without changing behaviour go here.
105There may well be none in a stable release.
86148eee 106
e14ac59b 107[ List each enhancement as a =item entry ]
1611045a 108
e14ac59b 109=over 4
7a7a10c7 110
e14ac59b 111=item *
7a7a10c7 112
e14ac59b 113XXX
7a7a10c7 114
e14ac59b 115=back
7a7a10c7 116
e14ac59b 117=head1 Modules and Pragmata
7a7a10c7 118
e14ac59b
RS
119XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
120go here. If Module::CoreList is updated, generate an initial draft of the
121following sections using F<Porting/corelist-perldelta.pl>, which prints stub
122entries to STDOUT. Results can be pasted in place of the '=head2' entries
123below. A paragraph summary for important changes should then be added by hand.
124In an ideal world, dual-life modules would have a F<Changes> file that could be
125cribbed.
7a7a10c7 126
e14ac59b 127[ Within each section, list entries as a =item entry ]
7a7a10c7 128
e14ac59b 129=head2 New Modules and Pragmata
45f11e9c 130
916c45d9 131=over 4
338a1057
SH
132
133=item *
134
e14ac59b 135XXX
0ace302a 136
e14ac59b 137=back
32209f41 138
e14ac59b 139=head2 Updated Modules and Pragmata
c387386a 140
e14ac59b 141=over 4
32209f41 142
e14ac59b 143=item *
5faa50e9 144
476161f6
NC
145L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
146optional fifth parameter to C<TIEHASH> has been removed. This was intended
147to provide control of the callback used by C<gdbm*> functions in case of
148fatal errors (such as filesystem problems), but did not work (and could
149never have worked). No code on CPAN even attempted to use it. The callback
150is now always the previous default, C<croak>. Problems on some platforms with
151how the C<C> C<croak> function is called have also been resolved.
5faa50e9 152
e14ac59b
RS
153=back
154
155=head2 Removed Modules and Pragmata
4cc02608 156
916c45d9 157=over 4
e7b92d54
SH
158
159=item *
160
e14ac59b 161XXX
11e375e0 162
e14ac59b 163=back
11e375e0 164
e14ac59b 165=head1 Documentation
11e375e0 166
e14ac59b
RS
167XXX Changes to files in F<pod/> go here. Consider grouping entries by
168file and be sure to link to the appropriate page, e.g. L<perlfunc>.
7b379596 169
e14ac59b 170=head2 New Documentation
5c26a176 171
e14ac59b 172XXX Changes which create B<new> files in F<pod/> go here.
5c26a176 173
e14ac59b 174=head3 L<XXX>
cb077ed2 175
e14ac59b 176XXX Description of the purpose of the new file here
11e375e0 177
e14ac59b 178=head2 Changes to Existing Documentation
11e375e0 179
e14ac59b
RS
180XXX Changes which significantly change existing files in F<pod/> go here.
181However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
182section.
183
243effed 184=head3 L<perlapi/Character classes>
11e375e0 185
e14ac59b 186=over 4
e498bd59
RS
187
188=item *
189
243effed
KW
190There are quite a few macros callable from XS modules that classify
191characters into things like alphabetic, punctuation, etc. More of these
192are now documented, including ones which work on characters whose code
193points are outside the Latin-1 range.
cb077ed2 194
5d8c8c8a 195=back
5f877a7f 196
e14ac59b
RS
197=head1 Diagnostics
198
199The following additions or changes have been made to diagnostic output,
200including warnings and fatal error messages. For the complete list of
201diagnostic messages, see L<perldiag>.
1ea91bbe 202
e14ac59b
RS
203XXX New or changed warnings emitted by the core's C<C> code go here. Also
204include any changes in L<perldiag> that reconcile it to the C<C> code.
205
206=head2 New Diagnostics
207
208XXX Newly added diagnostic messages go under here, separated into New Errors
209and New Warnings
210
211=head3 New Errors
5faa50e9 212
5d8c8c8a 213=over 4
1ea91bbe
FR
214
215=item *
216
e14ac59b 217XXX L<message|perldiag/"message">
5faa50e9 218
916c45d9 219=back
9c5f5e7a 220
e14ac59b 221=head3 New Warnings
4db91b87 222
5d8c8c8a 223=over 4
4db91b87 224
e14ac59b 225=item *
4db91b87 226
e14ac59b 227XXX L<message|perldiag/"message">
4db91b87 228
5d8c8c8a 229=back
5faa50e9 230
e14ac59b
RS
231=head2 Changes to Existing Diagnostics
232
233XXX Changes (i.e. rewording) of diagnostic messages go here
5faa50e9 234
5d8c8c8a 235=over 4
5faa50e9 236
e14ac59b 237=item *
ddb1bef5 238
e14ac59b 239XXX Describe change here
ddb1bef5 240
e14ac59b 241=back
5faa50e9 242
e14ac59b 243=head1 Utility Changes
5faa50e9 244
e14ac59b
RS
245XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
246Most of these are built within the directories F<utils> and F<x2p>.
5faa50e9 247
e14ac59b
RS
248[ List utility changes as a =head3 entry for each utility and =item
249entries for each change
250Use L<XXX> with program names to get proper documentation linking. ]
251
252=head3 L<XXX>
5faa50e9 253
5d8c8c8a 254=over 4
5faa50e9
FR
255
256=item *
257
e14ac59b 258XXX
cb077ed2 259
e14ac59b
RS
260=back
261
262=head1 Configuration and Compilation
263
264XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
265go here. Any other changes to the Perl build process should be listed here.
266However, any platform-specific changes should be listed in the
267L</Platform Support> section, instead.
cb077ed2 268
e14ac59b
RS
269[ List changes as a =item entry ].
270
271=over 4
90814a4e 272
5ce83ae9
DM
273=item *
274
e14ac59b 275XXX
5ce83ae9 276
5d8c8c8a 277=back
31c15ce5 278
e14ac59b
RS
279=head1 Testing
280
281XXX Any significant changes to the testing of a freshly built perl should be
282listed here. Changes which create B<new> files in F<t/> go here as do any
283large changes to the testing harness (e.g. when parallel testing was added).
284Changes to existing files in F<t/> aren't worth summarizing, although the bugs
285that they represent may be covered elsewhere.
286
287[ List each test improvement as a =item entry ]
4db91b87 288
5d8c8c8a 289=over 4
4db91b87
FC
290
291=item *
292
e14ac59b 293XXX
11e375e0 294
e14ac59b 295=back
11e375e0 296
e14ac59b 297=head1 Platform Support
11e375e0 298
e14ac59b 299XXX Any changes to platform support should be listed in the sections below.
11e375e0 300
e14ac59b
RS
301[ Within the sections, list each platform as a =item entry with specific
302changes as paragraphs below it. ]
11e375e0 303
e14ac59b 304=head2 New Platforms
11e375e0 305
e14ac59b
RS
306XXX List any platforms that this version of perl compiles on, that previous
307versions did not. These will either be enabled by new files in the F<hints/>
308directories, or new subdirectories and F<README> files at the top level of the
309source tree.
11e375e0 310
e14ac59b 311=over 4
11e375e0 312
e14ac59b 313=item XXX-some-platform
11e375e0 314
e14ac59b 315XXX
11e375e0 316
e14ac59b 317=back
11e375e0 318
e14ac59b 319=head2 Discontinued Platforms
11e375e0 320
e14ac59b 321=over 4
11e375e0 322
b6c36746 323=item BeOS
11e375e0 324
b6c36746 325Support for BeOS has been removed.
11e375e0 326
e14ac59b 327=back
11e375e0 328
e14ac59b 329=head2 Platform-Specific Notes
11e375e0 330
e14ac59b
RS
331XXX List any changes for specific platforms. This could include configuration
332and compilation changes or changes in portability/compatibility. However,
333changes within modules for platforms should generally be listed in the
334L</Modules and Pragmata> section.
11e375e0 335
e14ac59b 336=over 4
11e375e0 337
e14ac59b 338=item XXX-some-platform
11e375e0 339
e14ac59b 340XXX
11e375e0 341
e14ac59b 342=back
11e375e0 343
e14ac59b 344=head1 Internal Changes
11e375e0 345
e14ac59b
RS
346XXX Changes which affect the interface available to C<XS> code go here. Other
347significant internal changes for future core maintainers should be noted as
348well.
11e375e0 349
e14ac59b 350[ List each change as a =item entry ]
11e375e0 351
e14ac59b 352=over 4
11e375e0
FC
353
354=item *
355
463ea229
DM
356SvUPGRADE() is no longer an expression. Originally this macro (and its
357underlying function, sv_upgrade()) were documented as boolean, although
358in reality they always croaked on error and never returned false. In 2005
359the documentation was updated to specify a void return value, but
360SvUPGRADE() was left always returning 1 for backwards compatibility. This
361has now been removed, and SvUPGRADE() is now a statement with no return
362value.
363
364So this is now a syntax error:
365
366 if (!SvUPGRADE(sv)) { croak(...); }
367
368If you have code like that, simply replace it with
369
370 SvUPGRADE(sv);
e14ac59b 371
8b877d20
DM
372or to to avoid compiler warnings with older perls, possibly
373
374 (void)SvUPGRADE(sv);
375
e14ac59b
RS
376=back
377
378=head1 Selected Bug Fixes
379
380XXX Important bug fixes in the core language are summarized here. Bug fixes in
381files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
382
383[ List each fix as a =item entry ]
384
385=over 4
11e375e0
FC
386
387=item *
388
8b998a90
FC
389C<sort {undef} ...> under fatal warnings no longer crashes. It started
390crashing in Perl 5.16.
e14ac59b 391
fdea6f98
FC
392=item *
393
394Stashes blessed into each other
395(C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
396frees. This bug started happening in Perl 5.16.
397
7cf3104f
FC
398=item *
399
400Numerous memory leaks have been fixed, mostly involving fatal warnings and
401syntax errors.
402
e14ac59b
RS
403=back
404
405=head1 Known Problems
406
407XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
408tests that had to be C<TODO>ed for the release would be noted here. Unfixed
409platform specific bugs also go here.
410
411[ List each fix as a =item entry ]
412
413=over 4
2d9cd31f 414
c9ac5216
FC
415=item *
416
e14ac59b 417XXX
c9ac5216 418
5d8c8c8a 419=back
4db91b87 420
e14ac59b
RS
421=head1 Obituary
422
423XXX If any significant core contributor has died, we've added a short obituary
424here.
425
916c45d9 426=head1 Acknowledgements
05bee12a 427
e14ac59b
RS
428XXX Generate this with:
429
430 perl Porting/acknowledgements.pl v5.17.6..HEAD
29cf780c 431
44691e6f
AB
432=head1 Reporting Bugs
433
e08634c5
SH
434If you find what you think is a bug, you might check the articles recently
435posted to the comp.lang.perl.misc newsgroup and the perl bug database at
436http://rt.perl.org/perlbug/ . There may also be information at
437http://www.perl.org/ , the Perl Home Page.
44691e6f 438
e08634c5
SH
439If you believe you have an unreported bug, please run the L<perlbug> program
440included with your release. Be sure to trim your bug down to a tiny but
441sufficient test case. Your bug report, along with the output of C<perl -V>,
442will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
443
444If the bug you are reporting has security implications, which make it
e08634c5
SH
445inappropriate to send to a publicly archived mailing list, then please send it
446to perl5-security-report@perl.org. This points to a closed subscription
447unarchived mailing list, which includes all the core committers, who will be
448able to help assess the impact of issues, figure out a resolution, and help
f9001595 449co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
450platforms on which Perl is supported. Please only use this address for
451security issues in the Perl core, not for modules independently distributed on
452CPAN.
44691e6f
AB
453
454=head1 SEE ALSO
455
e08634c5
SH
456The F<Changes> file for an explanation of how to view exhaustive details on
457what changed.
44691e6f
AB
458
459The F<INSTALL> file for how to build Perl.
460
461The F<README> file for general stuff.
462
463The F<Artistic> and F<Copying> files for copyright information.
464
465=cut