From: Nat Torkington Date: Mon, 17 Mar 1997 16:50:14 +0000 (-0700) Subject: *.pod changes based on the FAQ X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3c10ad8e31f7d77e71c048b1746912f41cb540f0;p=p5sagit%2Fp5-mst-13.2.git *.pod changes based on the FAQ After the faqqing dust has settled, it looks like a couple of the things in the FAQ aren't mentioned in the pods and should be. I came up with a list of possible changes, and have implemented all but: - Need a discussion of optimising for speed/size, including compiling, autosplitting, etc. - The buffering discussion from part5 belongs somewhere. - The explanation of C<..> in perlop is confusing. Then again, C<..> is confusing. p5p-msgid: 199703171650.JAA02655@elara.frii.com --- diff --git a/pod/perldata.pod b/pod/perldata.pod index 1878f4a..b56f425 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -247,6 +247,11 @@ The usual Unix backslash rules apply for making characters such as newline, tab, etc., as well as some more exotic forms. See L for a list. +Octal or hex representations in string literals (eg, '0xffff') are not +automatically converted to their integer representation. The hex() +and oct() functions make these conversions for you. See +L and L for more details. + You can also embed newlines directly in your strings, i.e., they can end on a different line than they begin. This is nice, but if you forget your trailing quote, the error will not be reported until Perl finds @@ -440,6 +445,11 @@ put the list in parentheses to avoid ambiguity. Examples: # A "reverse comma operator". return (pop(@foo),pop(@foo))[0]; +C can be assigned to. This is useful for throwing away some of +the return values of a function: + + ($dev, $ino, undef, undef, $uid, $gid) = stat($file); + Lists may be assigned to if and only if each element of the list is legal to assign to: diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index eb7276a..0372ee3 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -1437,8 +1437,10 @@ Returns the socket option requested, or undefined if there is an error. =item glob Returns the value of EXPR with filename expansions such as a shell -would do. This is the internal function implementing the <*.c> -operator, except it's easier to use. If EXPR is omitted, $_ is used. +would do. This is the internal function implementing the +C*.cE> operator, except it's easier to use. If EXPR is +omitted, $_ is used. The EE operator is discussed in more +detail in L. =item gmtime EXPR diff --git a/pod/perlipc.pod b/pod/perlipc.pod index d289ad3..ab4a912 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -258,6 +258,57 @@ handle. Consider: print FH "bang\n"; close FH; +=head2 Filehandles + +Both the main process and the child process share the same STDIN, +STDOUT and STDERR filehandles. If both processes try to access them +at once, strange things can happen. You may want to close or reopen +the filehandles for the child. You can get around this by opening +your pipe with open(), but on some systems this means that the child +process cannot outlive the parent. + +=head2 Background Processes + +You can run a command in the background with: + + system("cmd&"); + +The command's STDOUT and STDERR (and possibly STDIN, depending on your +shell) will be the same as the parent's. You won't need to catch +SIGCHLD because of the double-fork taking place (see below for more +details). + +=head2 Complete Dissociation of Child from Parent + +In some cases (starting server processes, for instance) you'll want to +complete dissociate the child process from the parent. The following +process is reported to work on most Unixish systems. Non-Unix users +should check their Your_OS::Process module for other solutions. + +=over 4 + +=item * + +Open /dev/tty and use the the TIOCNOTTY ioctl on it. See L +for details. + +=item * + +Change directory to / + +=item * + +Reopen STDIN, STDOUT, and STDERR so they're not connected to the old +tty. + +=item * + +Background yourself like this: + + fork && exit; + +=back + =head2 Safe Pipe Opens Another interesting approach to IPC is making your single program go @@ -428,6 +479,14 @@ setting C<$AF_INET = 2>, you know you're in for big trouble: An immeasurably superior approach is to use the C module, which more reliably grants access to various constants and functions you'll need. +If you're not writing a server/client for an existing protocol like +NNTP or SMTP, you should give some thought to how your server will +know when the client has finished talking, and vice-versa. Most +protocols are based on one-line messages and responses (so one party +knows the other has finished when a "\n" is received) or multiline +messages and responses that end with a period on an empty line +("\n.\n" terminates a message/response). + =head2 Internet TCP Clients and Servers Use Internet-domain sockets when you want to do client-server diff --git a/pod/perlop.pod b/pod/perlop.pod index 71794fa..17c3c05 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -1190,3 +1190,23 @@ for them. By default, their results are interpreted as unsigned integers. However, if C is in effect, their results are interpreted as signed integers. For example, C<~0> usually evaluates to a large integral value. However, C is -1. + +=head2 Floating-point Arithmetic + +While C provides integer-only arithmetic, there is no +similar ways to provide rounding or truncation at a certain number of +decimal places. For rounding to a certain number of digits, sprintf() +or printf() is usually the easiest route. + +The POSIX module (part of the standard perl distribution) implements +ceil(), floor(), and a number of other mathematical and trigonometric +functions. The Math::Complex module (part of the standard perl +distribution) defines a number of mathematical functions that can also +work on real numbers. Math::Complex not as efficient as POSIX, but +POSIX can't work with complex numbers. + +Rounding in financial applications can have serious implications, and +the rounding method used should be specified precisely. In these +cases, it probably pays not to trust whichever system rounding is +being used by Perl, but to instead implement the rounding function you +need yourself. diff --git a/pod/perlre.pod b/pod/perlre.pod index cb3ce03..e4ee303 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -9,9 +9,10 @@ description of how to I regular expressions in matching operations, plus various examples of the same, see C and C in L. -The matching operations can -have various modifiers, some of which relate to the interpretation of -the regular expression inside. These are: +The matching operations can have various modifiers. The modifiers +which relate to the interpretation of the regular expression inside +are listed below. For the modifiers that alter the behaviour of the +operation, see L and L. =over 4 @@ -214,6 +215,17 @@ everything after the matched string. Examples: $seconds = $3; } +Once perl sees that you need one of C<$&>, C<$`> or C<$'> anywhere in +the program, it has to provide them on each and every pattern match. +This can slow your program down. The same mechanism that handles +these provides for the use of $1, $2, etc., so you pay the same price +for each regexp that contains capturing parentheses. But if you never +use $&, etc., in your script, then regexps I capturing +parentheses won't be penalized. So avoid $&, $', and $` if you can, +but if you can't (and some algorithms really appreciate them), once +you've used them once, use them at will, because you've already paid +the price. + You will note that all backslashed metacharacters in Perl are alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression languages, there are no backslashed symbols that aren't alphanumeric. diff --git a/pod/perlrun.pod b/pod/perlrun.pod index f90e642..88cba6e 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -87,6 +87,87 @@ If the script is syntactically correct, it is executed. If the script runs off the end without hitting an exit() or die() operator, an implicit C is provided to indicate successful completion. +=head2 #! and quoting on non-Unix systems + +Unix's #! technique can be simulated on other systems: + +=over 4 + +=item OS/2 + +Put + + extproc perl -S -your_switches + +as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's +`extproc' handling). + +=item DOS + +Create a batch file to run your script, and codify it in +C (see the F file in the source +distribution for more information). + +=item Win95/NT + +The Win95/NT installation, when using the Activeware port of Perl, +will modify the Registry to associate the .pl extension with the perl +interpreter. If you install another port, or (eventually) build your +own Win95/NT Perl using WinGCC, then you'll have to modify the +Registry yourself. + +=item Macintosh + +Macintosh perl scripts will have the the appropriate Creator and +Type, so that double-clicking them will invoke the perl application. + +=back + +Command-interpreters on non-Unix systems have rather different ideas +on quoting than Unix shells. You'll need to learn the special +characters in your command-interpreter (C<*>, C<\> and C<"> are +common) and how to protect whitespace and these characters to run +one-liners (see C<-e> below). + +On some systems, you may have to change single-quotes to double ones, +which you must I do on Unix or Plan9 systems. You might also +have to change a single % to a %%. + +For example: + + # Unix + perl -e 'print "Hello world\n"' + + # DOS, etc. + perl -e "print \"Hello world\n\"" + + # Mac + print "Hello world\n" + (then Run "Myscript" or Shift-Command-R) + + # VMS + perl -e "print ""Hello world\n""" + +The problem is that none of this is reliable: it depends on the command +tirely possible neither works. If 4DOS was the command shell, I'd +probably have better luck like this: + + perl -e "print "Hello world\n"" + +CMD.EXE in Windows NT slipped a lot of standard Unix functionality in +when nobody was looking, but just try to find documentation for its +quoting rules. + +Under the Mac, it depends which environment you are using. The MacPerl +shell, or MPW, is much like Unix shells in its support for several +quoting variants, except that it makes free use of the Mac's non-ASCII +characters as control characters. + +I'm afraid that there is no general solution to all of this. It is a +mess, pure and simple. + +[Some of this answer was contributed by Kenneth Albanowski.] + =head2 Switches A single-character switch may be combined with the following switch, if diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 6089431..0d72cf0 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -287,3 +287,38 @@ SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition. Prior to release 5.003 of Perl, a bug in the code of B could introduce a security hole in systems compiled with strict POSIX compliance. + +=head2 Protecting Your Programs + +There are a number of ways to hide the source to your Perl programs, +with varying levels of "security". + +First of all, however, you I take away read permission, because +the source code has to be readable in order to be compiled and +interpreted. (That doesn't mean that a CGI script's source is +readable by people on the web, though.) So you have to leave the +permissions at the socially friendly 0755 level. + +Some people regard this as a security problem. If your program does +insecure things, and relies on people not knowing how to exploit those +insecurities, it is not secure. It is often possible for someone to +determine the insecure things and exploit them without viewing the +source. Security through obscurity, the name for hiding your bugs +instead of fixing them, is little security indeed. + +You can try using encryption via source filters (Filter::* from CPAN). +But crackers might be able to decrypt it. You can try using the +byte-code compiler and interpreter described below, but crackers might +be able to de-compile it. You can try using the native-code compiler +described below, but crackers might be able to disassemble it. These +pose varying degrees of difficulty to people wanting to get at your +code, but none can definitively conceal it (this is true of every +language, not just Perl). + +If you're concerned about people profiting from your code, then the +bottom line is that nothing but a restrictive licence will give you +legal security. License your software and pepper it with threatening +statements like "This is unpublished proprietary software of XYZ Corp. +Your access to it does not give you permission to use it blah blah +blah." You should see a lawyer to be sure your licence's wording will +stand up in court. diff --git a/pod/perlvar.pod b/pod/perlvar.pod index d072d25..47503b3 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -213,6 +213,9 @@ delimit line boundaries when quoting poetry.) $_ = ; # whole file now here s/\n[ \t]+/ /g; +Remember: the value of $/ is a string, not a regexp. AWK has to be +better for something :-) + =item autoflush HANDLE EXPR =item $OUTPUT_AUTOFLUSH