__tcsetcp() — Set 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 __tcsetcp(int fildes, size_t termcplen, const struct __termcp *termcpptr);
General description
The __tcsetcp() function sets (or changes) the terminal session code page information contained in the termcp structure.
- 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.
Use the __tcsetcp() function to send new code page information to the data conversion point in order to change the data conversion environment for the terminal session. This function is used with terminal devices that support the “forward code page names only” Code Page Change Notification (CPCN) capability. The z/OS UNIX pseudotty (pty) device driver supports this capability.
For terminal sessions that use the z/OS UNIX pty device driver, the data conversion point is the application that uses the master pty device. An example data conversion point is the z/OS UNIX rlogin server. Here, rlogin uses CPCN functions to determine the ASCII source and/or EBCDIC target code pages to use for the conversion of the terminal data. During its processing of the __tcsetcp() function, the pty device driver applies the __termcp structure once the pty outbound data queue is drained. When this occurs, the pty input data queue is also flushed and a TIOCXPKT_CHCP packet exception event is generated if extended packet mode is enabled (PKTXTND is set in the termios structure) to notify the application using the master pty that the code page information has been changed. The master pty application can then use the __tcgetcp() function to retrieve the new code page information and establish a new data conversion environment.
The __tcsetcp() function is supported by both the master and slave pty device drivers, however, CPCN functions first must be enabled by the application that uses the master pty; enabling CPCN functions is performed by the system during the initial __tcsetcp() invocation against the master pty device. Once the __tcsetcp() function is performed against the master pty then it may be subsequently issued against the slave pty.
- __tccp_flags
- Flags. The following symbols are defined as bitwise distinct
values. Thus, __tccp_flags is the bitwise inclusive-OR of these symbols:
- Symbol
- Meaning
- _TCCP_BINARY
- Use _TCCP_BINARY to notify the data conversion point to stop
data conversion. If this flag is set, the source and target code page
names (__tccp_fromname and __tccp_toname respectively) are not changed
from their current values.
Attention: Use this option carefully. Once the data conversion is disabled the z/OS UNIX Shell cannot be used until the data conversion is re-enabled, using valid code pages for the terminal session.
- _TCCP_FASTP
- Use _TCCP_FASTP to indicate to the data conversion point (for example, rlogin) that the data conversion specified by the source and target code page names can be performed locally to the 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 the local data conversion tables and perform all data conversion using the local tables instead of using iconv() in subsequent conversions. This provides for better-performing data conversion.
- __tccp_fromname
- The source code page name; typically this is the ASCII code
page name. __tccp_fromname is a NULL-terminated string with a maximum
length of _TCCP_CPNAMEMAX, including the NULL (\00) character.
__tccp_fromname is case-sensitive.
- __tccp_toname
- The target code page name; typically this is the EBCDIC code
page name. __tccp_toname is a NULL-terminated string with a maximum
length of _TCCP_CPNAMEMAX, including the NULL (\00) character.
__tccp_toname is case-sensitive.
When __tcsetcp() is issued against the slave pty from a process in a background process group, SIGTTOU processing is as follows:
Processing for SIGTTOU | Expected Behavior |
---|---|
Default or signal handler | The SIGTTOU signal is generated. The function is not performed. __tcsetcp() returns -1 and sets errno to EINTR. |
Ignored or blocked | The SIGTTOU signal is not sent. The function continues normally. |
Returned value
If successful, __tcsetcp() returns 0.
- Error Code
- Description
- EBADF
- fildes is not a valid open file descriptor.
- EINTR
- A signal interrupted the call.
- EINVAL
- The value of termcplen was invalid.
- EIO
- The process group of the process issuing the function is an orphaned, background process group, and the process issuing the function is not ignoring or blocking SIGTTOU.
- ENODEV
- One of the following error conditions exist:
- CPCN functions have not been enabled.
The __tcsetcp() function must be issued against the master pty before any CPCN function can be issued against the slave pty.
- The terminal device driver does not support the “forward code page names only” CPCN capability.
- CPCN functions have not been enabled.
- ENOTTY
- The file associated with fildes is not a terminal device.
Example
#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(STDIN_FILENO,sizeof(mytermcp),&mytermcp))== -1)
perror("__tcgetcp() error");
else {
if (rv== _CPCN_NAMES) {
if (_TCCP_BINARY == (mytermcp.__tccp_flags & _TCCP_BINARY))
printf("Binary mode is in effect. No change made.\n");
else {
strcpy(mytermcp.__tccp_fromname,"IBM-850");
if (__tcsetcp(STDOUT_FILENO,sizeof(mytermcp),&mytermcp)!=0)
perror("__tcsetcp() error");
else
printf("ASCII code page changed to IBM-850.\n");
} /*not binary mode */
} /* _CPCN_NAMES */
} /* __tcgetcp success */
close(cterm_fd);
} /* controlling terminal established */
} /* main */
ASCII code page changed to IBM-850.