Make fileno() builtin work on directory handles
[perl.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
6 to be processed before release. ]
7
8 perldelta - what is new for perl v5.21.7
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.21.6 release and the 5.21.7
13 release.
14
15 If you are upgrading from an earlier release such as 5.21.5, first read
16 L<perl5216delta>, which describes differences between 5.21.5 and 5.21.6.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 [ List each enhancement as a =head2 entry ]
29
30 =head2 C<fileno> now works on directory handles
31
32 When the relevant support is available in the operating system, the
33 C<fileno> builtin now works on directory handles, yielding the
34 underlying file descriptor in the same way as for filehandles. On
35 operating systems without such support, C<fileno> on a directory handle
36 continues to return the undefined value, as before, but also sets C<$!> to
37 indicate that the operation is not supported.
38
39 Currently, this uses either a C<dd_fd> member in the OS C<DIR>
40 structure, or a dirfd(3) function as specified by POSIX.1-2008.
41
42 =head1 Security
43
44 XXX Any security-related notices go here.  In particular, any security
45 vulnerabilities closed should be noted here rather than in the
46 L</Selected Bug Fixes> section.
47
48 [ List each security issue as a =head2 entry ]
49
50 =head1 Incompatible Changes
51
52 XXX For a release on a stable branch, this section aspires to be:
53
54     There are no changes intentionally incompatible with 5.XXX.XXX
55     If any exist, they are bugs, and we request that you submit a
56     report.  See L</Reporting Bugs> below.
57
58 [ List each incompatible change as a =head2 entry ]
59
60 =head1 Deprecations
61
62 XXX Any deprecated features, syntax, modules etc. should be listed here.
63
64 =head2 Module removals
65
66 XXX Remove this section if inapplicable.
67
68 The following modules will be removed from the core distribution in a
69 future release, and will at that time need to be installed from CPAN.
70 Distributions on CPAN which require these modules will need to list them as
71 prerequisites.
72
73 The core versions of these modules will now issue C<"deprecated">-category
74 warnings to alert you to this fact.  To silence these deprecation warnings,
75 install the modules in question from CPAN.
76
77 Note that these are (with rare exceptions) fine modules that you are encouraged
78 to continue to use.  Their disinclusion from core primarily hinges on their
79 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
80 not usually on concerns over their design.
81
82 =over
83
84 =item XXX
85
86 XXX Note that deprecated modules should be listed here even if they are listed
87 as an updated module in the L</Modules and Pragmata> section.
88
89 =back
90
91 [ List each other deprecation as a =head2 entry ]
92
93 =head2 Setting C<${^ENCODING}> to anything but C<undef>
94
95 This variable allows Perl scripts to be written in a non-ASCII,
96 non-UTF-8 encoding.  However, it affects all modules globally, leading
97 to wrong answers and segmentation faults.  New scripts should be written
98 in UTF-8; old scripts should be converted to UTF-8, which is easily done
99 with the L<encoding> pragma.
100
101 =head1 Performance Enhancements
102
103 XXX Changes which enhance performance without changing behaviour go here.
104 There may well be none in a stable release.
105
106 [ List each enhancement as a =item entry ]
107
108 =over 4
109
110 =item *
111
112 XXX
113
114 =back
115
116 =head1 Modules and Pragmata
117
118 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
119 go here.  If Module::CoreList is updated, generate an initial draft of the
120 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
121 for important changes should then be added by hand.  In an ideal world,
122 dual-life modules would have a F<Changes> file that could be cribbed.
123
124 [ Within each section, list entries as a =item entry ]
125
126 =head2 New Modules and Pragmata
127
128 =over 4
129
130 =item *
131
132 XXX
133
134 =back
135
136 =head2 Updated Modules and Pragmata
137
138 =over 4
139
140 =item *
141
142 L<ExtUtils::ParseXS> has been upgraded from version 3.26 to 3.27.
143
144 Only declare C<file> unused if we actually define it.
145
146 Improve generated C<RETVAL> code generation to avoid repeated
147 references to C<ST(0)>.  [perl #123278]
148
149 =item *
150
151 The PathTools module collection has been upgraded from 3.52 to 3.53.
152
153 Don't turn leading C<//> into C</> on Cygwin. [perl #122635]
154
155 =item *
156
157 L<Locale::Maketext> has been upgraded from version 1.25 to 1.26.
158
159 =item *
160
161 L<XSLoader> has been upgraded from version 0.19 to 0.20
162
163 Don't test twice for bootstrap file.
164
165 =back
166
167 =head2 Removed Modules and Pragmata
168
169 =over 4
170
171 =item *
172
173 XXX
174
175 =back
176
177 =head1 Documentation
178
179 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
180 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
181
182 =head2 New Documentation
183
184 XXX Changes which create B<new> files in F<pod/> go here.
185
186 =head3 L<XXX>
187
188 XXX Description of the purpose of the new file here
189
190 =head2 Changes to Existing Documentation
191
192 XXX Changes which significantly change existing files in F<pod/> go here.
193 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
194 section.
195
196 =head3 L<XXX>
197
198 =over 4
199
200 =item *
201
202 XXX Description of the change here
203
204 =back
205
206 =head1 Diagnostics
207
208 The following additions or changes have been made to diagnostic output,
209 including warnings and fatal error messages.  For the complete list of
210 diagnostic messages, see L<perldiag>.
211
212 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
213 include any changes in L<perldiag> that reconcile it to the C<C> code.
214
215 =head2 New Diagnostics
216
217 XXX Newly added diagnostic messages go under here, separated into New Errors
218 and New Warnings
219
220 =head3 New Errors
221
222 =over 4
223
224 =item *
225
226 XXX L<message|perldiag/"message">
227
228 =back
229
230 =head3 New Warnings
231
232 =over 4
233
234 =item *
235
236 XXX L<message|perldiag/"message">
237
238 =back
239
240 =head2 Changes to Existing Diagnostics
241
242 XXX Changes (i.e. rewording) of diagnostic messages go here
243
244 =over 4
245
246 =item *
247
248 XXX Describe change here
249
250 =back
251
252 =head1 Utility Changes
253
254 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
255 Most of these are built within the directory F<utils>.
256
257 [ List utility changes as a =head2 entry for each utility and =item
258 entries for each change
259 Use L<XXX> with program names to get proper documentation linking. ]
260
261 =head2 L<XXX>
262
263 =over 4
264
265 =item *
266
267 XXX
268
269 =back
270
271 =head1 Configuration and Compilation
272
273 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
274 go here.  Any other changes to the Perl build process should be listed here.
275 However, any platform-specific changes should be listed in the
276 L</Platform Support> section, instead.
277
278 [ List changes as a =item entry ].
279
280 =over 4
281
282 =item *
283
284 XXX
285
286 =back
287
288 =head1 Testing
289
290 XXX Any significant changes to the testing of a freshly built perl should be
291 listed here.  Changes which create B<new> files in F<t/> go here as do any
292 large changes to the testing harness (e.g. when parallel testing was added).
293 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
294 that they represent may be covered elsewhere.
295
296 [ List each test improvement as a =item entry ]
297
298 =over 4
299
300 =item *
301
302 XXX
303
304 =back
305
306 =head1 Platform Support
307
308 XXX Any changes to platform support should be listed in the sections below.
309
310 [ Within the sections, list each platform as a =item entry with specific
311 changes as paragraphs below it. ]
312
313 =head2 New Platforms
314
315 XXX List any platforms that this version of perl compiles on, that previous
316 versions did not.  These will either be enabled by new files in the F<hints/>
317 directories, or new subdirectories and F<README> files at the top level of the
318 source tree.
319
320 =over 4
321
322 =item XXX-some-platform
323
324 XXX
325
326 =back
327
328 =head2 Discontinued Platforms
329
330 XXX List any platforms that this version of perl no longer compiles on.
331
332 =over 4
333
334 =item XXX-some-platform
335
336 XXX
337
338 =back
339
340 =head2 Platform-Specific Notes
341
342 =head3 Win32
343
344 =over
345
346 =item *
347
348 Intel C builds are now always built with C99 mode on.
349
350 =back
351
352 =head1 Internal Changes
353
354 XXX Changes which affect the interface available to C<XS> code go here.  Other
355 significant internal changes for future core maintainers should be noted as
356 well.
357
358 [ List each change as a =item entry ]
359
360 =over 4
361
362 =item *
363
364 XXX
365
366 =back
367
368 =head1 Selected Bug Fixes
369
370 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
371 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
372
373 [ List each fix as a =item entry ]
374
375 =over 4
376
377 =item *
378
379 On Win32, restoring in a child pseudo-process a variable that was
380 C<local()>ed in a parent pseudo-process before the C<fork> happened caused
381 memory corruption and a crash in the child pseudo-process (and therefore OS
382 process). 
383
384 =item *
385
386 The L<encoding> pragma's effect is now limited to lexical scope.  This
387 pragma is deprecated, but in the meantime, it could adversely affect
388 unrelated modules that are included in the same program.
389
390 =back
391
392 =head1 Known Problems
393
394 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
395 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
396 platform specific bugs also go here.
397
398 [ List each fix as a =item entry ]
399
400 =over 4
401
402 =item *
403
404 XXX
405
406 =back
407
408 =head1 Errata From Previous Releases
409
410 =over 4
411
412 =item *
413
414 XXX Add anything here that we forgot to add, or were mistaken about, in
415 the perldelta of a previous release.
416
417 =back
418
419 =head1 Obituary
420
421 XXX If any significant core contributor has died, we've added a short obituary
422 here.
423
424 =head1 Acknowledgements
425
426 XXX Generate this with:
427
428   perl Porting/acknowledgements.pl v5.21.6..HEAD
429
430 =head1 Reporting Bugs
431
432 If you find what you think is a bug, you might check the articles recently
433 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
434 https://rt.perl.org/ .  There may also be information at
435 http://www.perl.org/ , the Perl Home Page.
436
437 If you believe you have an unreported bug, please run the L<perlbug> program
438 included with your release.  Be sure to trim your bug down to a tiny but
439 sufficient test case.  Your bug report, along with the output of C<perl -V>,
440 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
441
442 If the bug you are reporting has security implications, which make it
443 inappropriate to send to a publicly archived mailing list, then please send it
444 to perl5-security-report@perl.org.  This points to a closed subscription
445 unarchived mailing list, which includes all the core committers, who will be
446 able to help assess the impact of issues, figure out a resolution, and help
447 co-ordinate the release of patches to mitigate or fix the problem across all
448 platforms on which Perl is supported.  Please only use this address for
449 security issues in the Perl core, not for modules independently distributed on
450 CPAN.
451
452 =head1 SEE ALSO
453
454 The F<Changes> file for an explanation of how to view exhaustive details on
455 what changed.
456
457 The F<INSTALL> file for how to build Perl.
458
459 The F<README> file for general stuff.
460
461 The F<Artistic> and F<Copying> files for copyright information.
462
463 =cut