modem_read()

Read bytes from a file descriptor

Synopsis:

#include <sys/modem.h>

int modem_read( int fd,
                char* buf,
                int bufsize,
                int quiet,
                int timeout,
                int flags,
                int (*cancel)(void) );

Description:

The modem_read() function reads up to bufsize bytes from the device specified by the file descriptor, fd, and places them into the buffer pointed to by buf.

If no characters are received within timeout 1/10 of a second then modem_read() returns with -1.

When at least one character has been received, modem_read() returns if the flow of incoming characters stops for at least quiet 1/10 of a second. The number of characters saved in buf is returned.

The flags parameter can be used to filter and map received characters as follows:

Flag	Description
MODEM_ALLOWCASE	Preserve case of incoming characters. Without this flag all letters are mapped to lower case.
MODEM_ALLOWCTRL	Allow control characters. Without this flag control characters are discarded.
MODEM_ALLOW8BIT	Preserve the top bit of incoming characters. Without this flag the top bit is set to zero for all characters.
MODEM_LASTLINE	Discard all previously received characters when a newline is received followed by more characters. Without this flag, buf may contain multiple lines. If an automatic login script may be presented with an arbitrary text screen before the login prompt this flag can be used to discard all but the login line reducing the possibility of false matches.

If a cancel function is provided, it's called once each quiet 1/10 of a second while waiting for input. If this function returns a nonzero value, the read returns immediately with -1 and errno set to ETIMEDOUT. The cancel function can be used as a callback in a graphical dialer which needs to support a cancel button to stop a script (see modem_script()).

Returns:

Zero for success, or -1 on failure.

Errors:

EAGAIN: The O_NONBLOCK flag is set on this fd, and the process would have been blocked in trying to perform this operation.
EBADF: The argument fd is invalid, or the file isn't opened for reading.
EINTR: The readcond() call was interrupted by the process being signalled.
EIO: This process isn't currently able to read data from this fd.
ENOSYS: This function isn't supported for this fd.

Classification:

QNX 6

Safety:
Cancellation point	Yes
Interrupt handler	Yes
Signal handler	Read the Caveats
Thread	Read the Caveats

Caveats:

Depending on what you do in your cancel function, modem_read() may or not be signal handler or thread-safe.