posixipc - Accessing POSIX IPC as a Tcl channel
This manpage describes the posixipc package which is a "C" based Tcl extension that provides Tcl channel drivers for POSIX message queue and shared memory IPC mechanisms.
The posixipc package consists of one command, posixipc, which is a namespace ensemble command consisting of two sub-commands. The sub-command names are mq and shm. These commands are also exported from the package namespace, so the invocation of the sub-commands can be shortened by importing them into the current namespace. For example:
package require posixipc namespace import ::posixipc::mq
will allow access to the mq command without the posixipc command word (i.e. mq rather than posixipc mq). For simplicity in the following descriptions, we will use the shortened command invocations.
The mq command is also a namespace ensemble command whose sub-commands provide access to POSIX message queue mechanisms.
The mq open command opens a POSIX message queue and returns a channel identifier that may be used in future invocations of I/O commands such as chan, puts, and close.
The options argument supplies options that control the details of how the message queue is created. The following options are write only and must be supplied to the open command, but may be read as channel configuration options (i.e. using the chan configure or fconfigure commands. These options only have effect if the message queue is created by the mq open command.
The following options are read / write and may be supplied to the open command or may be accessed as configuration options.
The following options are read only and can only be read as configuration options:
The mqname argument is the name of message queue. Message queue names must start with a slash (/) character and may not contain any other slash characters.
The access argument, if present, indicates the way in which the message queue is to be accessed. This argument may be specified in one of two different forms. In the first form, access may have any of the following values:
Open the message queue for reading only. The message queue must already exist. This is the default if access is not specified.
Open the message queue for reading and writing. The message queue must already exist.
Open the message queue for writing only. Create the message queue if it does not already exist.
Open the message queue for reading and writing. Create the message queue if it does not already exist.
All legal access values above may have the character b added as the second or third character in the value to indicate that the opened channel should be configured as if with the fconfigure -translation binary option, making the channel suitable for reading or writing of binary data.
In the second form, access consists of a list of any of the following flags, all of which have the standard POSIX meanings. Exactly one flag must be either RDONLY, WRONLY, or RDWR.
Open the message queue for reading only.
Open the message queue for writing only.
Open the message queue for both reading and writing.
Configure the opened channel with the -translation binary option.
Create the message queue if it does not already exist.
If CREAT is also specified, an error is returned if the message queue already exists.
Prevent the process from blocking in subsequent I/O operations.
If the message queue is created as part of opening it, permissions is used to set the permissions for the new message queue in conjunction with the process's file mode creation mask. The value of permissions defaults to 0666.
The mq unlink command removes the message queue named, mqname, from the system. Message queues persist in the system until explicitly unlinked or upon system reboot. The queue is actually destroyed when all processes that have open descriptors for the queue close those descriptors referring to the queue.
The name of message queue. Message queue names must start with a slash (/) character and may not contain any other slash characters.
The mq send command operates outside of the buffering of the Tcl virtual channel system and directly sends msg to the message queue associated with chan. If specified, the message is sent with priority priority. If the priority argument is not specified, the message is sent with the value of the -priority configuration option. This command is provided for applications where message priority changes frequently, such as on a message by message basis. Normal access to the message queue is intended to be provided by Tcl I/O commands such as chan.
A message queue channel token as returned from mq open. The channel must have been opened for writing.
A message to be placed on the message queue.
An optional unsigned number specifying the priority of the message. If priority is not specfied, then the current value of the -priority configuration option is used as the message priority.
The mq receive command returns the next highest priority message from the message queue given by chan. This command operates outside of the buffering of the Tcl virtual channel system. If the variable, varname, is specified, the priority of the message is set as the variable's value. This command is provided for those applications where message priority changes frequently, such as on a message by message basis. The message priority of the last received message is also available as the -lastpriority configuration option.
A message queue channel token as returned from mq open. The channel must have been opened for reading.
An optional variable name where the value of the priority of the received message is set. The priority of the last received message is also available as the -lastpriority configuration option.
The shm command is also a namespace ensemble command whose sub-commands provide access to POSIX shared memory mechanisms. This command only supports POSIX named shared memory. Unnamed shared memory is not supported. Since it is intended that the memory is shared between multiple processes, it is necessary to have an exclusion mechanism to prevent processes interferring with each other. The underlying shared memory channel driver also uses a POSIX semaphore to insure exclusive access to the shared memory.
The shm open command opens a POSIX named shared memory object and returns a channel identifier that may be used in future invocations of I/O commands such as chan, puts, and close
The options argument supplies options that control the details of how the shared memory is created.
The shmname argument specifies the name of shared memory object. Shared memory names must start with a slash (/) character and may not contain any other slash characters.
The access argument, if present, indicates the way in which the shared memory is to be accessed. It may be specified in one of two forms. In the first form, access may have any of the following values:
All legal access values above may have the character b added as the second or third character in the value to indicate that the opened channel should be configured as if with the fconfigure -translation binary option, making the channel suitable for reading or writing of binary data.
In the second form, access consists of a list of any of the following flags, all of which have the standard POSIX meanings. Exactly one flags must be either RDONLY, WRONLY, or RDWR.
If the message queue is created as part of opening it, permissions is used to set the permissions for the new message queue in conjunction withthe process's file mode creation mask. The value of permissions defaults to 0666.
The shm unlink command removes the shared memory object named, shmname, from the system. Shared memory objects persist in the system until explicitly unlinked or upon system reboot. The shared memory is actually destroyed when all processes that have open descriptors for the shared memory close those descriptors.
The name of shared memory object. Shared memory object names must start with a slash (/) character and may *not* contain any other slash characters.
chan, open
IPC, POSIX