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) );

Arguments:

fd

The file descriptor for the device that you want to read from; see modem_open().

buf

A pointer to a buffer where the function can store the data.

bufsize

The size of the buffer, in bytes.

quiet

The maximum time to wait for more input after receiving at least one characters, in tenths of a second.

timeout

The maximum time to wait for any input, in tenths of a second.

flags

Flags that you can use to filter and map received characters; any combination of:

MODEM_ALLOWCASE — preserve the 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. If an automatic login script may be presented with an arbitrary text screen before the login prompt, you can use this flag to discard all but the login line, reducing the possibility of false matches.

cancel

NULL, or a callback that's called whenever the quiet time period expires while waiting for more input.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Note: This function is in libc.a, but not in libc.so (in order to save space).

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 the given timeout, modem_read() returns -1.

When at least one character has been received, modem_read() returns if the flow of incoming characters stops for at least the quiet time period. If the buffer isn't large enough, modem_read() discards any incoming characters that won't fit in it. The function terminates the string in buf with a null character.

If you provide a cancel function, it's called once each quiet time period while waiting for input. If this function returns a nonzero value, modem_read() returns -1 immediately and sets errno to ETIMEDOUT. You can use the cancel function as a callback in a graphical dialer that needs to support a cancel button to stop a script (see modem_script()).

Returns:

Zero for success, or -1 on failure (errno is set).

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 Neutrino

Safety:
Cancellation point	Yes
Interrupt handler	No
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.