Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

19    IOS STDIO Reference

Low-Level Communications

Exploring Palm OS®

Overview ^TOP^

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 ^TOP^

cc_t Typedef ^TOP^

Purpose

Specifies a control character in a termios structure.

Declared In

SDK/posix/termios.h

Prototype

typedef unsigned char cc_t;

iovec Struct ^TOP^

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

iAddrP
Base address of the buffer.
iLen;
Length of the buffer.

Comments

All of the pointers in the array of iovec data structures must be in the same memory segment.

PollBox Struct ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 by IOSGetmsg() and IOSGetpmsg().
iLen
The length of the data currently in the iBufP buffer.
iBufP
A pointer to the buffer.

tcflag_t Typedef ^TOP^

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 ^TOP^

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 ^TOP^

Character Control Mode Constants ^TOP^

Purpose

Define constants that control character and flow modes for a connection. Used in the termios structure.

Declared In

SDK/posix/termios.h

Constants

Constant

Definition

CSIZE

Character sizes.

CS7

OR with CSIZE to specify 7-bit characters: CSIZE|CS7.

CS8

OR with CSIZE to specify 8-bit characters: CSIZE|CS8.

CSTOPB

Send two stop bits instead of the normal one.

CREAD

Enable the receiver.

PARENB

Enable transmit parity.

PARODD

Select odd parity. If this flag isn't set, and parity is enabled, parity is even.

HUPCL

If this flag is set, the line will be hung up after the last file descriptor accessing it is closed.

CLOCAL

If set, indicates a local line.

XLOBLK

Block layer output.

CTSFLOW

Enables CTS flow control.

RTSFLOW

Enables RTS flow control.

CRTSCTS (RTSFLOW | CTSFLOW)

Enables both CTS and RTS flow control.

IRDAENB

Enables IrDA encoding.

Input Control Mode Constants ^TOP^

Purpose

Define constants that specify input mode settings for connections. Used in the termios structure.

Declared In

SDK/posix/termios.h

Constants

Constant

Definition

IGNBRK

Ignore breaks.

BRKINT

Break sends an interrupt.

IGNPAR

Ignore characters with parity errors.

PARMRK

Mark parity errors.

INPCK

Enable input parity checking.

ISTRIP

Strip the high bit from received characters.

INLCR

Map newline to CR on input.

IGNCR

Ignore carriage returns.

ICRNL

Map CR to newline on input.

IUCLC

Map all upper-case characters to lower-case.

IXON

Enable software flow control on input.

IXANY

Any character received will restart input after flow control has disabled input.

IXOFF

Enables output software flow control.

Ioctl Command Constants ^TOP^

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

Constant

Definition

TIOCMGET

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.

TIOCGETA

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.

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.

TIOCSETA

Sets the device's communication settings to match those in the termios structure passed in iParam. This is the same as TCSETA.

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.

TCSBRK

Sets a break condition on the line. iParam is unused. This is the same as TIOCSBRK.

TIOCSBRK

Sets a break condition on the line. iParam is unused. This is the same as TCSBRK.

TIOCCBRK

Clears the break condition on the line. iParam is unused.

TIOCSDTR

Sets the DTR condition on the line. iParam is unused.

TIOCCDTR

Clears the DTR condition on the line. iParam is unused.

TIOCDRAIN

Blocks the calling thread until the transmit queue is empty. iParam is unused.

TCSETIRDAMODE

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.

Local Mode Constants ^TOP^

Purpose

Define local modes that can be specified in the termios structure.

Declared In

SDK/posix/termios.h

Constants

Constant

Definition

ISIG

Enable signals.

ICANON

Canonical input.

XCASE

Canonical upper/lower case.

ECHO

Enable echo.

ECHOE

Echo erase as backspace/space/backspace.

ECHOK

Echo newline after kill.

ECHONL

Echo newlines.

NOFLSH

Disable flush after interrupt or quit.

TOSTOP

Stop background processes that write to the connection.

IEXTEN

Implementation-defined extensions begin here.

Modulation Speed Constants ^TOP^

Purpose

Define the supported baud rates. Used in the termios structure.

Declared In

SDK/posix/termios.h

Constants

Constant

Definition

B0

0 bps.

B50

50 bps.

B75

75 bps.

B110

110 bps.

B134

134 bps.

B150

150 bps.

B200

200 bps.

B300

300 bps.

B600

600 bps.

B1200

1200 bps.

B1800

1800 bps.

B2400

2400 bps.

B4800

4800 bps.

B7200

7200 bps.

B9600

9600 bps.

B14400

14,400 bps.

B19200

19,200 bps.

B28800

28,800 bps.

B38400

38,400 bps.

B56000

56,000 bps.

B57600

57,600 bps.

B76800

76,800 bps.

B115200

115,200 bps.

B128000

128,000 bps.

B230400

230,400 bps.

B256000

256,000 bps.

B31250

31,250 bps. Used by MIDI.

NCC Constant ^TOP^

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 ^TOP^

Purpose

Define output control modes. These constants are used in the termios structure.

Declared In

SDK/posix/termios.h

Constants

Constant

Definition

OPOST

Enable post-processing of output.

OLCUC

Maps lower case to upper case on output.

ONLCR

Maps newlines to CR+NL on output.

OCRNL

Maps CR to newline on output.

ONOCR

No CR output when in column 0.

ONLRET

Newline performs a CR.

OFILL

Uses fill characters for delays.

OFDEL

Fills are DEL, otherwise NUL.

NLDLY

Newline delays.

NL0

Add this to NLDLY to choose the NL0 delay: NLDLY+NL0.

NL1

Add this to NLDLY to choose the NL1 delay: NLDLY+NL1.

CRDLY

Carriage return delays.

CR0

Add this to CRDLY to choose the CR0 delay: CRDLY+CR0.

CR1

Add this to CRDLY to choose the CR1 delay: CRDLY+CR1.

CR2

Add this to CRDLY to choose the CR2 delay: CRDLY+CR2.

CR3

Add this to CRDLY to choose the CR3 delay: CRDLY+CR3.

TABDLY

Tab delays.

TAB0

Add this to TABDLY to choose the TAB0 delay.

TAB1

Add this to TABDLY to choose the TAB1 delay.

TAB2

Add this to TABDLY to choose the TAB2 delay.

TAB3

Add this to TABDLY to choose the TAB3 delay.

BSDLY

Backspace delays.

BS0

Add this to BSDLY to choose the BS0 delay.

BS1

Add this to BSDLY to choose the BS1 delay.

VTDLY

Vertical tab delays.

VT0

Add this to VTDLY to choose the VT0 delay.

VT1

Add this to VTDLY to choose the VT1 delay.

FFDLY

Form feed delays.

FF0

Add this to FFDLY to choose the FF0 delay.

FF1

Add this to FFDLY to choose the FF1 delay.

Poll Mask Constants ^TOP^

Purpose

Define the events that can be polled for by IOSPoll().

Declared In

IOS.h

Constants

Constant

Definition

POLLIN

A non-priority message is available.

POLLPRI

A high-priority message is available.

POLLOUT

The stream is writable for non-priority messages.

POLLERR

An error message has arrived.

POLLHUP

A hangup has occurred.

POLLNVAL

The specified file descriptor isn't valid.

POLLRDNORM

A non-priority message is available.

POLLRDBAND

A priority (band > 0) message is available.

POLLWRNORM

Same as POLLOUT.

POLLWRBAND

A priority band exists and is writable.

POLLMSG

A signal message has reached the front of the queue.

Functions ^TOP^

IOSClose Function ^TOP^

Purpose

Closes the specified device.

Declared In

IOS.h

Prototype

status_t IOSClose(
    int32_t iFD 
)

Parameters

iFD
The file descriptor to close.

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 ^TOP^

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

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 ^TOP^

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

iFD
The file descriptor of the device.
iPath
The null-terminated pathname of the device.

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 ^TOP^

Purpose

Detaches a STREAMS-based file descriptor from the specified pathname.

Declared In

IOS.h

Prototype

status_t IOSDetach(
    const Char *iPath 
)

Parameters

iPath
The null-terminated pathname of the device.

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 ^TOP^

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.
errNone
No error.
iosErrCanceled
The operation was canceled.
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.

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 ^TOP^

Purpose

Receives a STREAMS message.

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:
RS_HIPRI
High priority
0
Normal, non-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


NOTE: The file descriptor must reference a STREAMS device.

IOSGetpmsg Function ^TOP^

Purpose

Receives a STREAMS message.

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:
MSG_HIPRI
High priority
MSG_BAND
Band priority
MSG_ANY
Any 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.


NOTE: The file descriptor must reference a STREAMS device.

IOSIoctl Function ^TOP^

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

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 ^TOP^

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 ^TOP^

Purpose

Creates an interprocess communication channel (called a "pipe").

Declared In

IOS.h

Prototype

status_t IOSPipe(
    int32_t oFD[2] 
)

Parameters

oFD
Two file descriptors.

Returns

Returns errNone if the operation succeeded. Otherwise returns an appropriate error code:

errNone
No error.
iosErrCanceled
The operation was canceled.
iosErrIOError
An I/O error occurred.
iosErrNoFileDescriptors
The caller has no free file descriptors left.
iosErrNoSessionEntry
The system is out of free file descriptors.
iosErrNotSupported
The device does not support this operation.

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.


IMPORTANT: Pipes are not supported in Palm OS Cobalt, but will be available in a future release.

IOSPoll Function ^TOP^

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 the iEvents member is ignored and the oRevents 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:

errNone
No error.
iosErrCanceled
The operation was canceled.
iosErrInvalidArg
One of the parameters is invalid.
iosErrIOError
An I/O error occurred.
iosErrNotSupported
The device does not support this operation.

Comments

IOSPoll() is only supported for STREAMS devices. File descriptor 0 is used to poll for pending user interface events.

IOSPutmsg Function ^TOP^

Purpose

Sends a STREAMS message.

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:
RS_HIPRI
High priority
0
Normal, non-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.


NOTE: The file descriptor must reference a STREAMS device.

IOSPutpmsg Function ^TOP^

Purpose

Sends a STREAMS message.

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:
MSG_HIPRI
High priority
MSG_BAND
Band 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.


NOTE: The file descriptor must reference a STREAMS device.

IOSRead Function ^TOP^

Purpose

Reads data from a device.

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 ^TOP^

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


NOTE: The scattered data buffer portions must all be in the same memory segment.

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 ^TOP^

Purpose

Writes data to a device.

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 ^TOP^

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


NOTE: The scattered data buffer must all be in the same memory segment.

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 ^TOP^

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 ^TOP^

Purpose

Creates a new PollBox.

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 ^TOP^

Purpose

Destroys an existing PollBox.

Declared In

PollBox.h

Prototype

void PbxDestroy(
    PollBox *pbx 
)

Parameters

pbx
A pointer to the PollBox to destroy.

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 ^TOP^

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 ^TOP^

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 ^TOP^

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

pbx
The PollBox to use for the event loop.

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 ^TOP^

PbxCallback Function ^TOP^

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.