Creating and Accessing Semaphore Sets

A semaphore set is created or accessed by using the semget(2) system call. Its function synopsis is as follows:

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

int semget(key_t key, int nsems, int flags);

The semget(2) function requires an IPC key value in the argument key, and permissions and flags in the argument flag. The argument nsems indicates how many semaphores you want to create in this set.

Like msgget(3), the key argument may be an IPC key or the value IPC_PRIVATE for a set of semaphores without a key value.

The flags argument should contain the permission bits to assign to the created set and the flag bit IPC_CREAT. The flag IPC_EXCL will force an error to be returned if the set already exists.

When accessing an existing set, you can specify zero for the flag argument. The permission bits are ignored when you are not creating semaphore sets.

The function semget(2) returns an IPC ID if the call is successful. Otherwise, -1 is returned with an error code left in errno.

Listing 24.1 shows the source code used by the utility program to create or access a semaphore set.

Code Listing 24.1. semget.c—Source Module That Creates and Accesses a Semaphore Set

1:   /* semget.c */
2:
3:   #include "semop.h"
4:
5:   void
6:   get_set(int optch,key_t key,int createflg) {
7:       int z;
8:       mode_t um;
9:       mode_t mode;                /* Create permissions */
10:      int flags;                  /* semget(2) flags */
11:
12:      if ( createflg )
13:          flags = IPC_CREAT|IPC_EXCL; /* Create set */
14:      else
15:          flags = 0;              /* Access existing set */
16:
17:      um = umask(077);            /* Query umask */
18:      umask(um);                  /* Restore umask */
19:      mode = 0666 & ~um;          /* Create permissions */
20:
21:      /*
22:       * Create a set of n_sem semaphores :
23:       */
24:      z = semget(key,n_sem,flags|mode);
25:      if ( z == -1 ) {
26:          fprintf(stderr,"%s: -%c
",strerror(errno),optch);
27:          exit(1);
28:      }
29:
30:      semid = z;                  /* Semaphore IPC ID */
31:
32:      printf("  -%c 0x%X => IPC ID %d
",optch,(int)key,semid);
33:      if ( key == IPC_PRIVATE )
34:          printf("  WARNING: IPC_PRIVATE used.
");
35:      fflush(stdout);
36:  }

The function get_set() sets the variable flags to IPC_CREAT|IPC_EXCL when the set is to be created (line 13). Otherwise, flags is set to zero (line 15).

Since the function semget(2) does not use the umask(2) value, the current mask is looked up and applied to the default permissions 0666 line in lines 17–19.

Line 24 calls semget(2) to access or create the set, depending upon the value of its flags variable. The number of semaphores to create (when flags contains IPC_CREAT) is determined by a global variable n_sem. If the function call succeeds, the global variable semid is assigned the IPC ID in line 30.

The following example shows how to create a simple semaphore set of three, using the utility program ./semop:

$ ./semop -k0xFEEDF00D -c3
  -c 0xFEEDF00D => IPC ID 131072
  -c 3 : Created semaphore set -k 0xFEEDF00D
$

The -k0xFEEDF00D option specifies the key, which is followed by the create option -c3. The value 3 indicates that three semaphores are to be created in the set. To confirm that the set was created, invoke the ipcs(1) command. Under FreeBSD, the display appears as follows:

$ ipcs
Message Queues:
T     ID     KEY        MODE       OWNER    GROUP

Shared Memory:
T     ID     KEY        MODE       OWNER    GROUP

Semaphores:
T     ID     KEY        MODE       OWNER    GROUP
s 131072  -17960947 --rw-r-----      ehg      ehg

$

The FreeBSD ipcs(1) command displays the key value as a signed decimal value. Hence, 0xFEEDF00D becomes the decimal value -17960947 in the display. Notice that the IPC ID value is shown as 131072 in this display (your IPC ID may differ).

The created set can be accessed by the utility by IPC key or IPC ID. The following shows how the set is accessed by the key value:

$ ./semop -k0xFEEDF00D -a
  -a 0xFEEDF00D => IPC ID 131072
  There are 3 semaphores in this set.
$

The -a option directs the utility program to access the semaphore set by the last -k key value provided. The same set can also be accessed more directly by use of the IPC ID:

$ ./semop -i131072 -R
  -i 131072 : There are 3 semaphores in this set.
  -R : key    0xFEEDF00D
  -R : IPC ID 131072
  -R : 0 has no SEM_UNDO
  -R : 1 has no SEM_UNDO
  -R : 2 has no SEM_UNDO
$

The option -i131072 identifies the IPC ID of the set, and is enough on its own. The -R option was added so that the IPC key value would be reported along with some other information.