Overview
This chapter covers the IOS STDIO API. IOS STDIO provides an architecture for communicating directly at a low level with any kind of communications device for which there are drivers available, through a standard, unified API. Using IOS STDIO calls, it's possible to write communications applications that can use any network or serial connection, without having to write custom code for each type of interface.
IOS STDIO also provides the pollbox—an automated event polling mechanism that can ease development of event-driven applications such as communications software.
IOS STDIO Data Structures and Types
cc_t Typedef
Purpose
Specifies a control character in a termios
structure.
Declared In
SDK/posix/termios.h
Prototype
typedef unsigned char cc_t;
iovec Struct
Purpose
The IOSReadv()
and IOSWritev()
functions pass an array of iovec
data structures that represent the scattered data array to read from or write to. Each iovec
structure contains a pointer and a byte length.
Declared In
IOS.h
Prototype
struct iovec { MemPtr iAddrP; int32_t iLen; };
Fields
Comments
All of the pointers in the array of iovec
data structures must be in the same memory segment.
PollBox Struct
Purpose
Describes a PollBox. Most of the fields in this structure are private.
Declared In
PollBox.h
Prototype
typedef struct PollBox { struct pollfd *pollTab; uint16_t count; uint16_t capacity; uint16_t flags; uint16_t nCallbacks; PbxInfo *infoTab; } PollBox;
Fields
-
pollTab
- A table of
pollfd
structures, one per file descriptor that's in the PollBox. -
count
- The number of file descriptors in the PollBox.
-
capacity
- The current maximum number of file descriptors the PollBox can contain; reserved for system use.
-
flags
- Internal flags; reserved for system use.
-
nCallbacks
- The number of file descriptors that have callbacks assigned; reserved for system use.
-
infoTab
- A table of
PbxInfo
structures, one per file descriptor. Reserved for system use.
pollfd Struct
Purpose
The IOSPoll()
function passes an array of pollfd
data structures that represent the file descriptors and events to poll. Each pollfd
structure contains a file descriptor, a mask of events to check, and a mask of events that are selected.
Declared In
IOS.h
Prototype
struct pollfd { int32_t fd; int16_t events; int16_t revents; };
Fields
-
fd
- The file descriptor to poll.
-
events
- The events in which you're interested.
-
revents
- On return, contains the events which have occurred.
speed_t Typedef
Purpose
Specifies the baud rate for a connection in a termios
structure.
Declared In
SDK/posix/termios.h
Prototype
typedef unsigned long speed_t;
strbuf Struct
Purpose
The IOSPutmsg()
, IOSPutpmsg()
, IOSGetmsg()
, and IOSGetpmsg()
functions pass two strbuf
structures which represent the data and control buffers. Each strbuf
contains the maximum length of the buffer, the length of the data currently in the buffer, and a pointer to the data buffer.
Declared In
IOS.h
Prototype
struct strbuf { int32_t iMaxLen; int32_t iLen; MemPtr iBufP; };
Fields
-
iMaxLen
- The maximum number of bytes that the
iBufP
buffer can hold. Only used byIOSGetmsg()
andIOSGetpmsg()
. -
iLen
- The length of the data currently in the
iBufP
buffer. -
iBufP
- A pointer to the buffer.
tcflag_t Typedef
Purpose
Specifies control modes for a connection in a termios
structure.
Declared In
SDK/posix/termios.h
Prototype
typedef unsigned long tcflag_t;
termios Struct
Purpose
Contains all the settings for a communications channel.
Declared In
SDK/poxis/termios.h
Prototype
struct termios { tcflag_t c_iflag; tcflag_t c_oflag; tcflag_t c_cflag; tcflag_t c_lflag; char c_line; cc_t c_cc[NCC]; speed_t c_ispeed; speed_t c_ospeed; };
Fields
-
c_iflag
- Input modes.
-
c_oflag
- Output modes.
-
c_cflag
- Control modes.
-
c_lflag
- Local modes.
-
c_line
- Line discipline.
-
c_cc[NCC]
- Control characters.
-
c_ispeed
- Input speed.
-
c_ospeed
- Output speed.
IOS STDIO Constants
Character Control Mode Constants
Purpose
Define constants that control character and flow modes for a connection. Used in the termios
structure.
Declared In
SDK/posix/termios.h
Constants
Input Control Mode Constants
Purpose
Define constants that specify input mode settings for connections. Used in the termios
structure.
Declared In
SDK/posix/termios.h
Constants
Ioctl Command Constants
Purpose
Define commands that can be sent to IOSIoctl()
. This list is not exhaustive; that is, some drivers will implement additional commands, and some may not implement all of these. This is simply a list of common constants.
Declared In
SDK/posix/sys/ttycom.h
SDK/posix/termios.h
Constants
Returns all of the modem's status flags. The IOSIoctl()
function's iParam
output pointer should point to an integer variable which will be filled with the status on return.
Returns a termios
structure describing the device's settings. The iParam
parameter should point to a termios
struct, which will be filled in with the current device settings. This is the same as TCGETA
.
Returns a termios
structure describing the device's settings. The iParam
parameter should point to a termios
struct, which will be filled in with the current device settings. This is the same as TIOCGETA
.
Sets the device's communication settings to match those in the termios
structure passed in iParam
. This is the same as TCSETA
.
Sets the device's communication settings to match those in the termios
structure passed in the iParam
parameter. This is the same as TIOCSETA
.
Sets a break condition on the line. iParam
is unused. This is the same as TIOCSBRK
.
Sets a break condition on the line. iParam
is unused. This is the same as TCSBRK
.
Blocks the calling thread until the transmit queue is empty. iParam
is unused.
Selects read or write mode on IrDA devices. iParam
should point to an integer 0 value to select write mode, or to a non-zero value to select read mode.
Returns all of the modem's status flags. The |
|
Returns a |
|
Returns a |
|
Sets the device's communication settings to match those in the |
|
Sets the device's communication settings to match those in the |
|
Sets a break condition on the line. |
|
Sets a break condition on the line. |
|
Blocks the calling thread until the transmit queue is empty. |
|
Selects read or write mode on IrDA devices. |
Local Mode Constants
Purpose
Define local modes that can be specified in the termios
structure.
Declared In
SDK/posix/termios.h
Constants
Modulation Speed Constants
Purpose
Define the supported baud rates. Used in the termios
structure.
Declared In
SDK/posix/termios.h
Constants
NCC Constant
Purpose
Defines the number of control characters that can be specified in the termios
structure.
Declared In
SDK/posix/termios.h
Constants
-
NCC
- This constant specifies the size of the array of control characters in the
termios
structure.
Output Control Mode Constants
Purpose
Define output control modes. These constants are used in the termios
structure.
Declared In
SDK/posix/termios.h
Constants
Poll Mask Constants
Purpose
Define the events that can be polled for by IOSPoll()
.
Declared In
IOS.h
Constants
Functions
IOSClose Function
Purpose
Declared In
IOS.h
Prototype
status_t IOSClose( int32_t iFD )
Parameters
Returns
Returns errNone
if the operation was successful; otherwise the operation failed and an appropriate error code is returned. Possible errors are:
-
errNone
- No Error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- The specified file descriptor is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not reference an open device.
Comments
Any thread in a process may close a file descriptor opened by that process.
When a process terminates, all associated file descriptors are closed automatically. However, since there is a limit on how many file descriptors can be opened at once, it is a good idea to close them as you're finished using them.
IOSFastIoctl Function
Purpose
Performs one of a variety of control functions on a device.
Declared In
IOS.h
Prototype
int32_t IOSIoctl( int32_t iFD, int32_t iRequest, int32_t iSendLen, MemPtr iSendP, int32_t iRecvLen, MemPtr iRecvP, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device.
-
→ iRequest
- The command to be executed on the device.
-
→ iSendLen
- The length of the send buffer.
-
→ iSendP
- A pointer to the send buffer.
-
→ iRecvLen
- The length of the receive buffer.
-
→ iRecvP
- A pointer to the receive buffer.
-
← oErrno
- The error code.
Returns
Returns the number of bytes actually received. If an error occurred, returns -1, and the actual error code in oErrno
.
Comments
FastIoctl()
calls are only supported by certain Palm OS internal devices.
The maximum send and receive buffer lengths are determined by the driver.
IOSFattach Function
Purpose
Attaches a STREAMS-based file descriptor to a given pathname.
Declared In
IOS.h
Prototype
status_t IOSFattach( int32_t iFD, const Char *iPath )
Parameters
Returns
Returns errNone
if the operation succeeded; otherwise returns one of the following error codes:
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrDeviceInUse
- The device is already opened and cannot be shared.
-
iosErrDeviceNotFound
- The device pathname is not a valid IOS device.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support this operation.
Comments
iFD
must reference an open STREAMS-based file descriptor. All subsequent operations on iPath
will operate on the STREAMS file until the STREAMS file is detached by calling IOSFdetach()
. iFD
can be attached to more than one path.
IOSFdetach Function
Purpose
Detaches a STREAMS-based file descriptor from the specified pathname.
Declared In
IOS.h
Prototype
status_t IOSDetach( const Char *iPath )
Parameters
Returns
Returns errNone
if the operation succeeded; otherwise returns one of the following error codes:
-
errNone
- No error.
-
iosErrAccess
- The caller does not have the required permissions for this operation.
-
iosErrCanceled
- The operation was canceled.
-
iosErrDeviceNotFound
- The device pathname is not a valid IOS device.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrNotSupported
- The device does not support this operation.
Comments
This function detaches a STREAMS-based file descriptor from the path to which it was associated by a prior call to IOSFattach()
. The iPath
parameter points to the pathname to the attached STREAMS file.
IOSFnctl Function
Purpose
Performs one of a variety of operations on an open file descriptor.
Declared In
IOS.h
Prototype
int32_t IOSFnctl( int32_t iFD, int32_t iRequest, int32_t iArg, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device.
-
→ iRequest
- The operation to perform on the file descriptor.
-
→ iArg
- Any additional information required by the command.
-
← oErrno
- The error code.
Returns
Returns a non-negative request-specific value if successful. Returns -1 if an error occurred; the specific error code is returned in oErrno
.
Comments
The allowed commands are defined in the fcntl.h
header file. Only F_GETFL
and F_SETFL
are supported in the current release of Palm OS.
IOSGetmsg Function
Purpose
Declared In
IOS.h
Prototype
int32_t IOSGetmsg( int32_t iFD, struct strbuf *oCtlPtrP, struct strbuf *oDataPtrP, int32_t oFlags, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device from which a STREAMS message is to be received.
-
← oCtlPtrP
- A pointer to a
strbuf
into which the control part of the message is to be stored. -
← oDataPtrP
- A pointer to a
strbuf
into which the data part of the message is to be stored. -
← oFlags
- The message's priority:
-
← oErrno
- The error code indicating the result of the operation.
Returns
A return value of 0 indicates that a full message was successfully received. A return value of MORECTL
indicates that more control information is waiting to be read. Similarly, a return value of MOREDATA
indicates that more data is waiting to be read. A return value of MORECTL
| MOREDATA
indicates that more of both control information and data are waiting to be read.
Comments
IOSGetpmsg Function
Purpose
Declared In
IOS.h
Prototype
int32_t IOSGetpmsg( int32_t iFD, struct strbuf *oCtlPtrP, struct strbuf *oDataPtrP, int32_t *oBand, int32_t oFlags, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device from which a STREAMS message is to be received.
-
← oCtlPtrP
- A pointer to a
strbuf
into which the control part of the message is to be stored. -
← oDataPtrP
- A pointer to a
strbuf
into which the data part of the message is to be stored. -
↔ ioBand
- The message's priority band.
-
↔ ioFlags
- The message's priority:
-
← oErrno
- The error code indicating the result of the operation.
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support this operation.
Returns
A return value of 0 indicates that a full message was successfully received. A return value of MORECTL
indicates that more control information is waiting to be read. Similarly, a return value of MOREDATA
indicates that more data is waiting to be read. A return value of MORECTL
| MOREDATA
indicates that more of both control information and data are waiting to be read.
Comments
You may choose to retrieve only high-priority messages by setting the integer pointed to by ioFlags
to MSG_HIPRI
and the integer pointed to by ioBand
to 0. In this case, IOSGetpmsg()
will only process the next message if it is a high-priority message.
Similarly, you can opt to only process a message from a given priority band by setting the integer pointed to by ioFlags
to MSG_BAND
and the integer pointed to by ioBand
to the priority band of interest. In this case, IOSGetpmsg()
will only process the next message if it is in a priority band equal to, or greater than, the integer pointed to by ioBand
, or if it is a high priority message.
If you just want to fetch the next message off the queue, set the integer pointed to by ioFlags
to MSG_ANY
and the integer pointed to by ioBand
to 0.
On return, ioBand
and ioFlags
are set to indicate the priority band and priority of the message returned.
IOSIoctl Function
Purpose
Performs one of a variety of control functions on a device.
Declared In
IOS.h
Prototype
int32_t IOSIoctl( int32_t iFD, int32_t iRequest, int32_t iParam, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device.
-
→ iRequest
- The command to be executed on the device.
-
→ iParam
- Any additional information required by the command.
-
← oErrno
- The error code.
Returns
Returns a non-negative request-specific value if successful. Returns -1 if an error occurred; the specific error code is returned in oErrno
.
IOSOpen Function
Purpose
Opens a device for reading, writing, and control.
Declared In
IOS.h
Prototype
int32_t IOSOpen( const Char *iPath, int32_t iFlags, status_t *oErrno )
Parameters
-
→ iPath
- The null-terminated pathname of the device to open.
-
→ iFlags
- A bitwise OR of flags specifying the access privileges requested:
-
O_RDONLY
- Open for read only.
-
O_WRONLY
- Open for write only.
-
O_RDWR
- Open for both reading and writing.
-
← oErrno
- On return, contains the error code indicating success or failure. Possible errors are:
-
errNone
- No error.
-
iosErrAuthFailed
- The caller is not authorized to use the requested device.
-
iosErrCanceled
- The operation was canceled.
-
iosErrDevice
- The device is already opened and cannot be shared.
-
iosErrDeviceNotFound
- The requested device could not be found.
-
iosErrInvalidArg
- Invalid argument.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNoFileDescriptors
- The system is out of free file descriptors.
-
iosErrNoSessionEntry
- The system is out of free file descriptors.
-
iosErrNotSupported
- This operation is not supported by the specified device.
Returns
Returns a file descriptor for the opened device. Returns -1 if an error occurred; the specific error code is stored in oErrno
.
Comments
The pathname must not span multiple memory segments.
IOSPipe Function
Purpose
Creates an interprocess communication channel (called a "pipe").
Declared In
IOS.h
Prototype
status_t IOSPipe( int32_t oFD[2] )
Parameters
Returns
Returns errNone
if the operation succeeded. Otherwise returns an appropriate error code:
Comments
The IOSPipe()
function creates an I/O interprocess communication channel called a pipe, returning two file descriptors in oFD
[0] and oFD
[1]. These file descriptors are STREAMS-based and are opened for both reading and writing.
Reading from oFD
[0] returns data written to oFD
[1] and vice versa.
IOSPoll Function
Purpose
Examines a set of file descriptors to see if any of them are ready for I/O.
Declared In
IOS.h
Prototype
status_t IOSPoll( struct pollfd iFDs[], int32_t iNfds, int32_t iTimeout, int32_t *oNfds )
Parameters
-
→ iFDs
- An array of
pollfd
structures, each containing a file descriptor to be polled, the events to poll for, and the events that actually occurred. - If the value of the file descriptor field in a
pollfd
structure is less than zero, then theiEvents
member is ignored and theoRevents
member is set to 0 on return. -
→ iNfds
- The number of
pollfd
structures in the array. -
→ iTimeout
- The number of milliseconds to wait before timing out. If -1,
IOSPoll()
blocks indefinitely. If the timeout is 0,IOSPoll()
does not block. -
← oNfds
- The number of file descriptors selected.
Returns
Returns errNone
if the operation is successful; otherwise returns an error code:
Comments
IOSPoll()
is only supported for STREAMS devices. File descriptor 0 is used to poll for pending user interface events.
IOSPutmsg Function
Purpose
Declared In
IOS.h
Prototype
status_t IOSPutmsg( int32_t iFD, const struct strbuf *iCtlPtrP, const struct strbuf *iDataPtrP, int32_t iFlags )
Parameters
-
→ iFD
- The file descriptor of the device to which the STREAMS message is to be sent.
-
→ iCtlPtrP
- A pointer to a
strbuf
containing the control portion of the message. -
→ iDataPtrP
- A pointer to a
strbuf
containing the data portion of the message. -
→ iFlags
- The message's priority:
Returns
Returns errNone
if the operation was successful. Otherwise returns an error code:
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support reading data.
Comments
The IOSPutmsg()
function creates a message containing either the control portion from iCtlPtrP
or the data portion from iDataPtrP
(or both) and sends it to the STREAMS device specified by the file descriptor iFD
, using the priority specified by iFlags
.
IOSPutpmsg Function
Purpose
Declared In
IOS.h
Prototype
status_t IOSPutpmsg( int32_t iFD, const struct strbuf *iCtlPtrP, const struct strbuf *iDataPtrP, int32_t iBand, int32_t iFlags )
Parameters
-
→ iFD
- The file descriptor of the device to which the STREAMS message is to be sent.
-
→ iCtlPtrP
- A pointer to a
strbuf
containing the control portion of the message. -
→ iDataPtrP
- A pointer to a
strbuf
containing the data portion of the message. -
iBand
- The priority band.
-
→ iFlags
- The message's priority:
Returns
Returns errNone
if the operation was successful. Otherwise returns an error code:
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support reading data.
Comments
The IOSPutmsg()
function creates a message containing either the control portion from iCtlPtrP
or the data portion from iDataPtrP
(or both) and sends it to the STREAMS device specified by the file descriptor iFD
, using the priority specified by iFlags
.
The iFlags
argument is a bit mask which must be either MSG_HIPRI
or MSG_BAND
. If iFlags
is 0, IOSPutpmsg()
fails and returns iosErrInvalidArg
. If a control part is specified and iFlags
is set to MSG_HIPRI
and iBand
is 0, a high-priority message is sent.
If iFlags
is set to MSG_HIPRI
and either no control part is specified or iBand
is non-zero, IOSPutpmsg()
fails and returns iosErrInvalidArg
.
If iFlags
is set to MSG_BAND
, then a message is sent in the priority band specified by iBand
. If a control part and data part are not specified and iFlags
is set to MSG_BAND
, no message is sent and errNone
is returned.
IOSRead Function
Purpose
Declared In
IOS.h
Prototype
int32_t IOSRead( int32_t iFD, MemPtr iBufP, int32_t iNbytes, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device from which data should be read.
-
→ iBufP
- A pointer to the memory buffer into which data should be read.
-
→ iNbytes
- The number of bytes to read from the device.
-
← oErrno
- On output, contains the result code indicating the error which occurred, or
errNone
if the data was read successfully.
Returns
Returns the number of bytes actually read, which may be lower than the number of bytes requested (if, for example, the end of the available data is reached). If an error occurred during the read operation, -1 is returned, and the error code is returned in the oErrno
parameter.
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support reading data.
-
iosErrBadFD
- The file descriptor is invalid or is not opened for reading.
IOSReadv Function
Purpose
Reads data from a device into a scattered data buffer.
Declared In
IOS.h
Prototype
int32_t IOSReadv( int32_t iFD, const struct iovec *iIovP, int32_t iIovCnt, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device from which data should be read.
-
→ iIovP
- A pointer to an array of
iIovCnt
iovec
structures indicating where the portions of the scattered data buffer are located. -
→ iIovCnt
- The number of entries in the
iIovP
. -
← oErrno
- On output, contains the result code indicating the error which occurred, or
errNone
if the data was read successfully.
Returns
Returns the number of bytes actually read, which may be lower than the number of bytes requested (if, for example, the end of the available data is reached). If an error occurred during the read operation, -1 is returned, and the error code is returned in the oErrno
parameter.
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support reading data.
-
iosErrBadFD
- The file descriptor is invalid or is not opened for reading.
Comments
This function attempts to read data from the device specified by the iFD
file descriptor into the scattered data buffer described by the iovec
structures passed in the iIovP
array. Each iovec
entry specifies the base address and length of each portion of the scattered buffer. Each buffer will be filled before moving on to the next one.
IOSWrite Function
Purpose
Declared In
IOS.h
Prototype
int32_t IOSWrite( int32_t iFD, MemPtr iBufP, int32_t iNbytes, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device to which data should be written.
-
→ iBufP
- A pointer to the memory buffer from which data should be written.
-
→ iNbytes
- The number of bytes to write to the device.
-
← oErrno
- On output, contains the result code indicating the error which occurred, or
errNone
if the data was written successfully.
Returns
Returns the number of bytes actually written. If an error occurred during the write operation, -1 is returned, and the error code is returned in the oErrno
parameter.
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support writing data.
-
iosErrBadFD
- The file descriptor is invalid or is not opened for writing.
IOSWritev Function
Purpose
Writes data to a device from a scattered data buffer.
Declared In
IOS.h
Prototype
int32_t IOSWritev( int32_t iFD, const struct iovec *iIovP, int32_t iIovCnt, status_t *oErrno )
Parameters
-
→ iFD
- The file descriptor of the device to which data should be written.
-
→ iIovP
- A pointer to an array of
iIovCnt
iovec
structures indicating where the portions of the scattered data buffer are located. -
→ iIovCnt
- The number of entries in the
iIovP
. -
← oErrno
- On output, contains the result code indicating the error which occurred, or
errNone
if the data was written successfully.
Returns
Returns the number of bytes actually written. If an error occurred during the write operation, -1 is returned, and the error code is returned in the oErrno
parameter.
-
errNone
- No error.
-
iosErrCanceled
- The operation was canceled.
-
iosErrInvalidArg
- One of the parameters is invalid.
-
iosErrIOError
- An I/O error occurred.
-
iosErrNotOpened
- The file descriptor does not correspond to an opened device.
-
iosErrNotSupported
- The device does not support writing data.
-
iosErrBadFD
- The file descriptor is invalid or is not opened for writing.
Comments
This function attempts to write data to the device specified by the iFD
file descriptor from the scattered data buffer described by the iovec
structures passed in the iIovP
array. Each iovec
entry specifies the base address and length of each portion of the scattered buffer. Each buffer will be completely written before moving on to the next one.
PbxAddFd Function
Purpose
Adds a file descriptor to a PollBox.
Declared In
PollBox.h
Prototype
status_t PbxAddFd( PollBox *pbx, int32_t fd, int16_t eventMask, PbxCallback *callback, void *context )
Parameters
-
→ pbx
- A pointer to the PollBox to which the file descriptor should be added.
-
→ fd
- The file descriptor to add to the PollBox.
-
→ eventMask
- A bitwise OR mask of the events to poll for.
-
→ callback
- A pointer to a callback handler that the PollBox will call when an event occurs on the file descriptor. You can specify
NULL
if your application does not require a callback. -
→ context
- A value that will be passed into the callback handler.
Returns
-
noErr
- The file descriptor was added successfully.
-
memErrNotEnoughSpace
- Not enough memory to add the file descriptor to the PollBox.
See Also
PbxRemoveFd()
, "Adding File Descriptors to Monitor"
PbxCreate Function
Purpose
Declared In
PollBox.h
Prototype
PollBox *PbxCreate( void )
Returns
Returns a pointer to the newly-created PollBox object. If an error occurred creating the PollBox, this function returns NULL
.
See Also
PbxDestroy()
, "Creating a PollBox"
PbxDestroy Function
Purpose
Declared In
PollBox.h
Prototype
void PbxDestroy( PollBox *pbx )
Parameters
Comments
PbxDestroy()
closes all file descriptors in the PollBox and frees any memory allocated by the PollBox.
See Also
PbxCreate()
, "Destroying a PollBox"
PbxPoll Function
Purpose
Polls all file descriptors in a PollBox for events that need processing.
Declared In
PollBox.h
Prototype
status_t PbxPoll( PollBox *pbx, int32_t timeout, int32_t *nReady )
Parameters
-
→ pbx
- The PollBox to poll.
-
→ timeout
- The number of milliseconds to wait for an event to occur. Specify 0 to return immediately if there are no events pending, or -1 to wait indefinitely.
-
← nReady
- The number of file descriptors with events pending, or
-1
if an error occurred.
Returns
On return, nReady
indicates the number of file descriptors that have events pending. Any of these events that have callbacks established have already had the callbacks run. If an error occurred during the poll operation, nReady
is set to -1, and a non-zero result is returned.
Comments
If there are no file descriptors in the PollBox, PbxPoll()
sets nReady
to 0 and returns zero.
Otherwise, this function blocks until one or more file descriptors in the box have events that were flagged as being of interest when they were added to the box, or until the timeout period expires. For each file descriptor that has events, the corresponding callback procedure (if one was specified when PbxAddFd()
was called) is called, and the number of file descriptors with events is returned in nReady
.
NOTE: If this function returns zero and sets
nReady
to zero, then there are either no file descriptors left in the PollBox or the timeout period expired. You can check which of these scenarios is the case by looking at the value of pbx->count;
if this is nonzero, then the timeout expired.
See Also
PbxCreate()
, PbxAddFd()
, "Polling for Events using a PollBox"
PbxRemoveFd Function
Purpose
Removes a file descriptor from a PollBox.
Declared In
PollBox.h
Prototype
void PbxRemoveFd( PollBox *pbx, int32_t fd )
Parameters
-
→ pbx
- The PollBox from which to remove the file descriptor
-
→ fd
- The file descriptor to remove from the PollBox.
See Also
PbxAddFd()
, "Removing a File Descriptor from the PollBox"
PbxRun Function
Purpose
Runs an event loop using a PollBox; this automatically calls PbxPoll()
for you repeatedly until there are no more file descriptors in the box, or until an unexpected error occurs.
Declared In
PollBox.h
Prototype
status_t PbxRun( PollBox *pbx )
Parameters
Returns
Returns 0 if the event loop terminated because there are no file descriptors left in the PollBox. If this value is non-zero, it is an error code indicating that something unexpected happened while processing the event loop.
Comments
The event loop is run by calling PbxPoll()
repeatedly with an infinite timeout. Your application can watch for user interface events by adding file descriptor 0 to the PollBox.
See Also
PbxPoll()
, PbxAddFd()
, PbxCreate()
, "Polling the Easy Way"
Application-Defined Functions
PbxCallback Function
Purpose
Called by a PollBox when an event occurs on a file descriptor.
Declared In
PollBox.h
Prototype
typedef void PbxCallback( struct PollBox *pbx, struct pollfd *pollFd, void *context )
Parameters
-
→ pbx
- The PollBox that is calling into your callback routine.
-
→ pollFd
- A
pollfd
structure indicating which file descriptor experienced an event, and which event or events occurred. -
→ context
- The context variable specified when your application called
PbxAddFd()
.
Comments
Implement this function to handle the event or events that have occurred, as described by the pollFd
structure.