Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

ttsession (1)

Name

ttsession - the ToolTalk message server

Synopsis

ttsession [-hNpsStv] [-E|-X] [-a level] [-d display] [-c [command]]

Description

ttsession(1)                   ToolTalk Commands                  ttsession(1)



NAME
       ttsession - the ToolTalk message server

SYNOPSIS
       ttsession [-hNpsStv] [-E|-X] [-a level] [-d display] [-c [command]]

DESCRIPTION
       The ttsession utility is the ToolTalk message server.  This background
       process must be running before any messages can be sent or received.
       Each message server defines a session.

       The message server has no user interface and typically runs in the
       background, started either by the user's .xinitrc file or automatically
       by any program that needs to send or receive a message.

OPTIONS
       The following options are available:

          -a level
                Set the server authentication level.  The following level
                string values are supported:

                   unix    The sender and receiver must have the same user ID.

                   des     The underlying RPC calls use AUTH_DES.

                   gss     The underlying RPC calls use RPCSEC_GSS.

                           For gss, additional options may be specified after
                           an immediately following comma in a comma separated
                           (without spaces) list of suboptions and keyword-
                           attribute pairs:

                                protect={access,integrity,privacy}
                                Specify the GSS service type. If no service
                                type is specified, protect=access is assumed.

                                     protect=access
                                     means the GSS mechanism is used to verify
                                     that clients have the credentials of the
                                     user that started ttsession.

                                     protect=integrity
                                     means the GSS mechanism is used to verify
                                     integrity of the data transmitted between
                                     ttsession and its clients. pro-
                                     tect=integrity implies protect=access

                                     protect=privacy
                                     means the Gss mechanism is used to pro-
                                     vide privacy against the data transmitted
                                     between ttsession and its clients. pro-
                                     tect=integrity implies protect=access.

                                mechanism=<mechanism name>
                                Use the named security mechanism. If no mecha-
                                nism is specifierd, ttsession wil arbitrarily
                                choose one of the installed mechanisms

                                qop=<quality of protection>
                                Use the named quality of protection. If the
                                quality of protection is not specified, the
                                default for the mechanism is used.

                   EXAMPLE

                   To specify GSS authentication using the kerberos_v5 mecha-
                   nism and the GSS_KRB5_CONF_C_QOP_DES quality of protection,
                   start ttsession as:

                   ttsession -a gss,mechanism=kerberos_v5,qop=GSS_KRB5_CONF_C_QOP_DES

                   This assumes that the kerberos_v5 mechanism is installed.

                   Security options can be overridden on a systemwide basis
                   via the file /etc/default/ttsession (ttsession_file(4)).

             -c [command]
                   Start a process tree session and run the given command.
                   The ttsession utility sets the environment variable TT_SES-
                   SION to the name of this session.  Any process started with
                   this variable in the environment defaults to being in this
                   session.  If command is omitted, ttsession invokes the
                   shell named by the SHELL environment variable.  Everything
                   after -c on the command line is used as the command to be
                   executed.

             -d display
                   Specify an X Windows display.  The ToolTalk session will
                   consist of those applications displaying on the named dis-
                   play.  The default display is identified by the DISPLAY
                   environment variable.

             -E    Read in the types from the Classing Engine database.  If
                   neither -E nor -X is given, -X is assumed.

             -h    Write a help message to standard error that describes the
                   command syntax of ttsession, and exit.

             -N    Maximize the number of clients allowed to connect to (in
                   other words, open procids in) this session by attempting to
                   raise the limit of open file descriptors.  The precise num-
                   ber of clients is system-dependent; on some systems this
                   option may have no effect.  On Solaris 2.6 and later,
                   ttsession always maximizes the number of clients, so there
                   is no need to specify this option.

             -o allow_unauth_types_load=<yes|no>
                   By default calls to tt_session_types_load(3) in the
                   ToolTalk API will fail with TT_ERR_ACCESS.  The system wide
                   default in this regard  may be changed via ttses-
                   sion_file(4). The behavior for a particular ttsession may
                   be changed via this option, if and only if the ttses-
                   sion_file(4) has not "locked" per-ttsession changes to this
                   option.

             -p    Write the name of a new process tree session to standard
                   output, and then fork a background instance of ttsession to
                   manage this new session.

             -s    Silent.  Do not write any warning messages to standard
                   error.

             -S    Do not fork a background instance to manage the ttsession
                   session.

             -t    Turn on trace mode.  See ASYNCHRONOUS EVENTS for how to
                   turn tracing on and off during execution.  Tracing displays
                   the state of a message when it is first seen by ttsession.
                   The lifetime of the message is then shown by showing the
                   result of matching the message against type signatures
                   (dispatch stage) and then showing the result of matching
                   the message against any registered message patterns (deliv-
                   ery stage).  Any attempt to send the message to a given
                   process is also shown together with the success of that
                   attempt.

             -v    Write the version number to standard output and exit.

             -X    Read in the types from the XDR format databases.  (Default)

OPERANDS
       None.

STDIN
       Not used.

INPUT FILES
       The XDR format databases listed by the -X option are serialized
       ToolTalk data structures of an unspecified format, except that it is
       the same as the format of tt_type_comp(1) output files.

       The file /etc/default/ttsession (ttsession_file(4)) can be used to
       change the system-wide behavior of the ttsession process depending on
       the contents of the file.

ENVIRONMENT VARIABLES
       The following environment variables affect the execution of ttsession:

          CEPATH         In Classing Engine mode, this variable tells the
                         Classing Engine where to find the databases that con-
                         tain ToolTalk types.  See ce_db_build(1).

          DISPLAY        If TT_SESSION is not set and DISPLAY is set, then the
                         value of DISPLAY will be used by all ToolTalk clients
                         to identify the ttsession process serving their X
                         display.  If no such process is running, the ToolTalk
                         service will auto-start one.

                         If ttsession is run with the -d option and DISPLAY is
                         not set, ttsession sets DISPLAY to be the value of
                         the -d option for itself and all processes it forks.
                         This helps ToolTalk clients to find the right X dis-
                         play when they are auto-started by ttsession.

          LANG           Provide a default value for the internationalization
                         variables that are unset or null.  If LANG is unset
                         or null, the corresponding value from the implementa-
                         tion-specific default locale will be used.  If any of
                         the internationalization variables contains an
                         invalid setting, the utility behaves as if none of
                         the variables had been defined.

          LC_ALL         If set to a non-empty string value, override the val-
                         ues of all the other internationalization variables.

          LC_MESSAGES    Determine the locale that is used to affect the for-
                         mat and contents of diagnostic messages written to
                         standard error and informative messages written to
                         standard output.

          NLSPATH        Determine the location of message catalogues for the
                         processing of LC_MESSAGES.

          TT_ARG_TRACE_WIDTH
                         Specify the number of bytes of argument and context
                         values to write when in trace mode.  The default is
                         to print the first 40 bytes.

          TTPATH         In XDR mode, a colon-separated list of directories
                         that tells ToolTalk where to find the ToolTalk types
                         databases. See tt_type_comp(1).

          TTSESSION_CMD
                         Specify the shell command to be used by all ToolTalk
                         clients for auto-starting ttsession.

       The ttsession utility creates the following variable when it invokes
       another process:

          TT_FILE        When ttsession invokes a tool to receive a message,
                         it copies the file attribute (if any) of the message
                         into this variable, formatted in the same manner as
                         returned by the tt_message_file(3) function.

          TT_SESSION     The ttsession utility uses this variable to communi-
                         cate its session ID to the tools that it starts.  The
                         format of the variable is implementation specific.
                         If this variable is set, the ToolTalk client library
                         uses its value as the default session ID.

          TT_TOKEN       Inform the ToolTalk client library that it has been
                         invoked by ttsession, so that the client can confirm
                         to ttsession that it started successfully.  The for-
                         mat of the variable is implementation specific.

       A tool started by ttsession must ensure that the TT_SESSION and
       TT_TOKEN are present in the environment of any processes it invokes.

RESOURCES
       None.

ASYNCHRONOUS EVENTS
       The ttsession utility reacts to two signals.  If it receives the
       SIGUSR1 signal, it toggles trace mode on or off (see the -t option).
       If it receives the SIGUSR2 signal, it rereads the types file.  The
       ttsession utility takes the standard action for all other signals.

STDOUT
       When the -v option is used, ttsession writes the version number in an
       unspecified format.  When -p is used, ttsession writes the name of a
       new process tree session.

STDERR
       Used only for diagnostic messages and the help message written by the
       -h option.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       When the -c child process exits, ttsession exits with the status of the
       exited child.  Otherwise, the following exit values are returned:

          0   Normal termination.  Without the -c or -S options, a zero exit
              status means ttsession has successfully forked an instance of
              itself that has begun serving the session.

          1   Abnormal termination.  The ttsession utility was given invalid
              command line options, was interrupted by SIGINT, or encountered
              some internal error.

          2   Collision.  Another ttsession was found to be serving the ses-
              sion already.

CONSEQUENCES OF ERRORS
       The ttsession utility takes the standard action for all signals.

APPLICATION USAGE
       Since everything after -c on the command line is used as the command to
       be executed, -c should be the last option.

       Tracing is helpful for seeing how messages are dispatched and deliv-
       ered, but the output may be voluminous.

EXAMPLES
       None.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/tooltalk |
       +---------------+------------------+
       |Stability      | Committed        |
       +---------------+------------------+

SEE ALSO
       tt_type_comp(1), tttrace(1), tt_message_file(3), ttsession_file(4).




ToolTalk 1.3                     1 March 1996                     ttsession(1)