Unhappy surprise: Firebird SQL's backup/restore uses magic words for stdin and stdout

I'm writing this mainly for Google/Bingle; it's not of general interest.

I work on a project that uses the Firebird SQL database extensively, and one of the command-line tools is gbak, which performs backup and restore operations. I (and my customers) use this all the time.

Normally the backup and restore operations are done to explicit filenames (backup CL_123.gdb to CL_123.gbk), but a recent project suggested we wanted to pipe these together (credentials removed for clarity):

gbak -backup CL_123.gdb /dev/stdout | gbak -restore /dev/stdin CL_123.gdb   # FAILS

The problem is that it doesn't work: the restore half is trying to seek on the input, and since seeks aren't allowed on a pipe, it fails with "gbak: ERROR:expected backup description record".

Digging into the source code shows that the literal magic words "stdin" and "stdout" (rather than the Linux-provided /dev-based files) send the process down a different code path that works properly without seeks:

gbak -backup CL_123.gdb stdout | gbak -restore stdin CL_123.gdb   # WORKS

This feature is very thinly documented, and I hope this blog posting helps somebody else save some time. I've filed an issue in the Firebird Tracker asking that the docs be clarified.