[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Kernel and Subsystems, Volume 2

CIO_HALT ddioctl Communications PDH Operation

Purpose

Removes the network ID of the calling process and cancels the results of the corresponding CIO_START operation.

Syntax

#include <sys/device.h>
#include <sys/comio.h>


int ddioctl
(
devno, op, parmptr,
devflag, chan, ext)
dev_t devno;
int op;
struct session_blk * parmptr;
ulong devflag;
int chan, ext;

Parameters

devno Specifies major and minor device numbers.
op Specifies the entry point for the CIO_HALT operation.
parmptr Points to a session_blk structure. This structure is defined in the /usr/include/sys/comio.h file.
devflag Specifies the DKERNEL flag. This flag is set by kernel-mode processes and cleared by calling user-mode processes.
chan Specifies the channel number assigned by the device handler's ddmpx routine.
ext Indicates device-dependent.

Description

The CIO_HALT operation must be supported by each physical device handler in the communication I/O subsystem. This operation should be issued once for each successfully issued CIO_START operation. The CIO_HALT operation removes the caller's network ID and undoes all that was affected by the corresponding CIO_START operation.

The CIO_HALT operation returns immediately to the caller, before the operation completes. If the return indicates no error, the PDH builds a CIO_HALT _DONE status block upon completion. For kernel-mode processes, the status block is passed to the associated status function (specified at open time). For user-mode processes, the block is placed in the associated status or exception queue.

session_blk Parameter Block

For the CIO_HALT operation, the ext parameter can be a pointer to a session_blk structure. This structure is defined in the /usr/include/sys/comio.h file and contains the following fields:

Field Description
status Indicates the status of the port. This field may contain additional information about the completion of the CIO_HALT operation. Besides the status codes listed here, device-dependent codes can be returned:
CIO_OK
Indicates the operation was successful.
CIO_INV_CMD
Indicates an invalid command was issued.
CIO_NETID_INV
Indicates the network ID was not valid.

The status field is used for specifying immediately detectable errors. If the status is CIO_OK, the CIO_HALT _DONE status block should be processed to determine whether the halt completed without errors.

netid Contains the network ID to halt.

Execution Environment

A CIO_HALT operation can be called from the process environment only.

Return Values

In general, communication device handlers use the common return codes defined for an operation. However, device handlers for specific communication devices may return device-specific codes. The common return codes for the CIO_HALT operation are the following:

Return Code Description
ENXIO Indicates an attempt to use an unconfigured device.
EFAULT Indicates an incorrect address was specified.
EINVAL Indicates an incorrect parameter was specified.
EBUSY Indicates the maximum number of opens was exceeded.
ENODEV Indicates the device does not exist.

Related Information

The ddioctl device driver entry point in AIX 5L Version 5.2 Technical Reference: Kernel and Subsystems Volume 1.

The CIO_GET_STAT ddioctl Communications PDH Operation, CIO_START ddioctl Communications PDH Operation.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]