__tcgetcp() — Get terminal code page names

Standards

Standards / Extensions C or C++ Dependencies
z/OS® UNIX both  

Format

#define _OPEN_SYS_PTY_EXTENSIONS
#include <termios.h>

int __tcgetcp(int fildes, size_t termcplen, struct __termcp *termcpptr);

General description

The __tcgetcp() function gets the terminal session code page information contained in the termcp structure and the Code Page Change Notification (CPCN) capability for the terminal file.

The following arguments are used:
fildes
The file descriptor of the terminal for which you want to get the code page names and CPCN capability.
termcplen
The length of the passed termcp structure.
termcpptr
A pointer to a __termcp structure.
__tcgetcp() stores the termcp information in a memory location pointed to by termcpptr. The return value contains the CPCN capability. The following CPCN capabilities are defined:
Symbol
Meaning
_CPCN_NAMES
Forward code page names only

Use the __tcsetcp() function to change the terminal session data conversion. The z/OS UNIX pseudotty device driver supports this CPCN capability.

_CPCN_TABLES
Forward code page names and tables

Use __tcsettables() to change the terminal session data conversion. The OCS remote-tty device driver supports this CPCN capability.

In the returned termcp structure, if the _TCCP_FASTP bit is set then the data conversion that is specified by the source and target code page names can be performed locally by the data conversion application. This is valid any time that a table-driven conversion can be performed. For example, the data conversion point (application) could use the z/OS UNIX iconv() service to build local data conversion tables and perform all data conversion using the local tables instead of using iconv() all in subsequent conversions. This provides for better-performing data conversion.

In the returned termcp structure, if the _TCCP_BINARY bit is set then no data conversion is being performed and the code page names contained in the termcp structure should be ignored.

__tcgetcp() can run in either a foreground or background process; however, if the process is in the background, a foreground process may subsequently change the terminal code pages.

Note: The __tcgetcp() function has a dependency on the level of the Enhanced ASCII Extensions. See Enhanced ASCII support for details.

Returned value

If successful, __tcgetcp() returns the termcp structure in a memory location pointed to by termcpptr. The return value contains the CPCN capability.

If unsuccessful, __tcgetcp() returns -1 and sets errno to one of the following values:
Error Code
Description
EBADF
fildes is not a valid open file descriptor.
EINVAL
The value of termcplen was invalid.
ENODEV
One of the following error conditions exist:
  • The terminal device driver does not support CPCN functions.
  • CPCN functions have not been enabled.

    For a z/OS UNIX pseudotty terminal device file, issue the __tcsetcp() function against the master pty first to enable CPCN support.

ENOTTY
The file associated with fildes is not a terminal device.

Example

The following example retrieves the current code pages used in the data conversion and CPCN capability. Here, the __tcgetcp() function is issued against a session using a pty terminal device; ISO8859-1 and IBM-1047 code pages are being used. 
#define _OPEN_SYS_PTY_EXTENSIONS
#include <unistd.h>
#include <stdio.h>
#include <fcntl.h>
#include <termios.h>

void main(void)
{
  struct __termcp mytermcp;
  int rv;
  int cterm_fd;

  if ((cterm_fd = open("/dev/tty",O_RDWR)) == -1)
    printf("No controlling terminal established.\n");
  else {
    if ((rv = __tcgetcp(cterm_fd,sizeof(mytermcp),&mytermcp))== -1)
      perror("__tcgetcp() error");
    else {
      if (_CPCN_NAMES == rv)
        printf("Forward Code Page Names Only.\n");
      else
        printf("Forward Code Page Names and Tables.\n");
      if (_TCCP_BINARY == (mytermcp.__tccp_flags & _TCCP_BINARY))
        printf("Binary mode is in effect.\n");
      else {
        printf("ASCII code page name is %s.\n",
                mytermcp.__tccp_fromname);
        printf("EBCIDC code page name is %s.\n",
                mytermcp.__tccp_toname);
      }
    }
    close(cterm_fd);
  }
}  /* main */
Output 
Forward code page names only.
ASCII code page name is ISO8859-1.
EBCDIC code page name is IBM-1047.

Related information