Hide Forgot
The readline man page is woefully inaccurate, and I just wasted a little while by believing it. Eventually I just read the info manual. Suggestion: remove the man page, or at least put a notice saying "it's way out of date", the way that many GNU manpages do.
Which parts? The function appears to work when it's called as the man page suggests that it should be....
If you compare the manpage and the info page, you'll find that there are some significant differences. The two that bit me were: 1. In the manpage it says that readline() returns EOF when Ctrl+D is pressed at the beginning of a line. In the info page it says (correctly) that it returns NULL in this case. 2. In the manpage it says that the default keybinding for Newline/Enter places the line you've just typed in the history. In the info page it says that you have to call add_history() to make this happen.
I've just sent mail to the listed contact for the man page, asking for suggestions on which course of action to take.
Chet tells me that an updated version will be in readline 4.2, and until then it's best to add a note to the man page about it being out-of-date. This will be done in readline-4.1-