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.
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.