This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Evaluate arg once in all forms of SvTRUE
[perl5.git] / pod / perldelta.pod
CommitLineData
0382c61d 1=encoding utf8
7b0fb693 2
0382c61d 3=head1 NAME
7b0fb693 4
d228bb8b
TH
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.33.5
7b0fb693 9
0382c61d 10=head1 DESCRIPTION
7b0fb693 11
d228bb8b 12This document describes differences between the 5.33.4 release and the 5.33.5
0382c61d 13release.
7b0fb693 14
d228bb8b
TH
15If you are upgrading from an earlier release such as 5.33.3, first read
16L<perl5334delta>, which describes differences between 5.33.3 and 5.33.4.
5238875c 17
d228bb8b 18=head1 Notice
8d374562 19
d228bb8b 20XXX Any important notices here
ff9545d6 21
d228bb8b 22=head1 Core Enhancements
ff9545d6 23
d228bb8b
TH
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.
8d374562 27
d228bb8b 28[ List each enhancement as a =head2 entry ]
8d374562 29
d228bb8b 30=head1 Security
8d374562 31
d228bb8b
TH
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.
5b68d8ff 35
d228bb8b 36[ List each security issue as a =head2 entry ]
8d374562 37
d228bb8b 38=head1 Incompatible Changes
8d374562 39
d228bb8b 40XXX For a release on a stable branch, this section aspires to be:
8d374562 41
d228bb8b
TH
42 There are no changes intentionally incompatible with 5.XXX.XXX
43 If any exist, they are bugs, and we request that you submit a
44 report. See L</Reporting Bugs> below.
8d374562 45
d228bb8b 46[ List each incompatible change as a =head2 entry ]
8d374562 47
d228bb8b 48=head1 Deprecations
8d374562 49
d228bb8b 50XXX Any deprecated features, syntax, modules etc. should be listed here.
8d374562 51
d228bb8b 52=head2 Module removals
8d374562 53
d228bb8b 54XXX Remove this section if not applicable.
8d374562 55
d228bb8b
TH
56The following modules will be removed from the core distribution in a
57future release, and will at that time need to be installed from CPAN.
58Distributions on CPAN which require these modules will need to list them as
59prerequisites.
8d374562 60
d228bb8b
TH
61The core versions of these modules will now issue C<"deprecated">-category
62warnings to alert you to this fact. To silence these deprecation warnings,
63install the modules in question from CPAN.
8d374562 64
d228bb8b
TH
65Note that these are (with rare exceptions) fine modules that you are encouraged
66to continue to use. Their disinclusion from core primarily hinges on their
67necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
68not usually on concerns over their design.
5b68d8ff 69
d228bb8b 70=over
8d374562 71
d228bb8b 72=item XXX
8d374562 73
d228bb8b
TH
74XXX Note that deprecated modules should be listed here even if they are listed
75as an updated module in the L</Modules and Pragmata> section.
76
77=back
78
79[ List each other deprecation as a =head2 entry ]
80
81=head1 Performance Enhancements
82
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
8d374562 85
d228bb8b
TH
86[ List each enhancement as an =item entry ]
87
88=over 4
5b68d8ff 89
650a1ca5 90=item *
8d374562 91
d228bb8b
TH
92XXX
93
94=back
95
96=head1 Modules and Pragmata
97
98XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
99go here. If Module::CoreList is updated, generate an initial draft of the
100following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
101for important changes should then be added by hand. In an ideal world,
102dual-life modules would have a F<Changes> file that could be cribbed.
103
104The list of new and updated modules is modified automatically as part of
105preparing a Perl release, so the only reason to manually add entries here is if
106you're summarising the important changes in the module update. (Also, if the
107manually-added details don't match the automatically-generated ones, the
108release manager will have to investigate the situation carefully.)
109
110[ Within each section, list entries as an =item entry ]
111
112=head2 New Modules and Pragmata
113
114=over 4
8d374562
SH
115
116=item *
117
d228bb8b
TH
118XXX Remove this section if not applicable.
119
120=back
121
122=head2 Updated Modules and Pragmata
123
124=over 4
8d374562 125
650a1ca5 126=item *
8d374562 127
d228bb8b
TH
128L<XXX> has been upgraded from version A.xx to B.yy.
129
130If there was something important to note about this change, include that here.
131
132=back
133
134=head2 Removed Modules and Pragmata
135
136=over 4
8d374562
SH
137
138=item *
139
d228bb8b 140XXX
8d374562 141
5b68d8ff 142=back
8d374562 143
5b68d8ff 144=head1 Documentation
8d374562 145
d228bb8b
TH
146XXX Changes to files in F<pod/> go here. Consider grouping entries by
147file and be sure to link to the appropriate page, e.g. L<perlfunc>.
148
149=head2 New Documentation
150
151XXX Changes which create B<new> files in F<pod/> go here.
152
153=head3 L<XXX>
154
155XXX Description of the purpose of the new file here
156
5b68d8ff 157=head2 Changes to Existing Documentation
4309bda4 158
5b68d8ff
SH
159We have attempted to update the documentation to reflect the changes
160listed in this document. If you find any we have missed, open an issue
161at L<https://github.com/Perl/perl5/issues>.
4309bda4 162
d228bb8b
TH
163XXX Changes which significantly change existing files in F<pod/> go here.
164However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
165section.
166
167Additionally, the following selected changes have been made:
168
8dc9a321 169=head3 L<perlfunc>
650a1ca5
TH
170
171=over 4
172
173=item *
174
8dc9a321
TC
175L<msgsnd()|perlfunc/msgsnd> documented a length field included in the
176packed C<MSG> parameter to msgsnd(), but there was no such field.
177C<MSG> contains only the type and the message content.
4309bda4 178
650a1ca5 179=back
5b68d8ff 180
d228bb8b
TH
181=head1 Diagnostics
182
183The following additions or changes have been made to diagnostic output,
184including warnings and fatal error messages. For the complete list of
185diagnostic messages, see L<perldiag>.
186
187XXX New or changed warnings emitted by the core's C<C> code go here. Also
188include any changes in L<perldiag> that reconcile it to the C<C> code.
189
190=head2 New Diagnostics
191
192XXX Newly added diagnostic messages go under here, separated into New Errors
193and New Warnings
194
195=head3 New Errors
4309bda4 196
5b68d8ff 197=over 4
4309bda4
S
198
199=item *
200
d228bb8b 201XXX L<message|perldiag/"message">
8d374562 202
5b68d8ff 203=back
8d374562 204
d228bb8b 205=head3 New Warnings
8d374562 206
d228bb8b
TH
207=over 4
208
209=item *
210
211XXX L<message|perldiag/"message">
212
213=back
8d374562 214
5b68d8ff 215=head2 Changes to Existing Diagnostics
8d374562 216
d228bb8b
TH
217XXX Changes (i.e. rewording) of diagnostic messages go here
218
5b68d8ff 219=over 4
8d374562
SH
220
221=item *
222
d228bb8b
TH
223XXX Describe change here
224
225=back
226
227=head1 Utility Changes
228
229XXX Changes to installed programs such as F<perldoc> and F<xsubpp> go here.
230Most of these are built within the directory F<utils>.
231
232[ List utility changes as a =head2 entry for each utility and =item
233entries for each change
234Use L<XXX> with program names to get proper documentation linking. ]
a473ef8b 235
d228bb8b
TH
236=head2 L<XXX>
237
238=over 4
239
240=item *
241
242XXX
243
244=back
245
246=head1 Configuration and Compilation
247
248XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
249go here. Any other changes to the Perl build process should be listed here.
250However, any platform-specific changes should be listed in the
251L</Platform Support> section, instead.
252
253[ List changes as an =item entry ].
254
255=over 4
256
257=item *
258
259XXX
260
261=back
262
263=head1 Testing
264
265XXX Any significant changes to the testing of a freshly built perl should be
266listed here. Changes which create B<new> files in F<t/> go here as do any
267large changes to the testing harness (e.g. when parallel testing was added).
268Changes to existing files in F<t/> aren't worth summarizing, although the bugs
269that they represent may be covered elsewhere.
270
271XXX If there were no significant test changes, say this:
272
273Tests were added and changed to reflect the other additions and changes
274in this release.
275
276XXX If instead there were significant changes, say this:
277
278Tests were added and changed to reflect the other additions and
279changes in this release. Furthermore, these significant changes were
280made:
281
282[ List each test improvement as an =item entry ]
283
284=over 4
285
286=item *
287
730797bb
KW
288When testing in parallel on many-core platforms, you can now cause the
289test suite to finish somewhat earlier, but with less logical ordering of
290the tests, by setting
291
292 PERL_TEST_HARNESS_ASAP=1
293
294while running the test suite.
e6b76f1d 295
5b68d8ff 296=back
e6b76f1d 297
5b68d8ff 298=head1 Platform Support
e6b76f1d 299
d228bb8b
TH
300XXX Any changes to platform support should be listed in the sections below.
301
302[ Within the sections, list each platform as an =item entry with specific
303changes as paragraphs below it. ]
304
305=head2 New Platforms
306
307XXX List any platforms that this version of perl compiles on, that previous
308versions did not. These will either be enabled by new files in the F<hints/>
309directories, or new subdirectories and F<README> files at the top level of the
310source tree.
311
312=over 4
313
314=item XXX-some-platform
315
316XXX
317
318=back
319
320=head2 Discontinued Platforms
321
322XXX List any platforms that this version of perl no longer compiles on.
323
324=over 4
325
326=item XXX-some-platform
327
328XXX
329
330=back
331
f460daa0
S
332=head2 Platform-Specific Notes
333
d228bb8b
TH
334XXX List any changes for specific platforms. This could include configuration
335and compilation changes or changes in portability/compatibility. However,
336changes within modules for platforms should generally be listed in the
337L</Modules and Pragmata> section.
338
5b68d8ff 339=over 4
f460daa0 340
7de4500e
TC
341=item Windows
342
343Windows now supports L<symlink()|perlfunc/symlink> and
344L<readlink()|perlfunc/readlink>, and L<lstat()|perlfunc/lstat> is no
345longer an alias for L<stat()|perlfunc/stat>.
346L<[#18005]|https://github.com/Perl/perl5/issues/18005>.
347
348Unlike POSIX systems, creating a symbolic link on Windows requires
349either elevated privileges or Windows 10 1703 or later with Developer
350Mode enabled.
351
352stat(), including C<stat FILEHANDLE>, and lstat() now uses our own
353implementation that populates the device C<dev> and inode numbers
354C<ino> returned rather than always returning zero. The number of
355links C<nlink> field is now always populated.
356
357L<< C<${^WIN32_SLOPPY_STAT}> |perlvar/${^WIN32_SLOPPY_STAT} >> previously
358controlled whether the C<nlink> field was populated requiring a
359separate Windows API call to fetch, since nlink and the other
360information required for stat() is now retrieved in a single API call.
361
362The C<-r> and C<-w> operators now return true for the C<STDIN>,
363C<STDOUT> and C<STDERR> handles. Unfortunately it still won't return
364true for duplicates of those handles.
365L<[#8502]|https://github.com/Perl/perl5/issues/8502>.
366
367The times returned by stat() and lstat() are no longer incorrect
368across Daylight Savings Time adjustments.
369L<[#6080]|https://github.com/Perl/perl5/issues/6080>.
370
371C<-x> on a filehandle should now match C<-x> on the corresponding
372filename on Vista or later.
373L<[#4145]|https://github.com/Perl/perl5/issues/4145>.
374
375C<-e '"'> no longer incorrectly returns true.
376L<[#12431]|https://github.com/Perl/perl5/issues/12431>.
d228bb8b
TH
377
378=back
379
380=head1 Internal Changes
381
382XXX Changes which affect the interface available to C<XS> code go here. Other
383significant internal changes for future core maintainers should be noted as
384well.
385
386[ List each change as an =item entry ]
387
388=over 4
389
390=item *
391
4eff5eb8
KW
392All C<SvTRUE>-ish functions now evaluate their arguments exactly once.
393In 5.32, plain L<perlapi/C<SvTRUE>> was changed to do that; now the rest
394do as well.
e6b76f1d
SH
395
396=back
397
f460daa0
S
398=head1 Selected Bug Fixes
399
d228bb8b
TH
400XXX Important bug fixes in the core language are summarized here. Bug fixes in
401files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
402
403[ List each fix as an =item entry ]
404
2c101fc0
S
405=over 4
406
f460daa0
S
407=item *
408
8dc9a321
TC
409L<semctl()|perlfunc/semctl>, L<msgctl()|perlfunc/msgctl>, and
410L<shmctl()|perlfunc/shmctl> now properly reset the UTF-8 flag on the
411C<ARG> parameter if it's modified for C<IPC_STAT> or C<GETALL>
412operations.
413
414=item *
415
416semctl(), msgctl(), and shmctl() now attempt to downgrade the C<ARG>
417parameter if it's value is being used as input to C<IPC_SET> or
418C<SETALL> calls. A failed downgrade will thrown an exception.
419
420=item *
421
422In cases where semctl(), msgctl() or shmctl() would treat the C<ARG>
423parameter as a pointer, an undefined value no longer generates a
424warning. In most such calls the pointer isn't used anyway and this
425allows you to supply C<undef> for a value not used by the underlying
426function.
427
428=item *
429
430L<semop()|perlfunc/semop> now downgrades the C<OPSTRING> parameter,
431L<msgsnd()|perlfunc/msgsnd> now downgrades the C<MSG> parameter and
432L<shmwrite|perlfunc/shmwrite> now downgrades the C<STRING> parameter
433to treat them as bytes. Previously they would be left upgraded,
434providing a corrupted structure to the underlying function call.
435
436=item *
437
438L<msgrcv()|perlfunc/msgrcv> now properly resets the UTF-8 flag the
439C<VAR> parameter when it is modified. Previusly the UTF-8 flag could
440be left on, resulting in a possibly corrupt result in C<VAR>.
d228bb8b
TH
441
442=back
443
444=head1 Known Problems
445
446XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
447tests that had to be C<TODO>ed for the release would be noted here. Unfixed
448platform specific bugs also go here.
449
450[ List each fix as an =item entry ]
451
452=over 4
a473ef8b
TC
453
454=item *
455
d228bb8b 456XXX
5b68d8ff
SH
457
458=back
e6b76f1d 459
d228bb8b 460=head1 Errata From Previous Releases
ff9545d6 461
d228bb8b 462=over 4
ff9545d6 463
d228bb8b 464=item *
ff9545d6 465
d228bb8b
TH
466XXX Add anything here that we forgot to add, or were mistaken about, in
467the perldelta of a previous release.
5b68d8ff 468
d228bb8b
TH
469=back
470
471=head1 Obituary
5b68d8ff 472
d228bb8b
TH
473XXX If any significant core contributor or member of the CPAN community has
474died, add a short obituary here.
475
476=head1 Acknowledgements
ff9545d6 477
d228bb8b 478XXX Generate this with:
0382c61d 479
d228bb8b 480 perl Porting/acknowledgements.pl v5.33.4..HEAD
8424e368 481
44691e6f
AB
482=head1 Reporting Bugs
483
5b68d8ff
SH
484If you find what you think is a bug, you might check the perl bug database
485at L<https://github.com/Perl/perl5/issues>. There may also be information at
46a21c0a 486L<http://www.perl.org/>, the Perl Home Page.
44691e6f 487
8166b4e0 488If you believe you have an unreported bug, please open an issue at
0382c61d 489L<https://github.com/Perl/perl5/issues>. Be sure to trim your bug down to a
8166b4e0 490tiny but sufficient test case.
44691e6f 491
87c118b9 492If the bug you are reporting has security implications which make it
8166b4e0 493inappropriate to send to a public issue tracker, then see
5b68d8ff
SH
494L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
495for details of how to report the issue.
44691e6f 496
390ae6f9
S
497=head1 Give Thanks
498
5b68d8ff
SH
499If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
500you can do so by running the C<perlthanks> program:
390ae6f9
S
501
502 perlthanks
503
504This will send an email to the Perl 5 Porters list with your show of thanks.
505
44691e6f
AB
506=head1 SEE ALSO
507
e08634c5
SH
508The F<Changes> file for an explanation of how to view exhaustive details on
509what changed.
44691e6f
AB
510
511The F<INSTALL> file for how to build Perl.
512
513The F<README> file for general stuff.
514
515The F<Artistic> and F<Copying> files for copyright information.
516
517=cut