CD_HALT_INPUT_REQ

Section: Communications Device Interface (CDI) (7)
Updated: 2008-10-31
Index Return to Main Contents

NAME

CD_HALT_INPUT_REQ - halt input

SYNOPSIS

This primitive consists of one M_PROTO(9) or M_PCPROTO(9) message block structured as follows:

typedef struct {
    cd_ulong cd_primitive;
    cd_ulong cd_disposal;
} cd_halt_input_req_t;
/* Actions to take with undelivered data */
#define CD_FLUSH        0x00    /* Discard undelivered data */
#define CD_WAIT         0x01    /* Attempt to deliver unsent
                                   data */
#define CD_DELIVER      0x02

DESCRIPTION

This user originated primitive requests that the input section be halted.

When a stream is enabled with CD_ENABLE_REQ(7), it can be used immediately for transmission. If the stream returns CD_AUTOALLOW in the cd_features field of the CD_INFO_ACK(7), the device automatically allows input and there is no need to call CD_ALLOW_INPUT_REQ(7) for the device. However, CD_HALT_INPUT_REQ will halt input on such a device.

In addition, if the input section is temporarily enabled with CD_READ_REQ(7), on a half-duplex communications device, then CD_HALT_INPUT_REQ will abort the read operation.

Parameters

This primitive contains the following parameters:

cd_primitive

Specifies the primitives type.

cd_disposal

Specifies how unsent messages are to be disposed. This field can be one of the following values:

CD_FLUSH: Discard undeliverable data. All data that is unsent at the time that the CD_DISABLE_REQ primitive is received will be discarded. Any data awaiting transmission the the device's write queue will be flushed.
CD_WAIT: Attempt to deliver unsent data. All data that is unsent at the time that the CD_DISABLE_REQ primitive is received the provider will attempt to send before acknowledging the primitive. The provider will not wait for acknowledgment of sent messages.
CD_DELIVER: Deliver unsent data. All data that is unsent at the time that the CD_DISABLE_REQ primitive is received the provider will deliver before acknowledging the primitive. The provider will wait for acknowledgment of sent messages.

State

This primitive is valid in state CD_ENABLED, CD_INPUT_ALLOWED, or CD_READ_ACTIVE. The new state is CD_ENABLED.

RESPONSE

This primitive requires that the CD provider acknowledge receipt of the primitive as follows:

Successful: Upon success, the provider will acknowledge receipt of the primitive with the CD_OK_ACK(7) primitive. The new state is CD_ENABLED.

Unsuccessful (non-fatal errors): Upon failure, the provider will acknowledge receipt of the primitive with the CD_ERROR_ACK(7) primitive with the error inidcated in the primitive. The new state remains unchanged.

ERRORS

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CD_BADDISPOSAL]: Invalid disposal parameter.
[CD_BADPRIM]: Unrecognized primitive.
[CD_DISC]: Disconnected.
[CD_EVENT]: Protocol-specific event occurred.
[CD_FATALERR]: Device has become unusable.
[CD_NOTSUPP]: Primitive not supported by this device.
[CD_OUTSTATE]: Primitive was issued from an invalid state.
[CD_PROTOSHORT]: M_PROTO block too short.
[CD_SYSERR]: UNIX system error.

Note: if the communications device is in the CD_ENABLED state and the input section is not active, the CD_HALT_INPUT_REQ primitive should be ignored and no non-fatal error generated.

FILES

HISTORY

The Communications Device Interface first appeared in SVR 4[1].

CONFORMANCE

This interface conforms to CDI with Gcom extensions.

REFERENCES

[1]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[3]: Advanced Programming in the UNIX®Environment, 15th edition, December 1997, (Reading, Massachusetts), W. R. Stevens, Addison Wesley. [ISBN 0-201-56317-7]