Perl 5 version 32.0 documentation

sysopen

  • sysopen FILEHANDLE,FILENAME,MODE

  • sysopen FILEHANDLE,FILENAME,MODE,PERMS

    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.

    Returns true on success and undef otherwise.

    PerlIO layers will be applied to the handle the same way they would in an open call that does not specify layers. That is, the current value of ${^OPEN} as set by the open pragma in a lexical scope, or the -C commandline option or PERL_UNICODE environment variable in the main program scope, falling back to the platform defaults as described in Defaults and how to override them in PerlIO. If you want to remove any layers that may transform the byte stream, use binmode after opening it.

    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 umask for more on this.

    This function has no direct relation to the usage of sysread, syswrite, or sysseek. A handle opened with this function can be used with buffered IO just as one opened with open can be used with unbuffered IO.

    Note that under Perls older than 5.8.0, sysopen depends on the fdopen(3) C library function. On many Unix systems, fdopen(3) is known to fail when file descriptors exceed a certain value, typically 255. If you need more file descriptors than that, consider using the POSIX::open function. For Perls 5.8.0 and later, PerlIO is (most often) the default.

    See perlopentut for a kinder, gentler explanation of opening files.

    Portability issues: sysopen in perlport.