DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Interprocess communication

Getting shared memory segments

This section describes how to use the shmget system call. The accompanying program illustrates its use.

Using shmget

The synopsis found on the shmget(2) manual page is as follows:

   #include  <sys/types.h>
   #include  <sys/ipc.h>
   #include  <sys/shm.h>
   

int shmget (key, size, shmflg) key_t key; int size, shmflg;

All of these include files are located in the /usr/include/sys directory of the UNIX operating system. The following line in the synopsis:

int shmget (key, size, shmflg)
informs you that shmget is a function with three formal arguments that returns an integer-type value. The next two lines:
key_t  key;
int size, shmflg;
declare the types of the formal arguments. key_t is defined by a typedef in the sys/types.h header file to be an integer.

The integer returned from this function (upon successful completion) is the shared memory identifier (shmid) that was discussed earlier.

As declared, the process calling the shmget system call must supply three arguments to be passed to the formal key, size, and shmflg arguments.

A new shmid with an associated shared memory data structure is provided if either

or

The value passed to the shmflg argument must be an integer-type value and will specify the following:

Access permissions determine the read/write attributes and modes determine the user/group/other attributes of the shmflg argument. They are collectively referred to as ``operation permissions.''

``Operation permissions codes'' reflects the numeric values (expressed in octal notation) for the valid operation permissions codes.

Operation permissions codes

Operation permissions Octal value
Read by user 00400
Write by user 00200
Read by group 00040
Write by group 00020
Read by others 00004
Write by others 00002

A specific octal value is derived by adding or bitwise ORing the octal values for the operation permissions desired. That is, if read by user and read/write by others is desired, the code value would be 00406 (00400 plus 00006). There are constants located in the sys/shm.h header file which can be used for the user (OWNER). They are:

SHM_R	0400
SHM_W	0200

Control flags are predefined constants (represented by all upper-case letters). The flags that apply to the shmget system call are IPC_CREAT and IPC_EXCL and are defined in the sys/ipc.h header file.

The value for shmflg is, therefore, a combination of operation permissions and control commands. After determining the value for the operation permissions as previously described, the desired flag(s) can be specified. This is accomplished by adding or bitwise ORing (|) them with the operation permissions; the bit positions and values for the control commands in relation to those of the operation permissions make this possible.

The shmflg value can easily be set by using the names of the flags in conjunction with the octal operation permissions value:

shmid = shmget (key, size, (IPC_CREAT | 0400));

shmid = shmget (key, size, (IPC_CREAT | IPC_EXCL | 0400));

As specified by the shmget(2) manual page, success or failure of this system call depends upon the argument values for key, size, and shmflg, and system-tunable parameters. The system call will attempt to return a new shmid if one of the following conditions is true:

The key argument can be set to IPC_PRIVATE like this:

shmid = shmget(IPC_PRIVATE, size, shmflg);
The SHMMNI system-tunable parameter determines the maximum number of unique shared memory segments (shmids) that may be in use at any given time. If the maximum number of shared memory segments is already in use, an attempt to create an additional segment will fail.

IPC_EXCL is another control command used in conjunction with IPC_CREAT. It will cause the system call to return an error if a shared memory identifier already exists for the specified key provided. This is necessary to prevent the process from thinking that it has received a new (unique) shmid when it has not. In other words, when both PC_CREAT and IPC_EXCL are specified, a unique shared memory identifier is returned if the system call is successful. Any value for shmflg returns a new identifier if the key equals zero (IPC_PRIVATE) and no system-tunable parameters are exceeded.

The system call will fail if the value for the size argument is less than SHMMIN or greater than SHMMAX. These tunable parameters specify the minimum and maximum shared memory segment sizes.

Refer to the shmget(2) manual page for specific associated data structure initialization for successful completion. The specific failure conditions and their error names are contained there also.


Next topic: Example program
Previous topic: Using shared memory

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004