NAME

trip — Specify C standard library functions to fail

SYNOPSIS

trip func[:chance[:errno]][,...] [--] command arguments...

trip [-l] [-V] [-e FUNC] [-c EXEC] [-h]

DESCRIPTION

Using trip you can start a program and intentionally trigger libc (C standard library) library function calls to fail. This can be useful during testing when you want to simulate an edge-case or a possible restriction, and inspect how your program will behave. It is best to use trip on software built without compiler optimisations, so that you can tell more easily what library functions the program will be using.

The default mode of operation is to list a single function to "trip" when invoked, followed by a command. For example we can prevent echo from allocating memory using malloc:

$ trip malloc echo hi
malloc: Cannot allocate memory

You can modify the default behaviour using the following flags:

-l: List all functions that trip knows how to "trip".
-V: Print version and build information.
-e FUNC: List all errno values that trip knows FUNC to set.
-c EXEC: Using nm(1), try to find out what functions a program EXEC might use and trip supports.
-h: Print a help message.
-d: Print debugging information during execution. This option has to be enable at compile time, so it could be missing from your installation.

Note that trip can get confused if the command you invoke also uses flags. In that case it is best to prefix the command with a -- delimiting the trip specifications from the sub-command.

Keep in mind that trip requires command to be a dynamically bound executable. If this is not the case, trip will have no effect.

Trip specifications

When specifying a function to "trip" the only necessary information is the function name. In this case the function will always fail with a random errno value, as specified for the requested function.

You can exert greater control of the behaviour of trip by specifying a chance of "tripping" a function and a specific errno value the function should set (in case the error handling depends on the kind of error). You can omit the chance or the error code. The fields of the specification are separable by a colon or a forward-flash (‘/’).

For example mkdir:0.2:ELOOP will make mkdir fail 20% of the time, in which case it will set errno to ELOOP (Too many levels of symbolic links).

One can trip multiple functions by enumerating these, separated by commas.

EXIT STATUS

In the default mode, trip will not exit if successful, and instead execute the requested command. It will exit with a >0 error code if an error occurs.

COMPATIBILITY

trip is currently only known to work on GNU/Linux systems with LD_PRELOAD support. In principle, it should be possible to extend support to other platforms.

trip does not support variable argument functions.

AUTHORS

trip was written by Philip Kaludercic <philip.kaludercic@fau.de>, and is maintained on https://gitlab.cs.fau.de/oj14ozun/trip.