vty_server Special File

Purpose

The virtual terminal server (vty_server or vts) is an AIX® device driver used to create a tty-style connection from the partition on which the virtual terminal server is running to a virtual terminal (not a virtual terminal server) on another partition.

Description

The vty has a controller side (vty server) and a worker side (vty). The vty server is opened and used by special programs such as mkvterm. The vty is opened and used by shells such as ksh. The data path is bidirectional.

vts_ioctl

The vts_ioctl command is called via the device switch table when an application calls ioctl with a file descriptor that was returned from a successful open of a vts port. vts_ioctl performs specialized control operations on the port.

Syntax

struct vts_ioctl {
		void *vi_buffer;			/* pointer to user's buffer */
		int vi_bufsize;			/* size of user's buffer */
		int vi_offset;				/* offset into data */
		int vi_result;				/* bytes transferred */
};

The vi_buffer parameter is a pointer to a buffer in user space. The vi_bufsize parameter specifies the size of the buffer. For VTS_READ_CLCS and VTS_READ_PARTNER, data is moved from the vts driver into the buffer specified by vi_buffer. For VTS_WRITE_PARTNER, data is pulled from the buffer specified by vi_buffer and moved into the vts driver.

The vi_offset parameter is used only for VTS_READ_CLCS. An application can make multiple VTS_READ_CLCS ioctl calls; the driver may have more data to transfer to the application than will fit in the buffer that is specified by the vi_buffer parameter.

The vi_offset is set to 0 for the first FTS_READ_CLCS. This causes the driver to query PHYP for the current list of possible CLCs. The first sequence of the CLCs is moved into user space. Each CLC is separated by a new line and the last CLC is terminated by a null. A count of the number of bytes moved into user space (excluding the terminating null) is stored in vi_result.

The application determines how the data is processed (for example, the application may save the data in a linked list). vi_result is then added to vi_offset and another VTS_READ_CLCS is performed. This causes the driver to move the next set of CLCs into the application's buffer. This sequence of operations continues until zero is returned in vi_result.

A sequence of VTS_READ_CLCS calls results in a sequence of CLCs separated by new lines and terminated by a null. The following are the possible error conditions:

EIO

A driver call to PHYP returned with an error.

ENOMEM

No memory is available to hold the CLC list.

EPERM

The copyin or copyout failed.

A VTS_READ_PARTNER call returns the value that was passed on the last successful VTS_WRITE_PARTNER call. If the vts is not currently connected, a null string is returned. The only possible errors are errors that are returned by copyin or copyout routines.

The VTS_WRITE_PARTNER call creates and ends connections. The following are possible errors when ending a connection:

ENXIO

The vts is not currently connected.

EIO

The H_FREE_VTERM call to PHYP returned H_HARDWARE. This usually indicates that there is a problem with PHYP or that the partition connection failed.

EINVAL

The H_FREE_VTERM call to PHYP returned H_PARAMETER. This usually indicates a driver problem.

To create a connection, the buffer must contain a CLC that was passed from VTS_READ_CLCS. The CLC can contain the ending new line, which is removed. The following are possible errors:

EBUSY

The vts is already connected. Use VTS_READ_PARTNER to determine where the vts is connected, or use VTS_WRITE_PARTNER with a null name to end the connection.

EINVAL

The CLC that was passed is not in the list of valid connections for this vts. EINVAL is also returned if the H_REGISTER_VTERM call to PHYP returns H_PARAMETER.

Note: If a reconfiguration has occurred, the list of valid CLCs may have changed.

EIO

The H_REGISTER_VTERM call to PHYP returned H_PARAMETER. This may be due to a failed PHYP.