Unix Inter Process Communication functionality.

This document describes the IPC unit for Free Pascal. It was written for linux by Michael 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.

Many constants here are provided for completeness only, and should under normal circumstances not be used by the programmer.

Last IPC error code
The IPCerror variable is used to report errors, by all calls.
Create if key is nonexistent
fail if key exists
return error on wait
Remove resource
set ipc_perm options
get ipc_perm options
For ipcs call
Internal Message control code. Do not use
Internal Message control code. Do not use
Internal Message control code. Do not use
Internal Message control code. Do not use
Internal Message control code. Do not use
Constant for use in
Constant for use in
Constant for use in
Constant for use in
Constant for use in
Constant for use in
Constant for use in
Constant for use in
Internal semaphore system constant. Do not use.
Internal semaphore system constant. Do not use.
Internal semaphore system constant. Do not use.
Internal semaphore system constant. Do not use.
Internal semaphore system constant. Do not use.
This constant is used in the call.
This constant is used in the call.
This constant is used in the call.
This constant is used in the call.
This constant is used in the call.
This constant is used in the call.
This constant is used in the call.
Some base types
Alias for type
Creation Mode
?
Message length type
Message queue number type
Pointer to record
Pointer to
Pointer to rcord
Semaphore operation: Get process ID of last operation.
Semaphore operation: Get current value of semaphore
Semaphore operation: Get all semaphore values
Semaphore operation: Get number of processes waiting for resource.
Semaphore operation: Get number of processes waiting for semaphores to reach zero
Semaphore operation: Set semaphore value
Semaphore operation: Set all semaphore values
Semaphore operation: ?
Semaphore operation: ?
Semaphore operation: ?
Semaphore operation: ?
Semaphore operation: ?
Number of semaphores
Pointer to cardinal type.
Pointer to word type.
Type returned by the key generating function.
Record used in all IPC systems to specify the permissions.
TIPC_Perm
is used in all IPC systems to specify the permissions. It should never be used directly.
key used to create resource
Owner user ID
Owner group id
Creator user ID
Creator group ID
?
Pointer to record.
Record used in the call to set or retrieve settings for shared memory.
Pointer to record.
Permissions
Segment size
Last access time
Last detach time
Create time
Creator PID
Last operation PID
Number of attachments
Number of pages
?
?
Record used by the shared memory system, Do not use directly.
Record used in the handling of message queues. Do not use directly.
Record returned by the call, contains all data about a message queue.
This record should never be used directly, it is an internal kernel record. It's fields may change at any time.
Queue permissions
Pointer to first message
Pointer to last message
Last send time
Last receive time
Last control time
Generic message data record
The 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 TMSGbuf record, but that has a size that is big enough to accomodate your messages. The mtype field should always be present, and should always be filled.
Message type
Message data
Internal message system record. Do not use directly.
Pointer to record
Structure returned by the call, contains all data of a semahore
Pointer to record.
IPC permissions
Last operation time
Create time
Internal data. Do not use
Internal data. Do not use
Internal data. Do not use
Internal data. Do not use
Internal data. Do not use
Record used in call.
The TSEMbuf record is used in the call, and is used to specify which operations you want to do.
Pointer to record.
Number of the semaphore to perform operation on.
Operation to perform on semaphore
Flags for operation.
Internal semaphore system record. Do not use.
Pointer to record.
Record used in call.
Pointer to record
Create token from filename

ftok returns a key that can be used in a or call to access a new or existing IPC resource.

Path is the name of a file in the file system, 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 Path and ID

For an example, see , or .

ftok
returns -1 if the file in Path doesn't exist.
Return message queue ID, possibly creating the queue

msgget returns the ID of the message queue described by key. Depending on the flags in msgflg, a new queue is created.

msgflg can have one or more of the following values (combined by ORs):

IPC_CREAT
  The queue is created if it doesn't already exist.
IPC_EXCL
  If used in combination with IPC_CREAT, causes the call to fail if the queue already exists. It cannot be used by itself.

Optionally, the flags can be ORed with a permission mode, which is the same mode that can be used in the file system.

For an example, see .

On error, -1 is returned, and IPCError is set.
Send a message to the messague queue

msgsend sends a message to a message queue with ID msqid. msgp is a pointer to a message buffer, that should be based on the TMsgBuf type. msgsiz is the size of the message (NOT of the message buffer record !)

The msgflg can have a combination of the following values (ORed together):

0
  No special meaning. The message will be written to the queue. If the queue is full, then the process is blocked.
IPC_NOWAIT
  If the queue is full, then no message is written, and the call returns immediatly.

The function returns True if the message was sent successfully, False otherwise.

For an example, see .

In case of error, the call returns False, and IPCerror is set.
Retrieve a message from the queue

msgrcv retrieves a message of type msgtyp from the message queue with ID msqid. msgtyp corresponds to the mtype field of the TMSGbuf record. The message is stored in the MSGbuf structure pointed to by msgp.

The msgflg parameter can be used to control the behaviour of the msgrcv call. It consists of an ORed combination of the following flags:

0
  No special meaning.
IPC_NOWAIT
  if no messages are available, then the call returns immediatly, with the ENOMSG error.
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)

The function returns True if the message was received correctly, False otherwise.

For an example, see .

In case of error, False is returned, and IPCerror is set.
Perform various operations on a message queue

msgctl performs various operations on the message queue with id ID. Which operation is performed, depends on the cmd parameter, which can have one of the following values:

IPC_STAT
  In this case, the msgctl call fills the TMSQid_ds structure with information about the message queue.
IPC_SET
  in this case, the msgctl call sets the permissions of the queue as specified in the ipc_perm record inside buf.
IPC_RMID
  If this is specified, the message queue will be removed from the system.

buf contains the data that are needed by the call. It can be Nil in case the message queue should be removed.

The function returns True if successfull, False otherwise.

On error, False is returned, and IPCerror is set accordingly.
Return the ID of a semaphore set, possibly creating the set

msgget returns the ID of the semaphore set described by key. Depending on the flags in semflg, a new queue is created.

semflg can have one or more of the following values (combined by ORs):

IPC_CREAT
  The queue is created if it doesn't already exist.
IPC_EXCL
  If used in combination with IPC_CREAT, causes the call to fail if the set already exists. It cannot be used by itself.

Optionally, the flags can be ORed 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 nsems semaphores in it.

On error, -1 is returned, and IPCError is set.
Perform semaphore operation.

semop performs a set of operations on a message queue. sops points to an array of type TSEMbuf. The array should contain nsops elements.

The fields of the structure

TSEMbuf = record sem_num : word; sem_op : integer; sem_flg : integer;

should be filled as follows:

sem_num
  The number of the semaphore in the set on which the operation must be performed.
sem_op
  The operation to be performed. The operation depends on the sign of sem_op: A positive number is simply added to the current value of the semaphore. If 0 (zero) is specified, then the process is suspended until the specified semaphore reaches zero. 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 IPC_NOWAIT is specified in the sem_flg.
sem_flg
  Optional flags: if IPC_NOWAIT is specified, then the calling process will never be suspended.

The function returns True if the operations were successful, False otherwise.

In case of error, False is returned, and IPCerror is set.
Perform various control operations on a semaphore set

semctl performs various operations on the semaphore semnum w ith semaphore set id ID.

The arg parameter supplies the data needed for each call. This is a variant record that should be filled differently, according to the command:

Type TSEMun = record case longint of 0 : ( val : longint ); 1 : ( buf : PSEMid_ds ); 2 : ( arr : PWord ); 3 : ( padbuf : PSeminfo ); 4 : ( padpad : pointer ); end;

Which operation is performed, depends on the cmd parameter, which can have one of the following values:

IPC_STAT
  In this case, the arg record should have it's buf field set to the address of a TSEMid_ds record. The semctl call fills this TSEMid_ds structure with information about the semaphore set.
IPC_SET
  In this case, the arg record should have it's buf field set to the address of a TSEMid_ds record. The semctl call sets the permissions of the queue as specified in the ipc_perm record.
IPC_RMID
  If this is specified, the semaphore set is removed from from the system.
GETALL
  In this case, the arr field of 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.
GETNCNT
  This will fill the val field of the arg union with the number of processes waiting for resources.
GETPID
  semctl
  returns the process ID of the process that performed the last call.
GETVAL
  semctl
  returns the value of the semaphore with number semnum.
GETZCNT
  semctl
  returns the number of processes waiting for semaphores that reach value zero.
SETALL
  In this case, the arr field of 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.
SETVAL
  This will set the value of semaphore semnum to the value in the val field of the arg parameter.

The function returns -1 on error.

The function returns -1 on error, and IPCerror is set accordingly.
Return the ID of a shared memory block, possibly creating it

shmget returns the ID of a shared memory block, described by key. Depending on the flags in flag, a new memory block is created.

flag can have one or more of the following values (combined by ORs):

IPC_CREAT
  The queue is created if it doesn't already exist.
IPC_EXCL
  If used in combination with IPC_CREAT, causes the call to fail if the queue already exists. It cannot be used by itself.

Optionally, the flags can be ORed 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 Size bytes in it.

On error, -1 is returned, and IPCError is set.
Attach a shared memory block.

shmat attaches a shared memory block with identified shmid to the current process. The function returns a pointer to the shared memory block.

If shmaddr is Nil, then the system chooses a free unmapped memory region, as high up in memory space as possible.

If shmaddr is non-nil, and SHM_RND is in shmflg, then the returned address is shmaddr, rounded down to SHMLBA. If SHM_RND is not specified, then shmaddr must be a page-aligned address.

The parameter shmflg can be used to control the behaviour of the shmat call. It consists of a ORed combination of the following constants:

SHM_RND
  The suggested address in shmaddr is rounded down to SHMLBA.
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.

For an example, see .

If an error occurs, -1 is returned, and IPCerror is set.
Detach shared memory block.

shmdt detaches the shared memory at address shmaddr. This shared memory block is unavailable to the current process, until it is attached again by a call to .

The function returns True if the memory block was detached successfully, False otherwise.

On error, False is returned, and IPCerror is set.
Perform control operations on a shared memory block.

shmctl performs various operations on the shared memory block identified by identifier shmid.

The buf parameter points to a TSHMid_ds record. The cmd parameter is used to pass which operation is to be performed. It can have one of the following values :

IPC_STAT
  shmctl
  fills the TSHMid_ds record that buf points to with the available information about the shared memory block.
IPC_SET
  applies the values in the ipc_perm record that buf points to, to the shared memory block.
IPC_RMID
  the shared memory block is destroyed (after all processes to which the block is attached, have detached from it).

If successful, the function returns True, False otherwise.

If an error occurs, the function returns False, and IPCerror is set.