-However, for historical reasons, some values are universal: zero means
-read-only, one means write-only, and two means read/write.
-
-If the file named by FILENAME does not exist and the C<open> call
-creates it (typically because MODE includes the O_CREAT flag), then
-the value of PERMS specifies the permissions of the newly created
-file. If PERMS is omitted, the default value is 0666, which allows
-read and write for all. This default is reasonable: see C<umask>.
-
-The IO::File module provides a more object-oriented approach, if you're
+For historical reasons, some values work on almost every system
+supported by perl: zero means read-only, one means write-only, and two
+means read/write. We know that these values do I<not> work under
+OS/390 Unix and on the Macintosh; you probably don't want to use them
+in new code.
+
+If the file named by FILENAME does not exist and the C<open()> call creates
+it (typically because MODE includes the C<O_CREAT> flag), then the value of
+PERMS specifies the permissions of the newly created file. If you omit
+the PERMS argument to C<sysopen()>, Perl uses the octal value C<0666>.
+These permission values need to be in octal, and are modified by your
+process's current C<umask>. The C<umask> value is a number representing
+disabled permissions bits--if your C<umask> were C<027> (group can't write;
+others can't read, write, or execute), then passing C<sysopen()> C<0666> would
+create a file with mode C<0640> (C<0666 &~ 027> is C<0640>).
+
+If you find this C<umask()> talk confusing, here's some advice: supply a
+creation mode of C<0666> for regular files and one of C<0777> for directories
+(in C<mkdir()>) and executable files. This gives users the freedom of
+choice: if they want protected files, they might choose process umasks
+of C<022>, C<027>, or even the particularly antisocial mask of C<077>. Programs
+should rarely if ever make policy decisions better left to the user.
+The exception to this is when writing files that should be kept private:
+mail files, web browser cookies, I<.rhosts> files, and so on. In short,
+seldom if ever use C<0644> as argument to C<sysopen()> because that takes
+away the user's option to have a more permissive umask. Better to omit it.
+
+The C<IO::File> module provides a more object-oriented approach, if you're