move info/ to doc/info

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 724 insertions, 0 deletions

diff --git a/doc/info/cmdipc.texinfo b/doc/info/cmdipc.texinfo
new file mode 100644
index 0000000..1ab3c22
--- /dev/null
+++ b/doc/info/cmdipc.texinfo
@@ -0,0 +1,724 @@
+\input texinfo   @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename cmdipc.info
+@settitle cmdipc
+@afourpaper
+@documentencoding UTF-8
+@documentlanguage en
+@finalout
+@c %**end of header
+
+
+@dircategory Interprocess communication
+@direntry
+* cmdipc: (cmdipc).                  System V and POSIX IPC from the command line
+@end direntry
+
+
+@copying
+Copyright @copyright{} 2014 Mattias Andrée
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end quotation
+@end copying
+
+@ifnottex
+@node Top
+@top cmdipc -- System V and POSIX IPC from the command line
+@insertcopying
+@end ifnottex
+
+@titlepage
+@title cmdipc
+@subtitle System V and POSIX IPC from the command line
+@author by Mattias Andrée (maandree)
+
+@page
+@c @center `'
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+
+
+@menu
+* Overview::                        Brief overview of @command{cmdipc}.
+* Invoking::                        Invocation of @command{cmdipc}.
+* Message Queues::                  Using message queue
+* Semaphores::                      Using semaphores
+* Shared Memory::                   Using shared memory
+* Mutexes::                         Using mutual exclusives
+* Conditions::                      Using conditions
+* Barriers::                        Using barriers
+* Shared Locks::                    Using shared locks
+* Rendezvous::                      Using rendezvous
+* GNU Free Documentation License::  Copying and sharing this manual.
+@end menu
+
+
+
+@node Overview
+@chapter Overview
+
+System V and POSIX interprocess communication
+from the command line. In addition to the primities
+shared memory, message queue and semaphores, this
+tool can from these primitives construct mutexes,
+conditions, barriers, shared locks and rendezvous.
+
+
+
+@node Invoking
+@chapter Invoking
+
+@command{cmdipc} have support for eight types
+of interprocess communication units: message
+queues, semaphores, shared memory, mutexes
+@footnote{Because of the nature of this program,
+mutexes are a bit degraded.}, conditions,
+barrers, shared locks and rendezvous. These
+are constructed from either the three System V
+interprocess communication primitives: message
+queues, semaphores and shared memory, or their
+POSIX variants. The type of interprocess
+communication unit to use is selected by the
+follow options, to use the POSIX variant rather
+than the System V variant add the option
+@option{-P} (@option{--posix}).
+
+@table @option
+@item -Q
+@itemx --mqueue
+Message queue.
+
+@item -S
+@itemx --semaphore
+Semaphore.
+
+@item -M
+@itemx --shm
+Shared memory.
+
+@item -X
+@itemx --mutex
+Mutually exclusive. (Mutex)
+
+@item -C
+@itemx --condition
+Condition.
+
+@item -B
+@itemx --barrier
+Barrier.
+
+@item -L
+@itemx --shared-lock
+Shared lock.
+
+@item -R
+@itemx --rendezvous
+Rendezvous.
+@end table
+
+To specify which instance of a unit to use,
+specify its key (not ID) with the @option{-k}
+(@option{--key}) option. If you do not have
+a key, your only option is to create one, but
+you can still create a unit with a specified
+key. To create a unit use the option @option{-c}
+(@option{--create}), this will be successful
+even if the key is already in use, in which
+case the unit will simply be opened. To fail
+if the key is already in use, use the option
+@option{-x} (@option{--exclusive}). @option{-x}
+can be used with or without @option{-c}, it
+is interpretation will does not depend on
+@option{-c}, @option{-c} is implied by
+@option{-x}. To remove a key, use the option
+@option{-r} (@option{--remove}).
+
+There are two additional options that are
+recognised. These cannot be used with any
+other optios.
+
+@table @option
+@item -h
+@itemx --help
+Print a list of all options.
+
+@item -f
+@itemx --ftok PATHNAME ID
+Print a key derived from an existing
+file and a project ID. The project ID
+is a integer between the values 0 and
+255, inclusively. The derived key is
+probable to be non-unique. This is a
+System V IPC function, and is not
+available, and are not necessary, for
+POSIX IPC.
+@end table
+
+The following options are recognised
+for interprocess communication units.
+
+@table @option
+@item -n
+@itemx --nonblocking
+Fail with exit value 2 if the unit
+is currently occupied and cannot be
+used without waiting.
+Not available for shared memory.
+
+@item -b
+@itemx --timeout SECONDS
+Not available for shared memory.
+Fail with exit value 2 if the unit
+is currently occupied and cannot be
+used without waiting for at most
+@code{SECONDS} seconds.
+
+For a non primitive unit, the
+time to live is reset when it enters
+its next state. This could mean
+that it could timeout anywhere
+between the specifed time and
+n times the specifed time when
+n is the number of steps in the
+action that can block, which with
+the current units is at most 3.
+
+@item -m
+@itemx --mode OCTAL
+Permission bits for the created
+unit.
+@end table
+
+
+
+
+@node Message Queues
+@chapter Message Queues
+
+Message queues are primitives and play well
+with other programs. Use of message queues
+are indicated by the @option{-Q} option.
+Message queues is a way to send short messages
+between program.
+
+The key for a System V message queue is an
+integer, and the key for a POSIX message queue
+is an ASCII string with NUL or slash between
+1 character and 254 characters long prefixed
+with a slash.
+
+Recognised options for System V message queues:
+
+@table @option
+@item -s
+@itemx --size SIZE
+The size of the queue. This is the total
+length of all message that can be fit into
+the queue before it starts blocking.
+
+@item -t
+@itemx --type TYPE
+When sending, a positive integer of the
+type associated with the message.
+
+When receiving, this allows you to
+control which types of messages are
+received. Zero means that any type is
+accepted, a positive value means that
+only the indicated type is allowed.
+If the value is negative, the first
+message of the lowest type that is
+at most the absolute value of the
+specifed value is received.
+@end table
+
+Recognised options for POSIX message queues:
+
+@table @option
+@item -s
+@itemx --size SIZE
+The maximum size of messages in the queue.
+
+@item -z
+@itemx --spool SIZE
+The size of the queue. This is the number
+of messages that can be fit into the queue
+before it starts blocking.
+
+@item -p
+@itemx --priority NASTYNESS
+The priority allows you to order messages
+in the queue. The highest priority message
+is received first. By default, messages
+are sent at the lowest priority, that is
+zero.
+@end table
+
+To receive a message, add the verb
+@option{receive}. To send a message,
+add the verb @option{send} followed
+by the message to send.
+
+
+
+@node Semaphores
+@chapter Semaphores
+
+Semaphores are primitives and play well
+with other programs. Use of semaphores
+are indicated by the @option{-S} option.
+Semaphores are primitive concurrency units
+that be used for many different things.
+Basically, a semaphore is an atomic counter
+that is never allowed to go below zero.
+
+The key for a System V semaphores is an
+integer, and the key for a POSIX semaphores
+is an ASCII string with NUL or slash between
+1 character and 254 characters long prefixed
+with a slash.
+
+The following options are recognised
+for semaphores:
+
+@table @option
+@item -i
+@itemx --initial VALUE
+You can select the value a semaphore should
+have when it is created. By default the value
+is zero.
+
+@item -d
+@itemx --delta DIFFERENCE
+When increasing or decreasing the value of
+the semaphore @option{--delta} can be used
+to select how much the value should change
+with. By default this is 1. Semaphores are
+atomic, you are guaranteed to either change
+the value exactly as much as specified or
+not all at.
+@end table
+
+The verbs @option{v} and @option{p} are
+used to increase or decrease the value of
+the semaphore, respectively. You can also
+set the exact value of the semaphore with
+the @option{set} verb which should be
+followed directly by the desired value.
+To read the current value use the verb
+@option{read}. @option{p} will block if
+the value of the semaphore would otherwise
+go below zero. You can also wait for the
+value of the semaphore to reach zero
+by using the @option{z} verb. POSIX
+semaphores does not have built in support
+for @option{z}, therefore when POSIX
+semaphores are used, the semaphore will
+be used as a spinlock. Keep in mind that
+spinlock are often suboptimal and it can
+miss that the semaphore's value reaches
+zero if it for a very short amount of
+time.
+
+
+
+@node Shared Memory
+@chapter Shared Memory
+
+Shared memory are primitives and play well
+with other programs. Use of shared memory
+are indicated by the @option{-M} option.
+Shared memory is a form of abstract file
+that can be used to store raw data between
+programs. It is highly recommended to create
+shared memory before any program starts
+using it.
+
+The key for a System V shared memory is an
+integer, and the key for a POSIX shared memory
+is an ASCII string with NUL or slash between
+1 character and 254 characters long prefixed
+with a slash.
+
+The following options are recognised
+for shared memory:
+
+@table @option
+@item -s
+@itemx --size
+When you create a shared memory you
+most specify how large, in bytes, the
+memory allocation should be. KB, MB,
+etc. are not recognised, only bytes.
+
+@item -l
+@itemx --length
+When you read shared memory you can
+specift how many bytes should be read.
+If this is left unspecified the entire
+shared memory, starting at the the
+selected offset, will be read.
+
+@item -o
+@itemx --offset
+When reading and writing shared memory,
+you specify how many bytes into the
+memory that the reading or writing should
+take place. By default the offset is zero.
+@end table
+
+To read the shared memory, use the verb
+@option{read}. To write, use the verb
+@option{write} followed by the data to
+write to the memory.
+
+
+
+@node Mutexes
+@chapter Mutexes
+
+Mutexes are implemented using semaphores.
+Actually, because of inherit limitations,
+mutexes are binary semaphores. These are
+fairly primitive and should hopefully
+interoperate nicely with other programs.
+A mutex, with the limitations we have,
+is a construct that lets you enter are
+guarded state that not be entered again,
+even recursively, before it has been left.
+Use of mutexes are indicated by the
+@option{-X} option.
+
+The key for a ``System V'' mutex is an
+integer, and the key for a ``POSIX'' mutex
+is an ASCII string with NUL or slash between
+1 character and 254 characters long prefixed
+with a slash.
+
+To enter a guarded state with a mutex,
+use the verb @option{enter}. Then leave
+it with @option{leave}.
+
+@*
+@cartouche
+@example
+create:
+    s := S(1)
+
+enter:
+    P(s)
+
+leave:
+    V(s)
+@end example
+@end cartouche
+
+
+
+@node Conditions
+@chapter Conditions
+
+A condition is a mutex with support for
+signalling. They are implemented using
+three semaphores. Just like with mutexes,
+you enter and leave guarded states with
+conditions. But conditions also allow
+to temporarily leave this state and
+wait for a signal continue and the
+re-enter the guarded state when it is
+not occupied. A signal, called
+notification, can only be sent from
+within a guarded state.
+Use of conditions are indicated by the
+@option{-C} option.
+
+The key for a ``System V'' condition is a
+integer-trio delimited by full stops. The
+key for a ``POSIX'' condition is a
+juxtaposition of three ASCII strings:
+no NUL or slash, between 1 character and
+254 characters long, and prefixed with a
+slash.
+
+To enter a guarded state with a condition,
+use the verb @option{enter}. Then leave
+it with @option{leave}. The verbs
+@option{wait}, @option{notify} and
+@option{broadcast} can only be used
+after @option{enter} has been used but
+before @option{leave}. @option{wait}
+temporarily leaves the guarded state
+and wait for a notification. A notification
+can be sent with @option{notify}.
+@option{notify} will send a notify to
+exactly one waiting peer. If there is
+not peer waiting, the notification will
+be stored for the next time @option{wait}
+is used. @option{notify} cannot block.
+If you want to send a signal to currently
+waiting peers you can instead use the
+verb @option{broadcast}. Alternatively
+you can use @option{notify all} (two
+command line arguments) perform a
+@option{broadcast} if there are any
+waiting peers, and otherwise @option{wait}.
+
+@*
+@cartouche
+@example
+create:
+    (s, c, q) := (S(1), S(0), S(0))
+
+enter:
+    P(s)
+
+leave:
+    V(s)
+
+wait:
+    V(s), V(c), P(q), P(c), P(s)
+
+notify:
+    V(q)
+
+broadcast:
+    c.value times:
+        V(q)
+
+notify all:
+    max(c.value, 1) times:
+        V(q)
+@end example
+@end cartouche
+
+
+
+@node Barriers
+@chapter Barriers
+
+A barrier is a synchronisation primitive
+that can be used to make sure the a number
+of process continue their work at the same
+time and do not fall out of sync with
+eachother. A barrier blocks until a select
+number of processes have reached it and the
+lets all of those processes continue. It
+does only have one verb: @option{enter}.
+The threshold, that is the number of
+process that are synchronised, is specified
+by the first non-option argument. If
+@option{enter} is used, the threshold is
+specified before @option{enter}. The
+threshold most be specified both at
+construction and at usage.
+Use of barriers are indicated by the
+@option{-B} option.
+
+A ``System V'' barrier is constructed from
+two semaphores. A ``POSIX'' barrier is
+constructed from three semaphores. This
+difference is due to the lack of the
+@code{Z} for POSIX semaphores.
+
+The key for a ``System V'' barrier is
+a integer-duo delimited by a full stop.
+The key for a ``POSIX'' barrier is a
+juxtaposition of three ASCII strings:
+no NUL or slash, between 1 character and
+254 characters long, and prefixed with a
+slash.
+
+@*
+@cartouche
+@example
+[sysv] create:
+    (s, mm c) := (S(threshold), S(1), S(0))
+
+[sysv] enter:
+    P(s), Z(s)
+    P(m), V(c)
+    if c.value = threshold:
+        s.value := threshold
+        c.value := 0
+    V(m)
+
+[posix] create:
+    (x, c, q) := (S(1), S(0), S(0))
+
+[posix] enter:
+    P(x), V(c)
+    if c.value = threshold:
+        V(q, delta = threshold - 1)
+        c.value := 0
+        V(x)
+    else:
+        V(x), P(q)
+@end example
+@end cartouche
+
+
+
+@node Shared Locks
+@chapter Shared Locks
+
+A shared lock is a mutex support for
+two types of locks: shared and exclusive.
+They are implemented using three semaphores.
+Mutexes are can be reduced from shared lock
+by only using exclusive locking. Exclusive
+locking allows only on program to enter
+a guarded state. Shared locks introduce
+shared locking works the same why but any
+number of programs can be in this state
+concurrently. The purpose of the shared
+locking is to block exclusive locking.
+If you for example are reading and writing
+to a file or shared memory, you would
+apply an exclusive lock if you want to
+be able to modify the content of the
+memory and a shared lock if you only
+which to be able to read it. This
+guarantees both that two processes will
+edit the memory at the same time and
+cause corruption, and that not process
+will modify the memory while another
+process is reading it, while allowing
+multiple processes to read the memory
+at the same time.
+Use of shared locks are indicated by the
+@option{-L} option.
+
+The key for a ``System V'' shared lock is
+a integer-trio delimited by full stops.
+The key for a ``POSIX'' shared lock is a
+juxtaposition of three ASCII strings:
+no NUL or slash, between 1 character and
+254 characters long, and prefixed with a
+slash.
+
+There are four verbs for shared locks:
+
+@table @option
+@item shared lock
+Apply shared locking.
+
+@item exclusive lock
+Apply exclusive locking.
+
+@item shared unlock
+Release shared locking.
+
+@item exclusive unlock
+Release exclusive locking.
+@*
+@end table
+
+@cartouche
+@example
+create:
+    (x, s, m) := (S(1), S(0), S(1))
+
+shared lock:
+    P(m)
+    if s.value = 0:
+        P(x)
+    V(s), V(m)
+
+exclusive lock:
+    P(x)
+
+shared unlock:
+    P(m), P(s)
+    if s.value = 0:
+        V(x)
+    V(m)
+
+exclusive unlock:
+    V(x)
+@end example
+@end cartouche
+
+
+
+@node Rendezvous
+@chapter Rendezvous
+
+A rendezvous is like barrier, except it
+is fixed to synchronising two processes.
+When two processes meet at a rendezvous
+they exchange a message with eachother.
+Use of rendezvous are indicated by the
+@option{-R} option. @option{-R} inherits
+the @option{-s} and @option{-z} options
+from @option{-Q}.
+
+A ``System V'' rendezvous is constructed
+from two semaphores and one message queue.
+A ``POSIX'' rendezvous is constructed from
+three semaphores and one message queue.
+This difference is due to POSIX message
+queues having priorities instead of types
+for messages.
+
+The key for a ``System V'' rendezvous is
+a integer-trio delimited by full stops.
+The key for a ``POSIX'' shared lock is a
+juxtaposition of four ASCII strings:
+no NUL or slash, between 1 character and
+254 characters long, and prefixed with a
+slash.
+
+@*
+@cartouche
+@example
+[sysv] create:
+    (m, i, q) := (S(1), S(0), M())
+
+[sysv] enter:
+    P(m)
+    if i.value = 0:
+        V(i), V(m)
+        send(q, type = 1)
+        receive(q, type = 2)
+    else:
+        P(i), V(m)
+        receive(q, type = 1)
+        send(q, type = 2)
+
+[posix] create:
+    (m, i, p, q) := (S(1), S(0), S(0), M())
+
+[posix] enter:
+    P(m)
+    if i.value = 0:
+        V(i), V(m)
+        send(q), P(p)
+        receive(q)
+    else:
+        P(i), V(m)
+        receive(q), V(p)
+        send(q)
+@end example
+@end cartouche
+
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include fdl.texinfo
+
+@bye
+