Recipe 10.10. Returning Failure
Author: Tom Christiansen & Nathan Torkington
Date: 1999-07-02T01:39:58Z

#

| Chapter 10 Subroutines |

## 10.10. Returning Failure

### Problem

You want to return a value indicating that your function failed.

### Solution

Use a bare `return` statement without any argument, which returns `undef` in scalar context and the empty list `()` in list context.

    return;

### Discussion

A `return` without an argument means:

    sub empty_retval {
        return ( wantarray ? () : undef );
    }

You can't use just `return` `undef` because in list context you will get a list of one value: `undef`. If your caller says:

    if (@a = yourfunc()) { ... }

Then the "error" condition will be perceived as true, because `@a` will be assigned (`undef`) and then evaluated in scalar context. This yields `1`, the number of elements in `@a`, which is true. You could use the `wantarray` function to see what context you were called in, but a bare `return` is a clear and tidy solution that always works:

    unless ($a = sfunc()) { die "sfunc failed" }
    unless (@a = afunc()) { die "afunc failed" }
    unless (%a = hfunc()) { die "hfunc failed" }

Some of Perl's built-in functions have a peculiar return value. Both `fcntl` and `ioctl` have the curious habit of returning the string `"0` `but` `true"` in some circumstances. (This magic string is conveniently exempt from the -w flag's incessant numerical conversion warnings.) This has the advantage of letting you write code like this:

    ioctl(....) or die "can't ioctl: $!";

That way, code doesn't have to check for a defined zero as distinct from the undefined value, as it would for the `read` or `glob` functions. `"0` `but` `true"` is zero when used numerically. It's rare that this kind of return value is needed. A more common (and spectacular) way to indicate failure in a function is to raise an exception, as described in Recipe 10.12.

### See Also

The `undef`, `wantarray`, and `return` functions in Chapter 3 of Programming Perl and perlfunc (1); Recipe 10.12

10.9. Returning More Than One Array or Hash |  | 10.11. Prototyping Functions