diff --git a/docs/ipc.tex b/docs/ipc.tex index e8cf3f9bb9..8c7ab7d943 100644 --- a/docs/ipc.tex +++ b/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}}