mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-10-31 21:09:38 +01:00
356a3d1609
* provided local copies or required styles since debian does not
supply the listings.sty anymore
656 lines
21 KiB
TeX
656 lines
21 KiB
TeX
%
|
|
% $Id$
|
|
% This file is part of the FPC documentation.
|
|
% Copyright (C) 1998, by Michael Van Canneyt
|
|
%
|
|
% The FPC documentation is free text; you can redistribute it and/or
|
|
% modify it under the terms of the GNU Library General Public License as
|
|
% published by the Free Software Foundation; either version 2 of the
|
|
% License, or (at your option) any later version.
|
|
%
|
|
% The FPC Documentation is distributed in the hope that it will be useful,
|
|
% but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
% Library General Public License for more details.
|
|
%
|
|
% You should have received a copy of the GNU Library General Public
|
|
% License along with the FPC documentation; see the file COPYING.LIB. If not,
|
|
% write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
% Boston, MA 02111-1307, USA.
|
|
%
|
|
\chapter{The IPC unit.}
|
|
\label{ch:ipcunit}
|
|
|
|
\FPCexampledir{ipcex}
|
|
This chapter describes the IPC unit for Free Pascal. It was written for
|
|
\linux by Micha\"el Van Canneyt. It gives all the functionality of system V
|
|
Inter-Process Communication: shared memory, semaphores and messages.
|
|
It works only on the \linux operating system.
|
|
|
|
The chapter is divided in 2 sections:
|
|
\begin{itemize}
|
|
\item The first section lists types, constants and variables from the
|
|
interface part of the unit.
|
|
\item The second section describes the functions defined in the unit.
|
|
\end{itemize}
|
|
\section {Types, Constants and variables : }
|
|
\subsection{Variables}
|
|
|
|
\begin{verbatim}
|
|
Var
|
|
IPCerror : longint;
|
|
\end{verbatim}
|
|
The \var{IPCerror} variable is used to report errors, by all calls.
|
|
\subsection{Constants}
|
|
Many constants here are provided for completeness only, and should under
|
|
normal circumstances not be used by the programmer.
|
|
\begin{verbatim}
|
|
Const
|
|
IPC_CREAT = 1 shl 9; { create if key is nonexistent }
|
|
IPC_EXCL = 2 shl 9; { fail if key exists }
|
|
IPC_NOWAIT = 4 shl 9; { return error on wait }
|
|
\end{verbatim}
|
|
These constants are used in the various \var{xxxget} calls.
|
|
\begin{verbatim}
|
|
IPC_RMID = 0; { remove resource }
|
|
IPC_SET = 1; { set ipc_perm options }
|
|
IPC_STAT = 2; { get ipc_perm options }
|
|
IPC_INFO = 3; { see ipcs }
|
|
\end{verbatim}
|
|
These constants can be passed to the various \var{xxxctl} calls.
|
|
\begin{verbatim}
|
|
const
|
|
MSG_NOERROR = 1 shl 12;
|
|
MSG_EXCEPT = 2 shl 12;
|
|
MSGMNI = 128;
|
|
MSGMAX = 4056;
|
|
MSGMNB = 16384;
|
|
\end{verbatim}
|
|
These constants are used in the messaging system, they are not for use by
|
|
the programmer.
|
|
\begin{verbatim}
|
|
const
|
|
SEM_UNDO = $1000;
|
|
GETPID = 11;
|
|
GETVAL = 12;
|
|
GETALL = 13;
|
|
GETNCNT = 14;
|
|
GETZCNT = 15;
|
|
SETVAL = 16;
|
|
SETALL = 17;
|
|
\end{verbatim}
|
|
These constants call be specified in the \seef{semop} call.
|
|
\begin{verbatim}
|
|
SEMMNI = 128;
|
|
SEMMSL = 32;
|
|
SEMMNS = (SEMMNI * SEMMSL);
|
|
SEMOPM = 32;
|
|
SEMVMX = 32767;
|
|
\end{verbatim}
|
|
These constanst are used internally by the semaphore system, they should not
|
|
be used by the programmer.
|
|
\begin{verbatim}
|
|
const
|
|
SHM_R = 4 shl 6;
|
|
SHM_W = 2 shl 6;
|
|
SHM_RDONLY = 1 shl 12;
|
|
SHM_RND = 2 shl 12;
|
|
SHM_REMAP = 4 shl 12;
|
|
SHM_LOCK = 11;
|
|
SHM_UNLOCK = 12;
|
|
\end{verbatim}
|
|
These constants are used in the \seef{shmctl} call.
|
|
|
|
\subsection{Types}
|
|
The following two types are provided because they are needed. One they they
|
|
should be defined in the system unit, however.
|
|
\begin{verbatim}
|
|
Type
|
|
PULong = ^Cardinal;
|
|
PWord = ^Word;
|
|
\end{verbatim}
|
|
|
|
\begin{verbatim}
|
|
Type
|
|
TKey = Longint;
|
|
\end{verbatim}
|
|
\var{TKey} is the type returned by the \seef{ftok} key generating function.
|
|
\begin{verbatim}
|
|
type
|
|
PIPC_Perm = ^TIPC_Perm;
|
|
TIPC_Perm = record
|
|
key : TKey;
|
|
uid,
|
|
gid,
|
|
cuid,
|
|
cgid,
|
|
mode,
|
|
seq : Word;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TIPC\_Perm} structure is used in all IPC systems to specify the
|
|
permissions.
|
|
\begin{verbatim}
|
|
Type
|
|
PSHMid_DS = ^TSHMid_ds;
|
|
TSHMid_ds = record
|
|
shm_perm : TIPC_Perm;
|
|
shm_segsz : longint;
|
|
shm_atime : longint;
|
|
shm_dtime : longint;
|
|
shm_ctime : longint;
|
|
shm_cpid : word;
|
|
shm_lpid : word;
|
|
shm_nattch : integer;
|
|
shm_npages : word;
|
|
shm_pages : Pointer;
|
|
attaches : pointer;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TSHMid\_ds} strucure is used in the \seef{shmctl} call to set or
|
|
retrieve settings concerning shared memory.
|
|
\begin{verbatim}
|
|
type
|
|
PSHMinfo = ^TSHMinfo;
|
|
TSHMinfo = record
|
|
shmmax : longint;
|
|
shmmin : longint;
|
|
shmmni : longint;
|
|
shmseg : longint;
|
|
shmall : longint;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TSHMinfo} record is used by the shared memory system, and should
|
|
not be accessed by the programer directly.
|
|
\begin{verbatim}
|
|
type
|
|
PMSG = ^TMSG;
|
|
TMSG = record
|
|
msg_next : PMSG;
|
|
msg_type : Longint;
|
|
msg_spot : PChar;
|
|
msg_stime : Longint;
|
|
msg_ts : Integer;
|
|
end;
|
|
\end{verbatim}
|
|
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;
|
|
msg_first : PMsg;
|
|
msg_last : PMsg;
|
|
msg_stime : Longint;
|
|
msg_rtime : Longint;
|
|
msg_ctime : Longint;
|
|
wwait : Pointer;
|
|
rwait : pointer;
|
|
msg_cbytes : word;
|
|
msg_qnum : word;
|
|
msg_qbytes : word;
|
|
msg_lspid : word;
|
|
msg_lrpid : word;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TMSQid\_ds} record is returned by the \seef{msgctl} call, and
|
|
contains all data about a message queue.
|
|
\begin{verbatim}
|
|
PMSGbuf = ^TMSGbuf;
|
|
TMSGbuf = record
|
|
mtype : longint;
|
|
mtext : array[0..0] of char;
|
|
end;
|
|
\end{verbatim}
|
|
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. The \var{mtype} field
|
|
should always be present, and should always be filled.
|
|
\begin{verbatim}
|
|
Type
|
|
PMSGinfo = ^TMSGinfo;
|
|
TMSGinfo = record
|
|
msgpool : Longint;
|
|
msgmap : Longint;
|
|
msgmax : Longint;
|
|
msgmnb : Longint;
|
|
msgmni : Longint;
|
|
msgssz : Longint;
|
|
msgtql : Longint;
|
|
msgseg : Word;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TMSGinfo} record is used internally by the message queue system,
|
|
and should not be used by the programmer directly.
|
|
\begin{verbatim}
|
|
Type
|
|
PSEMid_ds = ^PSEMid_ds;
|
|
TSEMid_ds = record
|
|
sem_perm : tipc_perm;
|
|
sem_otime : longint;
|
|
sem_ctime : longint;
|
|
sem_base : pointer;
|
|
sem_pending : pointer;
|
|
sem_pending_last : pointer;
|
|
undo : pointer;
|
|
sem_nsems : word;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TSEMid\_ds} structure is returned by the \seef{semctl} call, and
|
|
contains all data concerning a semahore.
|
|
\begin{verbatim}
|
|
Type
|
|
PSEMbuf = ^TSEMbuf;
|
|
TSEMbuf = record
|
|
sem_num : word;
|
|
sem_op : integer;
|
|
sem_flg : integer;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TSEMbuf} record us use in the \seef{semop} call, and is used to
|
|
specify which operations you want to do.
|
|
\begin{verbatim}
|
|
Type
|
|
PSEMinfo = ^TSEMinfo;
|
|
TSEMinfo = record
|
|
semmap : longint;
|
|
semmni : longint;
|
|
semmns : longint;
|
|
semmnu : longint;
|
|
semmsl : longint;
|
|
semopm : longint;
|
|
semume : longint;
|
|
semusz : longint;
|
|
semvmx : longint;
|
|
semaem : longint;
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TSEMinfo} record is used internally by the semaphore system, and
|
|
should not be used directly.
|
|
\begin{verbatim}
|
|
Type
|
|
PSEMun = ^TSEMun;
|
|
TSEMun = record
|
|
case longint of
|
|
0 : ( val : longint );
|
|
1 : ( buf : PSEMid_ds );
|
|
2 : ( arr : PWord );
|
|
3 : ( padbuf : PSeminfo );
|
|
4 : ( padpad : pointer );
|
|
end;
|
|
\end{verbatim}
|
|
The \var{TSEMun} variant record (actually a C union) is used in the
|
|
\seef{semctl} call.
|
|
|
|
\section{Functions and procedures}
|
|
|
|
\begin{function}{ftok}
|
|
\Declaration
|
|
Function ftok (Path : String; ID : char) : TKey;
|
|
\Description
|
|
\var{ftok} returns a key that can be used in a \seef{semget},\seef{shmget}
|
|
or \seef{msgget} call to access a new or existing IPC resource.
|
|
|
|
\var{Path} is the name of a file in the file system, \var{ID} is a
|
|
character of your choice. The ftok call does the same as it's C couterpart,
|
|
so a pascal program and a C program will access the same resource if
|
|
they use the same \var{Path} and \var{ID}
|
|
\Errors
|
|
\var{ftok} returns -1 if the file in \var{Path} doesn't exist.
|
|
\SeeAlso
|
|
\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;
|
|
\Description
|
|
\var{msgget} returns the ID of the message queue described by \var{key}.
|
|
Depending on the flags in \var{msgflg}, a new queue is created.
|
|
|
|
\var{msgflg} 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.
|
|
\Errors
|
|
On error, -1 is returned, and \var{IPCError} is set.
|
|
\SeeAlso
|
|
\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}
|
|
|
|
\FPCexample{msgtool}
|
|
|
|
\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}
|
|
|
|
\FPCexample{semtool}
|
|
|
|
\begin{function}{shmget}
|
|
\Declaration
|
|
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}
|
|
|
|
\begin{function}{shmat}
|
|
\Declaration
|
|
Function shmat (shmid:longint; shmaddr:pchar; shmflg:longint):pchar;
|
|
\Description
|
|
\var{shmat} attaches a shared memory block with identified \var{shmid}
|
|
to the current process. The function returns a pointer to the shared memory
|
|
block.
|
|
|
|
If \var{shmaddr} is \var{Nil}, then the system chooses a free unmapped
|
|
memory region, as high up in memory space as possible.
|
|
|
|
If \var{shmaddr} is non-nil, and \var{SHM\_RND} is in \var{shmflg}, then
|
|
the returned address is \var{shmaddr}, rounded down to \var{SHMLBA}.
|
|
If \var{SHM\_RND} is not specified, then \var{shmaddr} must be a
|
|
page-aligned address.
|
|
|
|
The parameter \var{shmflg} can be used to control the behaviour of the
|
|
\var{shmat} call. It consists of a ORed combination of the following
|
|
costants:
|
|
\begin{description}
|
|
\item[SHM\_RND] The suggested address in \var{shmaddr} is rounded down to
|
|
\var{SHMLBA}.
|
|
\item[SHM\_RDONLY] the shared memory is attached for read access only.
|
|
Otherwise the memory is attached for read-write. The process then needs
|
|
read-write permissions to access the shared memory.
|
|
\end{description}
|
|
\Errors
|
|
If an error occurs, -1 is returned, and \var{IPCerror} is set.
|
|
\SeeAlso
|
|
\seef{shmget}, \seef{shmdt}, \seef{shmctl}
|
|
\end{function}
|
|
|
|
For an example, see \seef{shmctl}.
|
|
|
|
\begin{function}{shmdt}
|
|
\Declaration
|
|
Function shmdt (shmaddr:pchar):boolean;
|
|
\Description
|
|
\var{shmdt} detaches the shared memory at address \var{shmaddr}. This shared
|
|
memory block is unavailable to the current process, until it is attached
|
|
again by a call to \seef{shmat}.
|
|
|
|
The function returns \var{True} if the memory block was detached
|
|
successfully, \var{False} otherwise.
|
|
\Errors
|
|
On error, False is returned, and IPCerror is set.
|
|
\SeeAlso
|
|
\seef{shmget}, \seef{shmat}, \seef{shmctl}
|
|
\end{function}
|
|
|
|
\begin{function}{shmctl}
|
|
\Declaration
|
|
Function shmctl(shmid:longint; cmd:longint; buf: pshmid\_ds): Boolean;
|
|
\Description
|
|
\var{shmctl} performs various operations on the shared memory block
|
|
identified by identifier \var{shmid}.
|
|
|
|
The \var{buf} parameter points to a \var{TSHMid\_ds} record. The
|
|
\var{cmd} parameter is used to pass which operation is to be performed.
|
|
It can have one of the following values :
|
|
\begin{description}
|
|
\item[IPC\_STAT] \var{shmctl} fills the \var{TSHMid\_ds} record that
|
|
\var{buf} points to with the available information about the shared memory
|
|
block.
|
|
\item[IPC\_SET] applies the values in the \var{ipc\_perm} record that
|
|
\var{buf} points to, to the shared memory block.
|
|
\item[IPC\_RMID] the shared memory block is destroyed (after all processes
|
|
to which the block is attached, have detached from it).
|
|
\end{description}
|
|
|
|
If successful, the function returns \var{True}, \var{False} otherwise.
|
|
\Errors
|
|
If an error occurs, the function returns \var{False}, and \var{IPCerror}
|
|
is set.
|
|
\SeeAlso
|
|
\seef{shmget}, \seef{shmat}, \seef{shmdt}
|
|
\end{function}
|
|
|
|
\FPCexample{shmtool}
|