[Chapter 3] 3.2.37 fcntl
Author: Larry Wall, Tom Christiansen & Randal L. Schwartz
Date: 1999-07-02T01:49:18Z

#

| Chapter 3 Functions |

### 3.2.37 fcntl

    fcntl FILEHANDLE, FUNCTION, SCALAR

This function calls UNIX's fcntl(2) function. (fcntl stands for "file control".) You'll probably have to say:

    use Fcntl;

first to get the correct function definitions. `SCALAR` will be read and/or written depending on the `FUNCTION` - a pointer to the string value of `SCALAR` will be passed as the third argument of the actual fcntl call. (If `SCALAR` has no string value but does have a numeric value, that value will be passed directly rather than a pointer to the string value.)

The return value of fcntl (and ioctl) is as follows:

System call returns | Perl returns
--- | ---
-1 | undefined value
0 | string "`0 but true`"
anything else | that number

Thus Perl returns true on success and false on failure, yet you can still easily determine the actual value returned by the operating system:

    $retval = fcntl(...) or $retval = -1;
    printf "System returned %d\n", $retval;

Here, even the string "`0 but true`" prints as 0, thanks to the `%d` format.

For example, since Perl always sets the close-on-exec flag for file descriptors above 2, if you wanted to pass file descriptor 3 to a subprocess, you might want to clear the flag like this:

    use Fcntl;
    open TTY,"+>/dev/tty" or die "Can't open /dev/tty: $!\n";
    fileno TTY == 3 or die "Internal error: fd mixup";
    fcntl TTY, &F_SETFL, 0
        or die "Can't clear the close-on-exec flag: $!\n";

fcntl will produce a fatal error if used on a machine that doesn't implement fcntl(2). On machines that do implement it, you can do such things as modify the close-on-exec flags, modify the non-blocking I/O flags, emulate the lockf(3) function, and arrange to receive the `SIGIO` signal when I/O is pending. You might even have record-locking facilities.

3.2.36 exp |  | 3.2.38 fileno