fpc/docs/ipc.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}