PORTS(4) PORTS(4)
NAME
ports - event ports file system
SYNOPSIS
o/ports [ -abcdi ] [ -q n ] [ -m mnt ]
DESCRIPTION
Ports provides text event delivery through its file inter-
face. It serves a directory with a post file that can be
used to post events. By default it mounts itself at /mnt/ui
unless flag -m is used to request mounting at mnt or flag -i
is used to request reaching the client through standard
input. Flags -abc are similar to those of mount(1).
Each write(2) on the post file is considered an event.
Events are supposed to be small enough to fit in a single
write, and they are handled as strings by ports. All events
should terminate with a new-line character. Multiple events
can be written together.
To listen for events, additional files may be created in the
directory served. Each file created represents a listener
for events. Once created, a regular expression in the format
supported by regex(2) must be written to the file, to pro-
gram it to listen for matching events. Events written to
post but not matching this regular expression will be
ignored (for this file). The regular expression can be
changed by further writes, but it will not affect events
already queued for delivery.
Each read request for a listener file will return a single
event by default. This can be changed by writing `multi' to
the file. In this case, all queued events that fit in the
read buffer will be delivered for a single request (without
splitting events between multiple reads).
Events are queued up to a maximum of 128 events (or n if -q
is given in the command line). Should the queue become full
(due to a slow event reader client), old events will be dis-
carded.
Note that listener files do not need to be open during the
entire process. That is, an application may create a lis-
tener file, close it, reopen it, write a regular expression,
close it, reopen it, and loop reading events. This is done
so to simplify the use of ports from shell scripts and to
admit protocols like Op.
When a program does not read events for more than one
minute, and the queue for the listener file is full, it is
PORTS(4) PORTS(4)
considered an error and the listener file is removed.
If a file with name unsent is created, events not posted to
any other file will be delivered to it. This file can be
used to detect events not received by anyone else.
SOURCE
/usr/octopus/port/ports.b
SEE ALSO
plumber(8)