Returning Failure (Perl Cookbook, 2nd Edition)

## 10.10. Returning Failure

### 10.10.1. Problem

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

### 10.10.2. Solution

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

>     return;

### 10.10.3. 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 assigned to `@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 nagging warnings about improper numerical conversions.) 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.

### 10.10.4. See Also

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

Copyright © 2003 O'Reilly & Associates. All rights reserved.