gls(7) gls(7)
NAME
gls - character mapping STREAMS module
DESCRIPTION
gls is a STREAMS module for use by the GLS subsystem. It is used to
perform translations between the representation of characters passed
to/from a STREAMS device, and their representation in the rest of the
system.
The gls module must be pushed on a stream immediately above the
device interface. Once gls has been pushed on a stream, it must be
loaded with one or more character translation tables by means of a
GLSLOAD ioctl call (see below). In order for translation to be
switched on, a loaded table must be selected by means of a GLSSELECT
ioctl call. Normally, all this is done by the user process
glsstty(1).
Up to 16 translation tables may be loaded at any one time; however,
the total space occupied by tables may not exceed 8K bytes. Space
occupied by loaded tables not selected by any process may be released
automatically if a table could not otherwise be loaded due to lack of
space.
A translation table is contained in a file generated by codesio(1).
The first structure in the table is of type codesetnamet (defined
in /usr/include/gls/codesio.h ). This structure contains elements
that identify the translation table source file by its device number
and inode number. This pair of numbers is used internally by gls to
identify a particular translation table, and is referred to below as
a table's codeid.
Certain ioctl command messages, generated by the ISTR ioctl request
are recognised by gls; other messages are passed transparently to the
neighbouring STREAMS module or driver. These commands take the
general form:
struct strioctl strioctl;
. . .
strioctl.iccmd = command;
strioctl.ic_timeout = 0;
. . .
retval = ioctl(fd, I_STR, &strioctl);
The following commands are understood:
GLSLOAD
Load a translation table pointed to by strioctl.icdp whose
length is strioctl.iclen.
7/91 Page 1
gls(7) gls(7)
If successful, the command returns zero. Otherwise, -1 is
returned with errno set to indicate the cause of the error as
follows:
[EINVAL] strioctl.iclen was not big enough to contain the
smallest possible table.
[EFAULT] The table's codeid is zero.
[EEXIST] A table with the same codeid is already loaded.
[ENOSPC] The maximum permitted number of tables are already
loaded.
[ENOMEM] There is not enough memory to store this table.
[E2BIG] Internal STREAMS error; the number of data bytes
received in the ioctl message was not equal to that
specified by strioctl.iclen. This error will
normally only occur if the message has been tampered
with in some way by a module higher up the stream.
[ENOEXEC] There is a format error in the table. Additional
information regarding the nature of the this error
may be obtained by means of a GLSENQUIRE command.
GLSSELECT
Select a previously loaded translation table. strioctl.icdp
should point to a structure of type codesetnamet and
strioctl.iclen should be set to its length; the codeid
elements (see above) of this structure define the table to be
selected. If the codeid elements are zero, gls reverts to
"transparent mode" and no translations are performed.
If successful, the call returns zero and members of the
codesetnamet structure will be overlaid by details relating
to the previously selected table. Otherwise, -1 is returned
with errno set to indicate the cause of the error as follows:
[EINVAL] strioctl.iclen not equal to sizeof(codesetnamet).
[ENXIO] The requested table is not currently loaded.
GLSCURRENT
Return the codeid of the currently selected translation table.
strioctl.icdp should point to a structure of type
codesetnamet and strioctl.iclen should be set to zero. A
returned codeid value of zero indicates that there is no
currently selected table and the module is thus in "transparent
mode" .
Page 2 7/91
gls(7) gls(7)
If successful, the call returns zero and members of the
codesetnamet structure will be overlaid by details relating
to the currently selected table. Otherwise, -1 is returned
with errno set to indicate the cause of the error as follows:
[EINVAL] strioctl.iclen not equal to zero.
GLSUNLOAD
Release the storage occupied by a previously loaded translation
table. strioctl.icdp should point to a structure of type
codesetnamet and strioctl.iclen should be set to its length;
the codeid elements of this structure define the table to be
unloaded.
If successful, the command returns zero. Otherwise, -1 is
returned with errno set to indicate the cause of the error as
follows:
[EINVAL] strioctl.iclen not equal to sizeof(codesetnamet).
[EFAULT] The table's codeid is zero.
[ENXIO] The requested table is not currently loaded.
[EBUSY] Another process has this table selected.
GLSENQUIRE
Return additional status information relating to a previous
GLSLOAD request. strioctl.icdp should point to an object of
the form
short loadstatus[2];
and strioctl.iclen should be set to zero.
If successful, the call returns zero and elements of the
loadstatus[] array will contain the requested information as
follows:
loadstatus[1] GLSLOAD error code.
loadstatus[0] Translation table offset where the error was
detected.
Otherwise, -1 is returned with errno set to indicate the cause
of the error as follows:
[EINVAL] strioctl.iclen not equal to zero.
7/91 Page 3
gls(7) gls(7)
The following table lists possible GLSLOAD error code values
that may be returned in loadstatus[1], together with their
meanings. For codes marked with *, the location of the error
is indicated by the value returned in loadstatus[0].
0 No error.
1 The codesin array is too big (Bad ct_insize?).
2 The string array is too big (Bad ct_strsize?).
3 The index in the ct_out array exceeds the string array.
4 There is a hole in the string array, or two of the
strings overlap.
5 One of the strings in the string array overflows the
array.
9 Can't grab some temp test space.
10* The pointer has a value that is not zero and status is
zero.
11* The pointer is out of range.
12* Not a header.
13* This entry is not being used consistently; i.e., a non-
headed not within a header, a pointer not in a header and
a header not being used by a pointer.
14* This header is within another header.
15* This header has a negative pointer.
16* The differences between the pointer and value fields of
this header are not >= 1.
17* The header size exceeds the size of the table.
18* Found a non header entry that is already in use.
GLSTIMEOUT
Set the timeout value for multi-character inputs. This is the
length of time that gls will wait for the next character in a
multi-character sequence to be received from the device driver.
strioctl.icdp should point to an object of the form:
Page 4 7/91
gls(7) gls(7)
long timeoutval;
and strioctl.iclen should be set to sizeof(long). timeoutval
should be set to the required timeout value.
Timeouts are measured in system clock ticks; i.e., on a 50Hz
system, setting timeoutval to 50 yields a timeout value of 1
second. A timeout value of 0 turns off timeout processing.
If successful, the command returns zero and timeoutval is
overlaid with the previous timeout value. Otherwise, -1 is
returned with errno set to indicate the cause of the error as
follows:
[EINVAL] strioctl.iclen not equal to sizeof(long).
FILES
/usr/lib/codeset/$LANG/$TERM
Character translation tables for language $LANG, terminal
$TERM.
SEE ALSO
codesio(1), glscnv(1), glsstty(1).
7/91 Page 5