Index: branches/vendor/third/perl/pod/perlutil.pod =================================================================== --- branches/vendor/third/perl/pod/perlutil.pod (revision 17034) +++ branches/vendor/third/perl/pod/perlutil.pod (revision 18449) @@ -30,5 +30,5 @@ If it's run from a terminal, F will usually call F to translate POD (Plain Old Documentation - see L for an -explanation) into a man page, and then run F to display it; if +explanation) into a manpage, and then run F to display it; if F isn't available, F will be used instead and the output piped through your favourite pager. @@ -124,4 +124,14 @@ new-style Perl5 modules. +=head2 Administration + +=over 3 + +=item L + +To display and change the libnet configuration run the libnetcfg command. + +=back + =head2 Development @@ -145,5 +155,5 @@ around - the F<.ph> file should be created by running F on the corresponding F<.h> file. See the F documentation for more on how -to convert a whole bunch of header files at ones. +to convert a whole bunch of header files at once. =item L and L @@ -162,7 +172,7 @@ =item L -Perl comes with a profiler, the F module. The +Perl comes with a profiler, the F module. The F utility analyzes the output of this profiler and tells you -which subroutines are taking up the most run time. See L +which subroutines are taking up the most run time. See L for more information. @@ -181,5 +191,5 @@ L, L, L, L, L, L, L, -L, L +L, L =cut Index: branches/vendor/third/perl/pod/perlpod.pod =================================================================== --- branches/vendor/third/perl/pod/perlpod.pod (revision 17034) +++ branches/vendor/third/perl/pod/perlpod.pod (revision 18449) @@ -1,202 +1,513 @@ + +=for comment +This document is in Pod format. To read this, use a Pod formatter, +like "perldoc perlpod". + =head1 NAME -perlpod - plain old documentation +perlpod - the Plain Old Documentation format =head1 DESCRIPTION -A pod-to-whatever translator reads a pod file paragraph by paragraph, -and translates it to the appropriate output format. There are -three kinds of paragraphs: -L, -L, and -L. +Pod is a simple-to-use markup language used for writing documentation +for Perl, Perl programs, and Perl modules. + +Translators are available for converting Pod to various formats +like plain text, HTML, man pages, and more. + +Pod markup consists of three basic kinds of paragraphs: +L, +L, and +L. + + +=head2 Ordinary Paragraph + +Most paragraphs in your documentation will be ordinary blocks +of text, like this one. You can simply type in your text without +any markup whatsoever, and with just a blank line before and +after. When it gets formatted, it will undergo minimal formatting, +like being rewrapped, probably put into a proportionally spaced +font, and maybe even justified. + +You can use formatting codes in ordinary paragraphs, for B, +I, C, L, and more. Such +codes are explained in the "L" +section, below. + =head2 Verbatim Paragraph -A verbatim paragraph, distinguished by being indented (that is, -it starts with space or tab). It should be reproduced exactly, -with tabs assumed to be on 8-column boundaries. There are no -special formatting escapes, so you can't italicize or anything -like that. A \ means \, and nothing else. +Verbatim paragraphs are usually used for presenting a codeblock or +other text which does not require any special parsing or formatting, +and which shouldn't be wrapped. + +A verbatim paragraph is distinguished by having its first character +be a space or a tab. (And commonly, all its lines begin with spaces +and/or tabs.) It should be reproduced exactly, with tabs assumed to +be on 8-column boundaries. There are no special formatting codes, +so you can't italicize or anything like that. A \ means \, and +nothing else. + =head2 Command Paragraph -All command paragraphs start with "=", followed by an -identifier, followed by arbitrary text that the command can -use however it pleases. Currently recognized commands are - - =head1 heading - =head2 heading - =item text - =over N +A command paragraph is used for special treatment of whole chunks +of text, usually as headings or parts of lists. + +All command paragraphs (which are typically only one line long) start +with "=", followed by an identifier, followed by arbitrary text that +the command can use however it pleases. Currently recognized commands +are + + =head1 Heading Text + =head2 Heading Text + =head3 Heading Text + =head4 Heading Text + =over indentlevel + =item stuff =back =cut =pod - =for X - =begin X - =end X - -=over 4 - -=item =pod - -=item =cut - -The "=pod" directive does nothing beyond telling the compiler to lay -off parsing code through the next "=cut". It's useful for adding -another paragraph to the doc if you're mixing up code and pod a lot. - -=item =head1 - -=item =head2 - -Head1 and head2 produce first and second level headings, with the text in -the same paragraph as the "=headn" directive forming the heading description. - -=item =over - -=item =back - -=item =item - -Item, over, and back require a little more explanation: "=over" starts a -section specifically for the generation of a list using "=item" commands. At -the end of your list, use "=back" to end it. You will probably want to give -"4" as the number to "=over", as some formatters will use this for indentation. -The unit of indentation is optional. If the unit is not given the natural -indentation of the formatting system applied will be used. Note also that -there are some basic rules to using =item: don't use them outside of -an =over/=back block, use at least one inside an =over/=back block, you don't -_have_ to include the =back if the list just runs off the document, and -perhaps most importantly, keep the items consistent: either use "=item *" for -all of them, to produce bullets, or use "=item 1.", "=item 2.", etc., to -produce numbered lists, or use "=item foo", "=item bar", etc., i.e., things -that looks nothing like bullets or numbers. If you start with bullets or -numbers, stick with them, as many formatters use the first "=item" type to -decide how to format the list. - -=item =for - -=item =begin - -=item =end - -For, begin, and end let you include sections that are not interpreted -as pod text, but passed directly to particular formatters. A formatter -that can utilize that format will use the section, otherwise it will be -completely ignored. The directive "=for" specifies that the entire next -paragraph is in the format indicated by the first word after -"=for", like this: - - =for html
+ =begin format + =end format + =for format text... + +To explain them each in detail: + +=over + +=item C<=head1 I> + +=item C<=head2 I> + +=item C<=head3 I> + +=item C<=head4 I> + +Head1 through head4 produce headings, head1 being the highest +level. The text in the rest of this paragraph is the content of the +heading. For example: + + =head2 Object Attributes + +The text "Object Attributes" comprises the heading there. (Note that +head3 and head4 are recent additions, not supported in older Pod +translators.) The text in these heading commands can use +formatting codes, as seen here: + + =head2 Possible Values for C<$/> + +Such commands are explained in the +"L" section, below. + +=item C<=over I> + +=item C<=item I> + +=item C<=back> + +Item, over, and back require a little more explanation: "=over" starts +a region specifically for the generation of a list using "=item" +commands, or for indenting (groups of) normal paragraphs. At the end +of your list, use "=back" to end it. The I option to +"=over" indicates how far over to indent, generally in ems (where +one em is the width of an "M" in the document's base font) or roughly +comparable units; if there is no I option, it defaults +to four. (And some formatters may just ignore whatever I +you provide.) In the I in C<=item I>, you may +use formatting codes, as seen here: + + =item Using C<$|> to Control Buffering + +Such commands are explained in the +"L" section, below. + +Note also that there are some basic rules to using "=over" ... +"=back" regions: + +=over + +=item * + +Don't use "=item"s outside of an "=over" ... "=back" region. + +=item * + +The first thing after the "=over" command should be an "=item", unless +there aren't going to be any items at all in this "=over" ... "=back" +region. + +=item * + +Don't put "=headI" commands inside an "=over" ... "=back" region. + +=item * + +And perhaps most importantly, keep the items consistent: either use +"=item *" for all of them, to produce bullets; or use "=item 1.", +"=item 2.", etc., to produce numbered lists; or use "=item foo", +"=item bar", etc. -- namely, things that look nothing like bullets or +numbers. + +If you start with bullets or numbers, stick with them, as +formatters use the first "=item" type to decide how to format the +list. + +=back + +=item C<=cut> + +To end a Pod block, use a blank line, +then a line beginning with "=cut", and a blank +line after it. This lets Perl (and the Pod formatter) know that +this is where Perl code is resuming. (The blank line before the "=cut" +is not technically necessary, but many older Pod processors require it.) + +=item C<=pod> + +The "=pod" command by itself doesn't do much of anything, but it +signals to Perl (and Pod formatters) that a Pod block starts here. A +Pod block starts with I command paragraph, so a "=pod" command is +usually used just when you want to start a Pod block with an ordinary +paragraph or a verbatim paragraph. For example: + + =item stuff() + + This function does stuff. + + =cut + + sub stuff { + ... + } + + =pod + + Remember to check its return value, as in: + + stuff() || die "Couldn't do stuff!"; + + =cut + +=item C<=begin I> + +=item C<=end I> + +=item C<=for I I> + +For, begin, and end will let you have regions of text/code/data that +are not generally interpreted as normal Pod text, but are passed +directly to particular formatters, or are otherwise special. A +formatter that can use that format will use the region, otherwise it +will be completely ignored. + +A command "=begin I", some paragraphs, and a +command "=end I", mean that the text/data inbetween +is meant for formatters that understand the special format +called I. For example, + + =begin html + +

This is a raw HTML paragraph

-The paired commands "=begin" and "=end" work very similarly to "=for", but -instead of only accepting a single paragraph, all text from "=begin" to a -paragraph with a matching "=end" are treated as a particular format. + =end html + +The command "=for I I" +specifies that the remainder of just this paragraph (starting +right after I) is in that special format. + + =for html
+

This is a raw HTML paragraph

+ +This means the same thing as the above "=begin html" ... "=end html" +region. + +That is, with "=for", you can have only one paragraph's worth +of text (i.e., the text in "=foo targetname text..."), but with +"=begin targetname" ... "=end targetname", you can have any amount +of stuff inbetween. (Note that there still must be a blank line +after the "=begin" command and a blank line before the "=end" +command. Here are some examples of how to use these: - =begin html - -
Figure 1.
- - =end html - - =begin text - - --------------- - | foo | - | bar | - --------------- - - ^^^^ Figure 1. ^^^^ - - =end text - -Some format names that formatters currently are known to accept include -"roff", "man", "latex", "tex", "text", and "html". (Some formatters will -treat some of these as synonyms.) - -And don't forget, when using any command, that the command lasts up until -the end of the B, not the line. Hence in the examples below, you -can see the empty lines after each command to end its paragraph. + =begin html + +
Figure 1.

+ + =end html + + =begin text + + --------------- + | foo | + | bar | + --------------- + + ^^^^ Figure 1. ^^^^ + + =end text + +Some format names that formatters currently are known to accept +include "roff", "man", "latex", "tex", "text", and "html". (Some +formatters will treat some of these as synonyms.) + +A format name of "comment" is common for just making notes (presumably +to yourself) that won't appear in any formatted version of the Pod +document: + + =for comment + Make sure that all the available options are documented! + +Some I will require a leading colon (as in +C<"=for :formatname">, or +C<"=begin :formatname" ... "=end :formatname">), +to signal that the text is not raw data, but instead I Pod text +(i.e., possibly containing formatting codes) that's just not for +normal formatting (e.g., may not be a normal-use paragraph, but might +be for formatting as a footnote). + +=back + +And don't forget, when using any command, that the command lasts up +until the end of its I, not its line. So in the +examples below, you can see that every command needs the blank +line after it, to end its paragraph. Some examples of lists include: - =over 4 - - =item * - - First item - - =item * - - Second item - - =back - - =over 4 - - =item Foo() - - Description of Foo function - - =item Bar() - - Description of Bar function - - =back - -=back - -=head2 Ordinary Block of Text - -It will be filled, and maybe even -justified. Certain interior sequences are recognized both -here and in commands: - - I Italicize text, used for emphasis or variables - B Embolden text, used for switches and programs - S Text contains non-breaking spaces - C Render code in a typewriter font, or give some other - indication that this represents program text - L A link (cross reference) to name - L manual page - L item in manual page - L section in other manual page - L<"sec"> section in this manual page - (the quotes are optional) - L ditto - same as above but only 'text' is used for output. - (Text can not contain the characters '/' and '|', - and should contain matched '<' or '>') - L - L - L - L - L - - F Used for filenames - X An index entry - Z<> A zero-width character - E A named character (very similar to HTML escapes) - E A literal < - E A literal > - E A literal / - E A literal | - (these are optional except in other interior - sequences and when preceded by a capital letter) - E Character number n (probably in ASCII) - E Some non-numeric HTML entity, such - as E - -Most of the time, you will only need a single set of angle brackets to -delimit the beginning and end of interior sequences. However, sometimes -you will want to put a right angle bracket (or greater-than sign '>') -inside of a sequence. This is particularly common when using a sequence -to provide a different font-type for a snippet of code. As with all -things in Perl, there is more than one way to do it. One way is to -simply escape the closing bracket using an C sequence: + =over + + =item * + + First item + + =item * + + Second item + + =back + + =over + + =item Foo() + + Description of Foo function + + =item Bar() + + Description of Bar function + + =back + + +=head2 Formatting Codes + +In ordinary paragraphs and in some command paragraphs, various +formatting codes (a.k.a. "interior sequences") can be used: + +=for comment + "interior sequences" is such an opaque term. + Prefer "formatting codes" instead. + +=over + +=item CtextE> -- italic text + +Used for emphasis ("Ccareful!E>") and parameters +("CLABELE>") + +=item CtextE> -- bold text + +Used for switches ("C-nE switch>"), programs +("CchfnE for that>"), +emphasis ("Ccareful!E>"), and so on +("CautovivificationE>"). + +=item CcodeE> -- code text + +Renders code in a typewriter font, or gives some other indication that +this represents program text ("Cgmtime($^T)E>") or some other +form of computerese ("Cdrwxr-xr-xE>"). + +=item CnameE> -- a hyperlink + +There are various syntaxes, listed below. In the syntaxes given, +C, C, and C
cannot contain the characters +'/' and '|'; and any '<' or '>' should be matched. + +=over + +=item * + +CnameE> + +Link to a Perl manual page (e.g., CNet::PingE>). Note +that C should not contain spaces. This syntax +is also occasionally used for references to UNIX man pages, as in +Ccrontab(5)E>. + +=item * + +Cname/"sec"E> or Cname/secE> + +Link to a section in other manual page. E.g., +Cperlsyn/"For Loops"E> + +=item * + +C/"sec"E> or C/secE> or C"sec"E> + +Link to a section in this manual page. E.g., +C/"Object Methods"E> + +=back + +A section is started by the named heading or item. For +example, Cperlvar/$.E> or Cperlvar/"$."E> both +link to the section started by "C<=item $.>" in perlvar. And +Cperlsyn/For LoopsE> or Cperlsyn/"For Loops"E> +both link to the section started by "C<=head2 For Loops>" +in perlsyn. + +To control what text is used for display, you +use "Ctext|...E>", as in: + +=over + +=item * + +Ctext|nameE> + +Link this text to that manual page. E.g., +CPerl Error Messages|perldiagE> + +=item * + +Ctext|name/"sec"E> or Ctext|name/secE> + +Link this text to that section in that manual page. E.g., +CSWITCH statements|perlsyn/"Basic BLOCKs and Switch +Statements"E> + +=item * + +Ctext|/"sec"E> or Ctext|/secE> +or Ctext|"sec"E> + +Link this text to that section in this manual page. E.g., +Cthe various attributes|/"Member Data"E> + +=back + +Or you can link to a web page: + +=over + +=item * + +Cscheme:...E> + +Links to an absolute URL. For example, +Chttp://www.perl.org/E>. But note +that there is no corresponding Ctext|scheme:...E> syntax, for +various reasons. + +=back + +=item CescapeE> -- a character escape + +Very similar to HTML/XML C<&I;> "entity references": + +=over + +=item * + +CltE> -- a literal E (less than) + +=item * + +CgtE> -- a literal E (greater than) + +=item * + +CverbarE> -- a literal | (Itical I) + +=item * + +CsolE> = a literal / (Iidus) + +The above four are optional except in other formatting codes, +notably C...E>, and when preceded by a +capital letter. + +=item * + +ChtmlnameE> + +Some non-numeric HTML entity name, such as CeacuteE>, +meaning the same thing as C<é> in HTML -- i.e., a lowercase +e with an acute (/-shaped) accent. + +=item * + +CnumberE> + +The ASCII/Latin-1/Unicode character with that number. A +leading "0x" means that I is hex, as in +C0x201EE>. A leading "0" means that I is octal, +as in C075E>. Otherwise I is interpreted as being +in decimal, as in C181E>. + +Note that older Pod formatters might not recognize octal or +hex numeric escapes, and that many formatters cannot reliably +render characters above 255. (Some formatters may even have +to use compromised renderings of Latin-1 characters, like +rendering CeacuteE> as just a plain "e".) + +=back + +=item CfilenameE> -- used for filenames + +Typically displayed in italics. Example: "C.cshrcE>" + +=item CtextE> -- text contains non-breaking spaces + +This means that the words in I should not be broken +across lines. Example: S$x ? $y : $zE>>. + +=item Ctopic nameE> -- an index entry + +This is ignored by most formatters, but some may use it for building +indexes. It always renders as empty-string. +Example: Cabsolutizing relative URLsE> + +=item CE> -- a null (zero-effect) formatting code + +This is rarely used. It's one way to get around using an +EE...E code sometimes. For example, instead of +"CltE3>" (for "NE3") you could write +"CEE3>" (the "ZEE" breaks up the "N" and +the "E" so they can't be considered +the part of a (fictitious) "NE...E" code. + +=for comment + This was formerly explained as a "zero-width character". But it in + most parser models, it parses to nothing at all, as opposed to parsing + as if it were a E or E, which are REAL zero-width characters. + So "width" and "character" are exactly the wrong words. + +=back + +Most of the time, you will need only a single set of angle brackets to +delimit the beginning and end of formatting codes. However, +sometimes you will want to put a real right angle bracket (a +greater-than sign, '>') inside of a formatting code. This is particularly +common when using a formatting code to provide a different font-type for a +snippet of code. As with all things in Perl, there is more than +one way to do it. One way is to simply escape the closing bracket +using an C code: C<$a E=E $b> @@ -204,10 +515,11 @@ This will produce: "C<$a E=E $b>" -A more readable, and perhaps more "plain" way is to use an alternate set of -delimiters that doesn't require a ">" to be escaped. As of perl5.5.660, -doubled angle brackets ("<<" and ">>") may be used I For example, the following will do the -trick: +A more readable, and perhaps more "plain" way is to use an alternate +set of delimiters that doesn't require a single ">" to be escaped. With +the Pod formatters that are standard starting with perl5.5.660, doubled +angle brackets ("<<" and ">>") may be used I For example, the following will +do the trick: C<< $a <=> $b >> @@ -216,93 +528,147 @@ long as you have the same number of them in the opening and closing delimiters, and make sure that whitespace immediately follows the last -'<' of the opening delimiter, and immediately precedes the first '>' of -the closing delimiter. So the following will also work: +'<' of the opening delimiter, and immediately precedes the first '>' +of the closing delimiter. (The whitespace is ignored.) So the +following will also work: C<<< $a <=> $b >>> - C<<<< $a <=> $b >>>> + C<<<< $a <=> $b >>>> + +And they all mean exactly the same as this: + + C<$a E=E $b> + +As a further example, this means that if you wanted to put these bits of +code in C (code) style: + + open(X, ">>thing.dat") || die $! + $foo->bar(); + +you could do it like so: + + C<<< open(X, ">>thing.dat") || die $! >>> + C<< $foo->bar(); >> + +which is presumably easier to read than the old way: + + CEthing.dat") || die $!> + C<$foo-Ebar(); >> This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), -and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser -1.093 or later. - +and any other pod2xxx or Pod::Xxxx translators that use +Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later. =head2 The Intent -That's it. The intent is simplicity, not power. I wanted paragraphs -to look like paragraphs (block format), so that they stand out -visually, and so that I could run them through fmt easily to reformat -them (that's F7 in my version of B). I wanted the translator (and not -me) to worry about whether " or ' is a left quote or a right quote -within filled text, and I wanted it to leave the quotes alone, dammit, in -verbatim mode, so I could slurp in a working program, shift it over 4 -spaces, and have it print out, er, verbatim. And presumably in a -constant width font. - -In particular, you can leave things like this verbatim in your text: - - Perl - FILEHANDLE - $variable - function() - manpage(3r) - -Doubtless a few other commands or sequences will need to be added along -the way, but I've gotten along surprisingly well with just these. - -Note that I'm not at all claiming this to be sufficient for producing a -book. I'm just trying to make an idiot-proof common source for nroff, -TeX, and other markup languages, as used for online documentation. -Translators exist for B (that's for nroff(1) and troff(1)), -B, B, B, and B. +The intent is simplicity of use, not power of expression. Paragraphs +look like paragraphs (block format), so that they stand out +visually, and so that I could run them through C easily to reformat +them (that's F7 in my version of B, or Esc Q in my version of +B). I wanted the translator to always leave the C<'> and C<`> and +C<"> quotes alone, in verbatim mode, so I could slurp in a +working program, shift it over four spaces, and have it print out, er, +verbatim. And presumably in a monospace font. + +The Pod format is not necessarily sufficient for writing a book. Pod +is just meant to be an idiot-proof common source for nroff, HTML, +TeX, and other markup languages, as used for online +documentation. Translators exist for B, B, +B (that's for nroff(1) and troff(1)), B, and +B. Various others are available in CPAN. + =head2 Embedding Pods in Perl Modules -You can embed pod documentation in your Perl scripts. Start your -documentation with a "=head1" command at the beginning, and end it -with a "=cut" command. Perl will ignore the pod text. See any of the -supplied library modules for examples. If you're going to put your -pods at the end of the file, and you're using an __END__ or __DATA__ -cut mark, make sure to put an empty line there before the first pod -directive. - - __END__ - - =head1 NAME - - modern - I am a modern module - -If you had not had that empty line there, then the translators wouldn't -have seen it. - -=head2 Common Pod Pitfalls - -=over 4 - -=item * - -Pod translators usually will require paragraphs to be separated by -completely empty lines. If you have an apparently empty line with -some spaces on it, this can cause odd formatting. - -=item * - -Translators will mostly add wording around a LEE link, so that -Cfoo(1)E> becomes "the I(1) manpage", for example (see -B for details). Thus, you shouldn't write things like CfooE manpage>, if you want the translated document to read -sensibly. - -If you need total control of the text used for a link in the output -use the form LEshow this text|fooE instead. - -=item * - -The B command is provided to check pod syntax -for errors and warnings. For example, it checks for completely -blank lines in pod segments and for unknown escape sequences. -It is still advised to pass it through -one or more translators and proofread the result, or print out the -result and proofread that. Some of the problems found may be bugs in -the translators, which you may or may not wish to work around. +You can embed Pod documentation in your Perl modules and scripts. +Start your documentation with an empty line, a "=head1" command at the +beginning, and end it with a "=cut" command and an empty line. Perl +will ignore the Pod text. See any of the supplied library modules for +examples. If you're going to put your Pod at the end of the file, and +you're using an __END__ or __DATA__ cut mark, make sure to put an +empty line there before the first Pod command. + + __END__ + + =head1 NAME + + Time::Local - efficiently compute time from local and GMT time + +Without that empty line before the "=head1", many translators wouldn't +have recognized the "=head1" as starting a Pod block. + +=head2 Hints for Writing Pod + +=over + +=item * + +The B command is provided for checking Pod syntax for errors +and warnings. For example, it checks for completely blank lines in +Pod blocks and for unknown commands and formatting codes. You should +still also pass your document through one or more translators and proofread +the result, or print out the result and proofread that. Some of the +problems found may be bugs in the translators, which you may or may not +wish to work around. + +=item * + +If you're more familiar with writing in HTML than with writing in Pod, you +can try your hand at writing documentation in simple HTML, and converting +it to Pod with the experimental L module, +(available in CPAN), and looking at the resulting code. The experimental +L module in CPAN might also be useful. + +=item * + +Many older Pod translators require the lines before every Pod +command and after every Pod command (including "=cut"!) to be a blank +line. Having something like this: + + # - - - - - - - - - - - - + =item $firecracker->boom() + + This noisily detonates the firecracker object. + =cut + sub boom { + ... + +...will make such Pod translators completely fail to see the Pod block +at all. + +Instead, have it like this: + + # - - - - - - - - - - - - + + =item $firecracker->boom() + + This noisily detonates the firecracker object. + + =cut + + sub boom { + ... + +=item * + +Some older Pod translators require paragraphs (including command +paragraphs like "=head2 Functions") to be separated by I +empty lines. If you have an apparently empty line with some spaces +on it, this might not count as a separator for those translators, and +that could cause odd formatting. + +=item * + +Older translators might add wording around an LEE link, so that +CFoo::BarE> may become "the Foo::Bar manpage", for example. +So you shouldn't write things like CfooE +documentation>, if you want the translated document to read sensibly +-- instead write CFoo::Bar|Foo::BarE documentation> or +Cthe Foo::Bar documentation|Foo::BarE>, to control how the +link comes out. + +=item * + +Going past the 70th column in a verbatim block might be ungracefully +wrapped by some formatters. =back @@ -310,9 +676,10 @@ =head1 SEE ALSO -L, L, -L +L, L, +L, L, L, L, L. =head1 AUTHOR -Larry Wall - +Larry Wall, Sean M. Burke + +=cut Index: branches/vendor/third/perl/pod/Makefile.SH =================================================================== --- branches/vendor/third/perl/pod/Makefile.SH (revision 17034) +++ branches/vendor/third/perl/pod/Makefile.SH (revision 18449) @@ -1,3 +1,3 @@ -case $CONFIG in +case $PERL_CONFIG_SH in '') if test -f config.sh; then TOP=.; @@ -46,4 +46,8 @@ TEX = $TEX +# The following is used to include the current directory in +# the dynamic loader path you are building a shared libperl. +LDLIBPTH = $ldlibpth + !GROK!THIS! @@ -81,5 +85,5 @@ tex: pod2latex $(TEX) -toc: buildtoc +toc perltoc.pod: buildtoc $(PERLILIB) buildtoc @@ -131,17 +135,17 @@ # Dependencies. pod2latex: pod2latex.PL ../lib/Config.pm - $(PERL) -I../lib pod2latex.PL + $(LDLIBPTH) $(PERL) -I../lib pod2latex.PL pod2html: pod2html.PL ../lib/Config.pm - $(PERL) -I ../lib pod2html.PL + $(LDLIBPTH) $(PERL) -I ../lib pod2html.PL pod2man: pod2man.PL ../lib/Config.pm - $(PERL) -I ../lib pod2man.PL + $(LDLIBPTH) $(PERL) -I ../lib pod2man.PL pod2text: pod2text.PL ../lib/Config.pm - $(PERL) -I ../lib pod2text.PL + $(LDLIBPTH) $(PERL) -I ../lib pod2text.PL checkpods: checkpods.PL ../lib/Config.pm - $(PERL) -I ../lib checkpods.PL + $(LDLIBPTH) $(PERL) -I ../lib checkpods.PL pod2usage: pod2usage.PL ../lib/Config.pm @@ -154,5 +158,5 @@ $(PERL) -I ../lib podselect.PL -perlmodlib.pod: $(PERL) perlmodlib.PL ../mv-if-diff +perlmodlib.pod: $(PERL) perlmodlib.PL ../mv-if-diff ../MANIFEST rm -f perlmodlib.tmp $(PERL) -I ../lib perlmodlib.PL @@ -160,8 +164,8 @@ compile: all - $(REALPERL) -I../lib ../utils/perlcc -o pod2latex.exe pod2latex -log ../compilelog - $(REALPERL) -I../lib ../utils/perlcc -o pod2man.exe pod2man -log ../compilelog - $(REALPERL) -I../lib ../utils/perlcc -o pod2text.exe pod2text -log ../compilelog - $(REALPERL) -I../lib ../utils/perlcc -o checkpods.exe checkpods -log ../compilelog + $(REALPERL) -I../lib ../utils/perlcc -I .. -L .. -o pod2latex.exe pod2latex -log ../compilelog + $(REALPERL) -I../lib ../utils/perlcc -I .. -L .. -o pod2man.exe pod2man -log ../compilelog + $(REALPERL) -I../lib ../utils/perlcc -I .. -L .. -o pod2text.exe pod2text -log ../compilelog + $(REALPERL) -I../lib ../utils/perlcc -I .. -L .. -o checkpods.exe checkpods -log ../compilelog !NO!SUBS! Index: branches/vendor/third/perl/pod/perlport.pod =================================================================== --- branches/vendor/third/perl/pod/perlport.pod (revision 17034) +++ branches/vendor/third/perl/pod/perlport.pod (revision 18449) @@ -76,5 +76,5 @@ all of which are in a state of constant evolution. Thus, this material should be considered a perpetual work in progress -(Under Construction). +(C<< Under Construction >>). =head1 ISSUES @@ -105,5 +105,5 @@ } -You can get away with this on Unix and MacOS (they have a single +You can get away with this on Unix and Mac OS (they have a single character end-of-line), but the same program will break under DOSish perls because you're only chop()ing half the end-of-line. Instead, @@ -172,6 +172,6 @@ and LF characters. You can print it out and stick it in your wallet. - LF == \012 == \x0A == \cJ == ASCII 10 - CR == \015 == \x0D == \cM == ASCII 13 + LF eq \012 eq \x0A eq \cJ eq chr(10) eq ASCII 10 + CR eq \015 eq \x0D eq \cM eq chr(13) eq ASCII 13 | Unix | DOS | Mac | @@ -189,5 +189,21 @@ These are just the most common definitions of C<\n> and C<\r> in Perl. -There may well be others. +There may well be others. For example, on an EBCDIC implementation such +as z/OS or OS/400 the above material is similar to "Unix" but the code +numbers change: + + LF eq \025 eq \x15 eq chr(21) eq CP-1047 21 + LF eq \045 eq \x25 eq \cU eq chr(37) eq CP-0037 37 + CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-1047 13 + CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-0037 13 + + | z/OS | OS/400 | + ---------------------- + \n | LF | LF | + \r | CR | CR | + \n * | LF | LF | + \r * | CR | CR | + ---------------------- + * text-mode STDIO =head2 Numbers endianness and Width @@ -230,6 +246,9 @@ transfer and store numbers always in text format, instead of raw binary, or else consider using modules like Data::Dumper (included in -the standard distribution as of Perl 5.005) and Storable. Keeping -all data as text significantly simplifies matters. +the standard distribution as of Perl 5.005) and Storable (included as +of perl 5.8). Keeping all data as text significantly simplifies matters. + +The v-strings are portable only up to v2147483647 (0x7FFFFFFF), that's +how far EBCDIC, or more precisely UTF-EBCDIC will go. =head2 Files and Filesystems @@ -260,4 +279,7 @@ (e.g. the FAT filesystem limits the time granularity to two seconds). +The "inode change timestamp" (the C<-C> filetest) may really be the +"creation timestamp" (which it is not in UNIX). + VOS perl can emulate Unix filenames with C as path separator. The native pathname characters greater-than, less-than, number-sign, and @@ -267,4 +289,11 @@ separator, or go native and use C<.> for path separator and C<:> to signal filesystems and disk names. + +Don't assume UNIX filesystem access semantics: that read, write, +and execute are all the permissions there are, and even if they exist, +that their semantics (for example what do r, w, and x mean on +a directory) are the UNIX ones. The various UNIX/POSIX compatibility +layers usually try to make interfaces like chmod() work, but sometimes +there simply is no good mapping. If all this is intimidating, have no (well, maybe only a little) @@ -312,9 +341,10 @@ but people forget. -Do not have two files of the same name with different case, like -F and F, as many platforms have case-insensitive -filenames. Also, try not to have non-word characters (except for C<.>) -in the names, and keep them to the 8.3 convention, for maximum -portability, onerous a burden though this may appear. +Do not have two files or directories of the same name with different +case, like F and F, as many platforms have +case-insensitive (or at least case-forgiving) filenames. Also, try +not to have non-word characters (except for C<.>) in the names, and +keep them to the 8.3 convention, for maximum portability, onerous a +burden though this may appear. Likewise, when using the AutoSplit module, try to keep your functions to @@ -323,12 +353,16 @@ first 8 characters. -Whitespace in filenames is tolerated on most systems, but not all. +Whitespace in filenames is tolerated on most systems, but not all, +and even on systems where it might be tolerated, some utilities +might become confused by such whitespace. + Many systems (DOS, VMS) cannot have more than one C<.> in their filenames. Don't assume C<< > >> won't be the first character of a filename. -Always use C<< < >> explicitly to open a file for reading, -unless you want the user to be able to specify a pipe open. - - open(FILE, "< $existing_file") or die $!; +Always use C<< < >> explicitly to open a file for reading, or even +better, use the three-arg version of open, unless you want the user to +be able to specify a pipe open. + + open(FILE, '<', $existing_file) or die $!; If filenames might use strange characters, it is safest to open it @@ -336,4 +370,30 @@ translate characters like C<< > >>, C<< < >>, and C<|>, which may be the wrong thing to do. (Sometimes, though, it's the right thing.) +Three-arg open can also help protect against this translation in cases +where it is undesirable. + +Don't use C<:> as a part of a filename since many systems use that for +their own semantics (Mac OS Classic for separating pathname components, +many networking schemes and utilities for separating the nodename and +the pathname, and so on). For the same reasons, avoid C<@>, C<;> and +C<|>. + +Don't assume that in pathnames you can collapse two leading slashes +C into one: some networking and clustering filesystems have special +semantics for that. Let the operating system to sort it out. + +The I as defined by ANSI C are + + a b c d e f g h i j k l m n o p q r t u v w x y z + A B C D E F G H I J K L M N O P Q R T U V W X Y Z + 0 1 2 3 4 5 6 7 8 9 + . _ - + +and the "-" shouldn't be the first character. If you want to be +hypercorrect, stay case-insensitive and within the 8.3 naming +convention (all the files and directories have to be unique within one +directory if their names are lowercased and truncated to eight +characters before the C<.>, if any, and to three characters after the +C<.>, if any). (And do not use C<.>s in directory names.) =head2 System Interaction @@ -352,4 +412,23 @@ Don't open the same file more than once at a time for writing, as some operating systems put mandatory locks on such files. + +Don't assume that write/modify permission on a directory gives the +right to add or delete files/directories in that directory. That is +filesystem specific: in some filesystems you need write/modify +permission also (or even just) in the file/directory itself. In some +filesystems (AFS, DFS) the permission to add/delete directory entries +is a completely separate permission. + +Don't assume that a single C completely gets rid of the file: +some filesystems (most notably the ones in VMS) have versioned +filesystems, and unlink() removes only the most recent one (it doesn't +remove all the versions because by default the native tools on those +platforms remove just the most recent version, too). The portable +idiom to remove all the versions of a file is + + 1 while unlink "file"; + +This will terminate if the file is undeleteable for some reason +(protected, not there, and so on). Don't count on a specific environment variable existing in C<%ENV>. @@ -369,4 +448,36 @@ Don't count on specific values of C<$!>. + +=head2 Command names versus file pathnames + +Don't assume that the name used to invoke a command or program with +C or C can also be used to test for the existence of the +file that holds the executable code for that command or program. +First, many systems have "internal" commands that are built-in to the +shell or OS and while these commands can be invoked, there is no +corresponding file. Second, some operating systems (e.g., Cygwin, +DJGPP, OS/2, and VOS) have required suffixes for executable files; +these suffixes are generally permitted on the command name but are not +required. Thus, a command like "perl" might exist in a file named +"perl", "perl.exe", or "perl.pm", depending on the operating system. +The variable "_exe" in the Config module holds the executable suffix, +if any. Third, the VMS port carefully sets up $^X and +$Config{perlpath} so that no further processing is required. This is +just as well, because the matching regular expression used below would +then have to deal with a possible trailing version number in the VMS +file name. + +To convert $^X to a file pathname, taking account of the requirements +of the various operating system possibilities, say: + use Config; + $thisperl = $^X; + if ($^O ne 'VMS') + {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} + +To convert $Config{perlpath} to a file pathname, say: + use Config; + $thisperl = $Config{perlpath}; + if ($^O ne 'VMS') + {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} =head2 Interprocess Communication (IPC) @@ -405,4 +516,12 @@ even on all Unix platforms. +Do not use either the bare result of C or +bare v-strings (such as C) to represent IPv4 addresses: +both forms just pack the four bytes into network order. That this +would be equal to the C language C struct (which is what the +socket code internally uses) is not guaranteed. To be portable use +the routines of the Socket extension, such as C, +C, and C. + The rule of thumb for portable code is: Do it all in portable Perl, or use a module (that may internally implement it with platform-specific @@ -469,13 +588,18 @@ =head2 Character sets and character encoding -Assume little about character sets. Assume nothing about -numerical values (C, C) of characters. Do not -assume that the alphabetic characters are encoded contiguously (in -the numeric sense). Do not assume anything about the ordering of the -characters. The lowercase letters may come before or after the -uppercase letters; the lowercase and uppercase may be interlaced so -that both `a' and `A' come before `b'; the accented and other -international characters may be interlaced so that E comes -before `b'. +Assume very little about character sets. + +Assume nothing about numerical values (C, C) of characters. +Do not use explicit code point ranges (like \xHH-\xHH); use for +example symbolic character classes like C<[:print:]>. + +Do not assume that the alphabetic characters are encoded contiguously +(in the numeric sense). There may be gaps. + +Do not assume anything about the ordering of the characters. +The lowercase letters may come before or after the uppercase letters; +the lowercase and uppercase may be interlaced so that both `a' and `A' +come before `b'; the accented and other international characters may +be interlaced so that E comes before `b'. =head2 Internationalisation @@ -512,5 +636,5 @@ Most multi-user platforms provide basic levels of security, usually implemented at the filesystem level. Some, however, do -not--unfortunately. Thus the notion of user id, or "home" directory, +not-- unfortunately. Thus the notion of user id, or "home" directory, or even the state of being logged-in, may be unrecognizable on many platforms. If you write programs that are security-conscious, it @@ -518,4 +642,22 @@ under so that you can write code explicitly for that platform (or class of platforms). + +Don't assume the UNIX filesystem access semantics: the operating +system or the filesystem may be using some ACL systems, which are +richer languages than the usual rwx. Even if the rwx exist, +their semantics might be different. + +(From security viewpoint testing for permissions before attempting to +do something is silly anyway: if one tries this, there is potential +for race conditions-- someone or something might change the +permissions between the permissions check and the actual operation. +Just try the operation.) + +Don't assume the UNIX user and group semantics: especially, don't +expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work +for switching identities (or memberships). + +Don't assume set-uid and set-gid semantics. (And even if you do, +think twice: set-uid and set-gid are a known can of security worms.) =head2 Style @@ -533,5 +675,5 @@ assume certain things about the filesystem and paths. Be careful not to depend on a specific output style for errors, such as when -checking C<$!> after an system call. Some platforms expect a certain +checking C<$!> after a system call. Some platforms expect a certain output format, and perl on those platforms may have been adjusted accordingly. Most specifically, don't anchor a regex when testing @@ -587,4 +729,5 @@ AIX aix aix BSD/OS bsdos i386-bsdos + Darwin darwin darwin dgux dgux AViiON-dgux DYNIX/ptx dynixptx i386-dynixptx @@ -596,5 +739,5 @@ HP-UX hpux PA-RISC1.1 IRIX irix irix - Mac OS X rhapsody rhapsody + Mac OS X darwin darwin MachTen PPC machten powerpc-machten NeXT 3 next next-fat @@ -664,15 +807,20 @@ DOSish perls are as follows: - OS $^O $Config{'archname'} - -------------------------------------------- - MS-DOS dos - PC-DOS dos - OS/2 os2 - Windows 95 MSWin32 MSWin32-x86 - Windows 98 MSWin32 MSWin32-x86 - Windows NT MSWin32 MSWin32-x86 - Windows NT MSWin32 MSWin32-ALPHA - Windows NT MSWin32 MSWin32-ppc - Cygwin cygwin + OS $^O $Config{archname} ID Version + -------------------------------------------------------- + MS-DOS dos ? + PC-DOS dos ? + OS/2 os2 ? + Windows 3.1 ? ? 0 3 01 + Windows 95 MSWin32 MSWin32-x86 1 4 00 + Windows 98 MSWin32 MSWin32-x86 1 4 10 + Windows ME MSWin32 MSWin32-x86 1 ? + Windows NT MSWin32 MSWin32-x86 2 4 xx + Windows NT MSWin32 MSWin32-ALPHA 2 4 xx + Windows NT MSWin32 MSWin32-ppc 2 4 xx + Windows 2000 MSWin32 MSWin32-x86 2 5 xx + Windows XP MSWin32 MSWin32-x86 2 ? + Windows CE MSWin32 ? 3 + Cygwin cygwin ? The various MSWin32 Perl's can distinguish the OS they are running on @@ -685,4 +833,11 @@ } +There are also Win32::IsWinNT() and Win32::IsWin95(), try C, +and as of libwin32 0.19 (not part of the core Perl distribution) +Win32::GetOSName(). The very portable POSIX::uname() will work too: + + c:\> perl -MPOSIX -we "print join '|', uname" + Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86 + Also see: @@ -698,5 +853,5 @@ The EMX environment for DOS, OS/2, etc. emx@iaehv.nl, http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or -ftp://hobbes.nmsu.edu/pub/os2/dev/emx. Also L. +ftp://hobbes.nmsu.edu/pub/os2/dev/emx/ Also L. =item * @@ -785,12 +940,8 @@ $is_68k = $MacPerl::Architecture eq 'Mac68K'; -S and S, based on NeXT's OpenStep OS, will -(in theory) be able to run MacPerl natively, under the "Classic" -environment. The new "Cocoa" environment (formerly called the "Yellow Box") -may run a slightly modified version of MacPerl, using the Carbon interfaces. - -S and its Open Source version, Darwin, both run Unix -perl natively (with a few patches). Full support for these -is slated for perl 5.6. +S, based on NeXT's OpenStep OS, runs MacPerl natively, under the +"Classic" environment. There is no "Carbon" version of MacPerl to run +under the primary Mac OS X environment. S and its Open Source +version, Darwin, both run Unix perl natively. Also see: @@ -800,13 +951,13 @@ =item * +MacPerl Development, http://dev.macperl.org/ . + +=item * + The MacPerl Pages, http://www.macperl.com/ . =item * -The MacPerl mailing lists, http://www.macperl.org/ . - -=item * - -MacPerl Module Porters, http://pudge.net/mmp/ . +The MacPerl mailing lists, http://lists.perl.org/ . =back @@ -875,8 +1026,9 @@ native formats. -What C<\n> represents depends on the type of file opened. It could -be C<\015>, C<\012>, C<\015\012>, or nothing. The VMS::Stdio module -provides access to the special fopen() requirements of files with unusual -attributes on VMS. +What C<\n> represents depends on the type of file opened. It usually +represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>, +C<\000>, C<\040>, or nothing depending on the file organiztion and +record format. The VMS::Stdio module provides access to the +special fopen() requirements of files with unusual attributes on VMS. TCP/IP stacks are optional on VMS, so socket routines might not be @@ -928,10 +1080,10 @@ Unix-style file specifications as in either of the following: - $ perl -ne "print if /perl_setup/i" >system>notices - $ perl -ne "print if /perl_setup/i" /system/notices + C<< $ perl -ne "print if /perl_setup/i" >system>notices >> + C<< $ perl -ne "print if /perl_setup/i" /system/notices >> or even a mixture of both as in: - $ perl -ne "print if /perl_setup/i" >system/notices + C<< $ perl -ne "print if /perl_setup/i" >system/notices >> Even though VOS allows the slash character to appear in object @@ -942,9 +1094,10 @@ file names to 32 or fewer characters. -See F for restrictions that apply when Perl is built -with the alpha version of VOS POSIX.1 support. - -Perl on VOS is built without any extensions and does not support -dynamic loading. +Perl on VOS can be built using two different compilers and two different +versions of the POSIX runtime. The recommended method for building full +Perl is with the GNU C compiler and the generally-available version of +VOS POSIX support. See F (installed as L) for +restrictions that apply when Perl is built using the VOS Standard C +compiler or the alpha version of VOS POSIX support. The value of C<$^O> on VOS is "VOS". To determine the architecture that @@ -978,5 +1131,5 @@ =item * -F +F (installed as L) =item * @@ -986,10 +1139,10 @@ There is no specific mailing list for Perl on VOS. You can post comments to the comp.sys.stratus newsgroup, or subscribe to the general -Stratus mailing list. Send a letter with "Subscribe Info-Stratus" in +Stratus mailing list. Send a letter with "subscribe Info-Stratus" in the message body to majordomo@list.stratagy.com. =item * -VOS Perl on the web at http://ftp.stratus.com/pub/vos/vos.html +VOS Perl on the web at http://ftp.stratus.com/pub/vos/posix/posix.html =back @@ -1214,4 +1367,5 @@ ------------------------------------------ Amiga DOS amigaos m68k-amigos + BeOS beos MPE/iX mpeix PA-RISC1.1 @@ -1246,5 +1400,5 @@ =item * -Plan 9, F +S, F =back @@ -1344,7 +1498,10 @@ Access permissions are mapped onto VOS access-control list changes. (VOS) +The actual permissions set depend on the value of the C +in the SYSTEM environment settings. (Cygwin) + =item chown LIST -Not implemented. (S, Win32, Plan9, S, VOS) +Not implemented. (S, Win32, S, S, VOS) Does nothing, but won't fail. (Win32) @@ -1354,5 +1511,5 @@ =item chroot -Not implemented. (S, Win32, VMS, Plan9, S, VOS, VM/ESA) +Not implemented. (S, Win32, VMS, S, S, VOS, VM/ESA) =item crypt PLAINTEXT,SALT @@ -1365,9 +1522,9 @@ =item dbmclose HASH -Not implemented. (VMS, Plan9, VOS) +Not implemented. (VMS, S, VOS) =item dbmopen HASH,DBNAME,MODE -Not implemented. (VMS, Plan9, VOS) +Not implemented. (VMS, S, VOS) =item dump LABEL @@ -1388,4 +1545,15 @@ (SunOS, Solaris, HP-UX) +=item exit EXPR + +=item exit + +Emulates UNIX exit() (which considers C to indicate an error) by +mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden +with the pragma C. As with the CRTL's exit() +function, C is also mapped to an exit status of SS$_NORMAL +(C<1>); this mapping cannot be overridden. Any other argument to exit() +is used directly as Perl's exit status. (VMS) + =item fcntl FILEHANDLE,FUNCTION,SCALAR @@ -1400,5 +1568,5 @@ =item fork -Not implemented. (S, AmigaOS, S, VOS, VM/ESA) +Not implemented. (S, AmigaOS, S, VOS, VM/ESA, VMS) Emulated using multiple interpreters. See L. (Win32) @@ -1417,11 +1585,25 @@ =item getppid +Not implemented. (S, Win32, S) + +=item getpriority WHICH,WHO + +Not implemented. (S, Win32, VMS, S, VOS, VM/ESA) + +=item getpwnam NAME + +Not implemented. (S, Win32) + +Not useful. (S) + +=item getgrnam NAME + Not implemented. (S, Win32, VMS, S) -=item getpriority WHICH,WHO - -Not implemented. (S, Win32, VMS, S, VOS, VM/ESA) - -=item getpwnam NAME +=item getnetbyname NAME + +Not implemented. (S, Win32, S) + +=item getpwuid UID Not implemented. (S, Win32) @@ -1429,116 +1611,91 @@ Not useful. (S) -=item getgrnam NAME +=item getgrgid GID Not implemented. (S, Win32, VMS, S) -=item getnetbyname NAME - -Not implemented. (S, Win32, Plan9) - -=item getpwuid UID +=item getnetbyaddr ADDR,ADDRTYPE + +Not implemented. (S, Win32, S) + +=item getprotobynumber NUMBER + +Not implemented. (S) + +=item getservbyport PORT,PROTO + +Not implemented. (S) + +=item getpwent + +Not implemented. (S, Win32, VM/ESA) + +=item getgrent + +Not implemented. (S, Win32, VMS, VM/ESA) + +=item gethostent Not implemented. (S, Win32) -Not useful. (S) - -=item getgrgid GID - -Not implemented. (S, Win32, VMS, S) - -=item getnetbyaddr ADDR,ADDRTYPE - -Not implemented. (S, Win32, Plan9) - -=item getprotobynumber NUMBER - -Not implemented. (S) - -=item getservbyport PORT,PROTO - -Not implemented. (S) - -=item getpwent - -Not implemented. (S, Win32, VM/ESA) - -=item getgrent - -Not implemented. (S, Win32, VMS, VM/ESA) - -=item gethostent +=item getnetent + +Not implemented. (S, Win32, S) + +=item getprotoent + +Not implemented. (S, Win32, S) + +=item getservent + +Not implemented. (Win32, S) + +=item sethostent STAYOPEN + +Not implemented. (S, Win32, S, S) + +=item setnetent STAYOPEN + +Not implemented. (S, Win32, S, S) + +=item setprotoent STAYOPEN + +Not implemented. (S, Win32, S, S) + +=item setservent STAYOPEN + +Not implemented. (S, Win32, S) + +=item endpwent + +Not implemented. (S, MPE/iX, VM/ESA, Win32) + +=item endgrent + +Not implemented. (S, MPE/iX, S, VM/ESA, VMS, Win32) + +=item endhostent Not implemented. (S, Win32) -=item getnetent - -Not implemented. (S, Win32, Plan9) - -=item getprotoent - -Not implemented. (S, Win32, Plan9) - -=item getservent - -Not implemented. (Win32, Plan9) - -=item setpwent - -Not implemented. (S, Win32, S) - -=item setgrent - -Not implemented. (S, Win32, VMS, S) - -=item sethostent STAYOPEN - -Not implemented. (S, Win32, Plan9, S) - -=item setnetent STAYOPEN - -Not implemented. (S, Win32, Plan9, S) - -=item setprotoent STAYOPEN - -Not implemented. (S, Win32, Plan9, S) - -=item setservent STAYOPEN - -Not implemented. (Plan9, Win32, S) - -=item endpwent - -Not implemented. (S, MPE/iX, VM/ESA, Win32) - -=item endgrent - -Not implemented. (S, MPE/iX, S, VM/ESA, VMS, Win32) - -=item endhostent - -Not implemented. (S, Win32) - =item endnetent -Not implemented. (S, Win32, Plan9) +Not implemented. (S, Win32, S) =item endprotoent -Not implemented. (S, Win32, Plan9) +Not implemented. (S, Win32, S) =item endservent -Not implemented. (Plan9, Win32) +Not implemented. (S, Win32) =item getsockopt SOCKET,LEVEL,OPTNAME -Not implemented. (S, Plan9) +Not implemented. (S) =item glob EXPR =item glob - -Globbing built-in, but only C<*> and C metacharacters are supported. -(S) This operator is implemented via the File::Glob extension on most @@ -1556,6 +1713,8 @@ =item kill SIGNAL, LIST -Not implemented, hence not useful for taint checking. (S, -S) +C is implemented for the sake of taint checking; +use with other signals is unimplemented. (S) + +Not implemented, hence not useful for taint checking. (S) C doesn't have the semantics of C, i.e. it doesn't send @@ -1594,5 +1753,5 @@ =item msgrcv ID,VAR,SIZE,TYPE,FLAGS -Not implemented. (S, Win32, VMS, Plan9, S, VOS) +Not implemented. (S, Win32, VMS, S, S, VOS) =item open FILEHANDLE,EXPR @@ -1610,6 +1769,4 @@ =item pipe READHANDLE,WRITEHANDLE -Not implemented. (S) - Very limited functionality. (MiNT) @@ -1622,9 +1779,9 @@ =item select RBITS,WBITS,EBITS,TIMEOUT -Only implemented on sockets. (Win32) +Only implemented on sockets. (Win32, VMS) Only reliable on sockets. (S) -Note that the C form is generally portable. +Note that the C