Opens the file whose filename is given by FILENAME, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the real filehandle wanted; an undefined scalar will be suitably autovivified. This function calls the underlying operating system's open(2) function with the parameters FILENAME, MODE, and PERMS.
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module Fcntl
. See
the documentation of your operating system's open(2) syscall to see
which values and flag bits are available. You may combine several flags
using the |-operator.
Some of the most common values are O_RDONLY
for opening the file in
read-only mode, O_WRONLY
for opening the file in write-only mode,
and O_RDWR
for opening the file in read-write mode.
For historical reasons, some values work on almost every system supported by Perl: 0 means read-only, 1 means write-only, and 2 means read/write. We know that these values do not work under OS/390 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 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 you omit
the PERMS argument to sysopen, Perl uses the octal value 0666
.
These permission values need to be in octal, and are modified by your
process's current umask.
In many systems the O_EXCL
flag is available for opening files in
exclusive mode. This is not locking: exclusiveness means here that
if the file already exists, sysopen() fails. O_EXCL
may not work
on network filesystems, and has no effect unless the O_CREAT
flag
is set as well. Setting O_CREAT|O_EXCL
prevents the file from
being opened if it is a symbolic link. It does not protect against
symbolic links in the file's path.
Sometimes you may want to truncate an already-existing file. This
can be done using the O_TRUNC
flag. The behavior of
O_TRUNC
with O_RDONLY
is undefined.
You should seldom if ever use 0644
as argument to sysopen, because
that takes away the user's option to have a more permissive umask.
Better to omit it. See the perlfunc(1) entry on umask for more
on this.
Note that sysopen depends on the fdopen() C library function.
On many Unix systems, fdopen() is known to fail when file descriptors
exceed a certain value, typically 255. If you need more file
descriptors than that, consider rebuilding Perl to use the sfio
library, or perhaps using the POSIX::open() function.
See perlopentut for a kinder, gentler explanation of opening files.
Portability issues: sysopen in perlport.