tokn Special File

AIX Version 4 Files Reference

tokn Special File

Purpose

Provides access to the token-ring adapters by way of the token-ring device handler.

Description

The tokn character special file provides access to the token-ring device handler that provides access to a token-ring local area network. The device handler supports up to four token-ring adapters.

Usage Considerations

When accessing the token-ring device handler, the following should be taken into account:

Driver initialization and termination

The device handler may be loaded and unloaded. The device handler supports the configuration calls to initialize and terminate itself.

Special file support

Calls other than the open and close subroutines are discussed based on the mode in which the device handler is operating.

Subroutine Support

The token-ring device handler provides specific support for the open, close, read, write, and ioctl subroutines.

open and close Subroutines

The device handler supports the /dev/tokn special file as a character-multiplex special file. The special file must be opened for both reading and writing (O_RDWR). There are no particular considerations for closing the special file. The special file name used in an open call depends upon how the device is to be opened. The three types of special file names are:

/dev/tokn	Starts the device handler for the selected port, where the value of n is 0 <= n <= 7.
/dev/tokn/D	Starts the device handler for the selected port in Diagnostic mode, where the value of n is 0 <= n <= 7.
/dev/tokn/W	Starts the device handler for the selected port in Diagnostic Wrap mode, where the value of n is 0 <= n <= 7.

read Subroutine

Can take the form of a read, readx, readv, or readvx subroutine. For this call, the device handler copies the data into the buffer specified by the caller.

write Subroutine

Can take the form of a write, writex, writev, or writevx subroutine. For this call, the device handler copies the user data into a kernel buffer and transmits the data on the LAN.

ioctl Subroutine

The token-ring device handler supports the following ioctl operations:

CIO_GET_STAT	Returns current adapter and device handler status.
CIO_HALT	Halts a session and removes a network ID from the network ID table.
CIO_QUERY	Returns the current counter values, as defined in the /usr/include/sys/comio.h and /usr/include/sys/tokuser.h files.
CIO_START	Starts a session and registers a network ID.
IOCINFO	Returns a structure of device information to the user specified area. The `devtype` field is DD_NET_DH and the `devsubtype` field is DD_TR, as defined in the /usr/include/sys/devinfo.h file.
TOK_GRP_ADDR	Allows the setting of the active group address for the token-ring adapter.
TOK_FUNC_ADDR	Allows the setting of a functional address for the token-ring adapter.
TOK_QVPD	Returns adapter vital product data.
TOK_RING_INFO	Returns information about the token-ring device.

Error Conditions

The following error conditions may be returned when accessing the device handler through the dev/tokn special file:

EACCES	Indicates that permission to access the adapter is denied for one of the following reasons: Device has not been configured. Diagnostic mode open request denied. The call is from a kernel-mode process.
EAGAIN	Indicates that the transmit queue is full.
EBUSY	Indicates one of the following: The device is already opened in Diagnostic mode. The maximum number of opens has already been reached. The request is denied. The device is in use. The device handler cannot terminate.
EEXIST	Indicates that the device is already configured or the device handler is unable to remove the device from switch table.
EFAULT	Indicates that the an invalid address or parameter was specified.
EINTR	Indicates that the subroutine was interrupted.
EINVAL	Indicates one of the following: The parameters specified were invalid. The define device structure (DDS) is invalid. The device handler is not in Diagnostic mode.
ENOCONNECT	Indicates that the device has not been started.
ENETDOWN	Indicates that the network is down and the device handler is unable to process the command.
ENOENT	Indicates that there was no DDS available.
ENOMEM	Indicates that the device handler was unable to allocate required memory.
ENOMSG	Indicates that there was no message of desired type.
ENOSPC	Indicates that the network ID table is full or the maximum number of opens was exceeded.
EADDRINUSE	Indicates that the specified network ID is in use.
ENXIO	Indicates that the specified minor number was not valid.
ENETUNREACH	Indicates that the device handler is in Network Recovery mode and is unable to process the write operation.
EMSGSIZE	Indicates that the data is too large for the supplied buffer.

Implementation Specifics

This file functions with the token-ring Device Handler.

Related Information

Special Files Overview.

The close subroutine, open subroutine, read or readx subroutine, write or writex subroutine.