posixipc(n) 1.0 posixipc "posixipc Package for Tcl access to POSIX IPC mechanisms"

Name

posixipc - Accessing POSIX IPC as a Tcl channel

Table Of Contents

Synopsis

Description

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.

Commands

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.

mq Command

The mq command is also a namespace ensemble command whose sub-commands provide access to POSIX message queue mechanisms.

mq open ?options? mqname ?access? ?permissions?

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.

-maxmsg count

The maximum number of messages that may be queued. If not specified, a system default value is used. The maximum value of count is also controlled by system specific configuration.

-msgsize len

The maximum length, in bytes, of any message. If not specified, a system default value is used. The maximum value of len is also controlled by system specific configuration.

The following options are read / write and may be supplied to the open command or may be accessed as configuration options.

-priority priority_number

The default message priority as a non-negative number. If not specified, the default priority is 0. Messages are placed on the message queue in decreasing order of priority.

The following options are read only and can only be read as configuration options:

-curmsgs

The number of messages currently in the queue.

-lastpriority

The message priority of the last received message.

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:

r

Open the message queue for reading only. The message queue must already exist. This is the default if access is not specified.

r+

Open the message queue for reading and writing. The message queue must already exist.

w

Open the message queue for writing only. Create the message queue if it does not already exist.

w+

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.

RDONLY

Open the message queue for reading only.

WRONLY

Open the message queue for writing only.

RDWR

Open the message queue for both reading and writing.

BINARY

Configure the opened channel with the -translation binary option.

CREAT

Create the message queue if it does not already exist.

EXCL

If CREAT is also specified, an error is returned if the message queue already exists.

NONBLOCK

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.

mq unlink mqname

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.

mqname

The name of message queue. Message queue names must start with a slash (/) character and may not contain any other slash characters.

mq send chan msg ?priority?

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.

chan

A message queue channel token as returned from mq open. The channel must have been opened for writing.

msg

A message to be placed on the message queue.

priority

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.

mq receive chan ?varname?

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.

chan

A message queue channel token as returned from mq open. The channel must have been opened for reading.

varname

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.

shm Command

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.

shm open ?options? shmname ?access? ?permissions?

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.

-size bytes

The size of the shared memory in bytes. This option must be supplied if the shared memory object is to be created. This option is not required if an existing shared memory object is being opened nor can the size of an existing shared memory object be changed as part of opening it.

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:

r

Open the shared memory for reading only. The shared memory must already exist. This is the default if access is not specified.

r+

Open the shared memory for reading and writing. The shared memory must already exist.

w

Open the shared memory for writing only. Create the shared memory if it does not already exist.

w+

Open the shared memory for reading and writing. Create the shared memory 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 flags must be either RDONLY, WRONLY, or RDWR.

RDONLY

Open the shared memory for reading only.

WRONLY

Open the shared memory for writing only.

RDWR

Open the shared memory for both reading and writing.

BINARY

Configure the opened channel with the -translation binary option.

CREAT

Create the shared memory if it does not already exist.

EXCL

If CREAT is also specified, an error is returned if the shared memory already exists.

NONBLOCK

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 withthe process's file mode creation mask. The value of permissions defaults to 0666.

shm unlink shmname

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.

shmname

The name of shared memory object. Shared memory object names must start with a slash (/) character and may *not* contain any other slash characters.

See Also

chan, open

Keywords

IPC, POSIX