paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-04-16 04:59:25 +02:00
Code Issues Packages Projects Releases Wiki Activity

+ Documented semaphores and message queues

Browse Source
This commit is contained in:
michael 1999-01-15 13:47:49 +00:00
parent 5812e04e95
commit 7838e830a5
1 changed files with 203 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
docs/ipc.tex
View File

@ -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}}