+ Documented semaphores and message queues

docs/ipc.tex

@@ -165,7 +165,6 @@ The \var{TMSG} record is used in the handling of message queues. There
 should be few cases where the programmer needs to access this data.
 \begin{verbatim}
 type
-
   PMSQid_ds = ^TMSQid_ds;
   TMSQid_ds = record
     msg_perm   : TIPC_perm;
@@ -195,7 +194,8 @@ contains all data about a message queue.
 The \var{TMSGbuf} record is a record containing the data of a record. you
 should never use this record directly, instead you should make your own
 record that follows the structure of the \var{TMSGbuf} record, but that has
-a size that is big enough to accomodate your messages.
+a size that is big enough to accomodate your messages. The \var{mtype} field
+should always be present, and should always be filled.
 \begin{verbatim}
 Type
   PMSGinfo = ^TMSGinfo;
@@ -264,7 +264,7 @@ Type
    case longint of
       0 : ( val : longint );
       1 : ( buf : PSEMid_ds );
-      2 : ( arr : Pointer );
+      2 : ( arr : PWord );
       3 : ( padbuf : PSeminfo );
       4 : ( padpad : pointer );
    end;
@@ -291,6 +291,8 @@ they use the same \var{Path} and \var{ID}
 \seef{semget},\seef{shmget},\seef{msgget}
 \end{function}
 
+For an example, see \seef{msgctl}, \seef{semctl}, \seef{shmctl}.
+
 \begin{function}{msgget}
 \Declaration
 Function msgget(key: TKey; msgflg:longint):longint;	
@@ -312,59 +314,254 @@ On error, -1 is returned, and \var{IPCError} is set.
 \seef{ftok},\seef{msgsnd}, \seef{msgrcv}, \seef{msgctl}, \seem{semget}{2}
 \end{function}
 
+For an example, see \seef{msgctl}.
+
 \begin{function}{msgsnd}
 \Declaration
 Function msgsnd(msqid:longint; msgp: PMSGBuf; msgsz: longint; msgflg:longint): Boolean;
 \Description
+\var{msgsend} sends a message to a message queue with ID \var{msqid}.
+\var{msgp} is a pointer to a message buffer, that should be based on the
+\var{TMsgBuf} type. \var{msgsiz} is the size of the message (NOT of the
+message buffer record !)
+
+The \var{msgflg} can have a combination of the following values (ORed
+together):
+\begin{description}
+\item [0] No special meaning. The message will be written to the queue.
+If the queue is full, then the process is blocked.
+\item [IPC\_NOWAIT] If the queue is full, then no message is written,
+and the call returns immediatly.
+\end{description}
+
+The function returns \var{True} if the message was sent successfully, 
+\var{False} otherwise.
 \Errors
+In case of error, the call returns \var{False}, and \var{IPCerror} is set.
 \SeeAlso
+\seef{msgget}, \seef{msgrcv}, seef{msgctl}
 \end{function}
 
+For an example, see \seef{msgctl}.
+
 \begin{function}{msgrcv}
 \Declaration
 Function msgrcv(msqid:longint; msgp: PMSGBuf; msgsz: longint; msgtyp:longint; msgflg:longint): Boolean;
 \Description
+\var{msgrcv} retrieves a message of type \var{msgtyp} from the message 
+queue with ID \var{msqid}. \var{msgtyp} corresponds to the \var{mtype} 
+field of the \var{TMSGbuf} record. The message is stored in the \var{MSGbuf}
+structure pointed to by \var{msgp}.
+
+The \var{msgflg} parameter can be used to control the behaviour of the
+\var{msgrcv} call. It consists of an ORed combination of the following
+flags:
+\begin{description}
+\item [0] No special meaning.
+\item [IPC\_NOWAIT] if no messages are available, then the call returns
+immediatly, with the \var{ENOMSG} error.
+\item [MSG\_NOERROR] If the message size is wrong (too large), 
+no error is generated, instead the message is truncated. 
+Normally, in such cases, the call returns an error (E2BIG)
+\end{description}
+
+The function returns \var{True} if the message was received correctly,
+\var{False} otherwise.
 \Errors
+In case of error, \var{False} is returned, and \var{IPCerror} is set.
 \SeeAlso
+\seef{msgget}, \seef{msgsnd}, \seef{msgctl}
 \end{function}
 
+For an example, see \seef{msgctl}.
+
 \begin{function}{msgctl}
 \Declaration
 Function msgctl(msqid:longint; cmd: longint; buf: PMSQid\_ds): Boolean;
 \Description
+\var{msgctl} performs various operations on the message queue with id
+\var{ID}. Which operation is performed, depends on the \var{cmd} 
+parameter, which can have one of the following values:
+\begin{description}
+\item[IPC\_STAT] In this case, the \var{msgctl} call fills the
+\var{TMSQid\_ds} structure with information about the message queue.
+\item[IPC\_SET] in this case, the \var{msgctl} call sets the permissions
+of the queue as specified in the \var{ipc\_perm} record inside \var{buf}.
+\item[IPC\_RMID] If this is specified, the message queue will be removed 
+from the system.
+\end{description}
+
+\var{buf} contains the data that are needed by the call. It can be 
+\var{Nil} in case the message queue should be removed.
+
+The function returns \var{True} if successfull, \var{False} otherwise.
 \Errors
+On error, \var{False} is returned, and \var{IPCerror} is set accordingly.
 \SeeAlso
+\seef{msgget}, \seef{msgsnd}, \seef{msgrcv}
 \end{function}
 
+\latex{\inputlisting{ipcex/msgtool.pp}}
+\html{\input{ipcex/msgtool.tex}}
+
 \begin{function}{semget}
 \Declaration
 Function semget(key:Tkey; nsems:longint; semflg:longint): longint;
 \Description
+\var{msgget} returns the ID of the semaphore set described by \var{key}.
+Depending on the flags in \var{semflg}, a new queue is created.
+
+\var{semflg} can have one or more of the following values (combined by ORs):
+\begin{description}
+\item[IPC\_CREAT] The queue is created if it doesn't already exist.
+\item[IPC\_EXCL] If used in combination with \var{IPC\_CREAT}, causes the
+call to fail if the set already exists. It cannot be used by itself.
+\end{description}
+Optionally, the flags can be \var{OR}ed with a permission mode, which is the
+same mode that can be used in the file system.
+
+if a new set of semaphores is created, then there will be \var{nsems}
+semaphores in it.
 \Errors
+On error, -1 is returned, and \var{IPCError} is set.
 \SeeAlso
+\seef{ftok}, \seef{semop}, \seef{semctl}
 \end{function}
 
 \begin{function}{semop}
 \Declaration
 Function semop(semid:longint; sops: pointer; nsops: cardinal): Boolean;
 \Description
+\var{semop} performs a set of operations on a message queue.
+\var{sops} points to an array of type \var{TSEMbuf}. The array should
+contain \var{nsops} elements.
+
+The fields of the \var{TSEMbuf} structure 
+\begin{verbatim}
+  TSEMbuf = record
+    sem_num : word;
+    sem_op  : integer;
+    sem_flg : integer;
+\end{verbatim}
+
+should be filled as follows:
+\begin{description}
+\item[sem\_num] The number of the semaphore in the set on which the
+operation must be performed.
+\item[sem\_op] The operation to be performed. The operation depends on the
+sign of \var{sem\_op}
+\begin{enumerate}
+\item A positive  number is simply added to the current value of the
+semaphore.
+\item If 0 (zero) is specified, then the process is suspended until the 
+  specified semaphore reaches zero.
+\item If a negative number is specified, it is substracted from the
+current value of the semaphore. If the value would become negative
+then the process is suspended until the value becomes big enough, unless
+\var{IPC\_NOWAIT} is specified in the \var{sem\_flg}.
+\end{enumerate}
+\item[sem\_flg] Optional flags: if \var{IPC\_NOWAIT} is specified, then the
+calling process will never be suspended.
+\end{description}
+
+The function returns \var{True} if the operations were successful,
+\var{False} otherwise.
 \Errors
+In case of error, \var{False} is returned, and \var{IPCerror} is set.
 \SeeAlso
+\seef{semget}, \seef{semctl}
 \end{function}
 
 \begin{function}{semctl}
 \Declaration
 Function semctl(semid:longint; semnum:longint; cmd:longint; var arg: tsemun): longint;
 \Description
+\var{semctl} performs various operations on the semaphore \var{semnum} w
+ith semaphore set id \var{ID}. 
+
+The \var{arg} parameter supplies the data needed for each call. This is
+a variant record that should be filled differently, according to the
+command:
+\begin{verbatim}
+Type
+  TSEMun = record
+   case longint of
+      0 : ( val : longint );
+      1 : ( buf : PSEMid_ds );
+      2 : ( arr : PWord );
+      3 : ( padbuf : PSeminfo );
+      4 : ( padpad : pointer );
+   end;
+\end{verbatim}
+
+
+Which operation is performed, depends on the \var{cmd} 
+parameter, which can have one of the following values:
+\begin{description}
+\item[IPC\_STAT] In this case, the arg record should have it's \var{buf}
+field set to the address of a \var{TSEMid\_ds} record. 
+The \var{semctl} call fills this \var{TSEMid\_ds} structure with information 
+about the semaphore set. 
+\item[IPC\_SET] In this case, the \var{arg} record should have it's \var{buf}
+field set to the address of a \var{TSEMid\_ds} record.
+The \var{semctl} call sets the permissions of the queue as specified in 
+the \var{ipc\_perm} record.
+\item[IPC\_RMID] If this is specified, the semaphore set is removed from 
+from the system.
+\item[GETALL] In this case, the \var{arr} field of \var{arg} should point
+to a memory area where the values of the semaphores will be stored.
+The size of this memory area is \var{SizeOf(Word)* Number of semaphores
+in the set}.
+This call will then fill the memory array with all the values of the
+semaphores.
+\item[GETNCNT] This will fill the \var{val} field of the \var{arg} union
+with the bumber of processes waiting for resources.
+\item[GETPID] \var{semctl} returns the process ID of the process that
+performed the last \seef{semop} call.
+\item[GETVAL] \var{semctl} returns the value of the semaphore with number
+\var{semnum}.
+\item[GETZCNT] \var{semctl} returns the number of processes waiting for 
+semaphores that reach value zero.
+\item[SETALL] In this case, the \var{arr} field of \var{arg} should point
+to a memory area where the values of the semaphores will be retrieved from.
+The size of this memory area is \var{SizeOf(Word)* Number of semaphores
+in the set}.
+This call will then set the values of the semaphores from the memory array.
+\item[SETVAL] This will set the value of semaphore \var{semnum} to the value
+in the \var{val} field of the \var{arg} parameter.
+\end{description}
+
+The function returns -1 on error.
 \Errors
+The function returns -1 on error, and \var{IPCerror} is set accordingly.
 \SeeAlso
+\seef{semget}, \seef{semop}
 \end{function}
 
+\latex{\inputlisting{ipcex/semtool.pp}}
+\html{\input{ipcex/semtool.tex}}
+
+
 \begin{function}{shmget}
 \Declaration
-Function shmget(key: Tkey; size:longint; flag:longint):longint;
+Function shmget(key: Tkey; Size:longint; flag:longint):longint;
 \Description
+\var{shmget} returns the ID of a shared memory block, described by \var{key}.
+Depending on the flags in \var{flag}, a new memory block is created.
+
+\var{flag} can have one or more of the following values (combined by ORs):
+\begin{description}
+\item[IPC\_CREAT] The queue is created if it doesn't already exist.
+\item[IPC\_EXCL] If used in combination with \var{IPC\_CREAT}, causes the
+call to fail if the queue already exists. It cannot be used by itself.
+\end{description}
+Optionally, the flags can be \var{OR}ed with a permission mode, which is the
+same mode that can be used in the file system.
+
+if a new memory block is created, then it will have size \var{Size}
+semaphores in it.
 \Errors
+On error, -1 is returned, and \var{IPCError} is set.
 \SeeAlso
 \end{function}
 
@@ -392,3 +589,5 @@ Function shmctl(shmid:longint; cmd:longint; buf: pshmid\_ds): Boolean;
 \SeeAlso
 \end{function}
 
+\latex{\inputlisting{ipcex/shmtool.pp}}
+\html{\input{ipcex/shmtool.tex}}