semget()--Get Semaphore Set with Key

 #include <sys/sem.h>
 #include <sys/stat.h>

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

The semget() function either creates a new semaphore set or returns the semaphore set identifier associated with the key parameter for an existing semaphore set. A new semaphore set is created if one of the following is true:

• The key parameter is equal to IPC_PRIVATE.
  
  
• The key parameter does not already have a semaphore set identifier associated with it and the IPC_CREAT flag is specified in the semflg parameter.
  

The system maintains status information about a semaphore set which can be retrieved with the semctl() function. When a new semaphore set is created, the system initializes the members of the semid_ds structure as follows:

• sem_perm.cuid and sem_perm.uid are set to the current user ID of the thread.
  
  
• sem_perm.cgid and sem_perm.gid are set to the current group ID of the thread.
  
  
• The low-order 9 bits of shm_perm.mode are set equal to the low-order 9 bits of the shmflg parameter.
  
  
• sem_nsems is set to the value specified in the nsems parameter.
  
  
• sem_ctime is set to the current time.
  
  
• sem_otime is set to zero.

Parameters

key

(Input) Key associated with the semaphore set. A key of IPC_PRIVATE (0x00000000) guarantees that a unique semaphore set is created. A key can also be specified by the caller or generated by the ftok() function.

nsems

(Input) Number of semaphores in the semaphore set. The number of semaphores in the set cannot be changed after the semaphore set is created. If an existing semaphore set is being accessed, nsems can be zero.

semflg

(Input) Operations and permission flags. The semflg parameter value is either zero, or is obtained by performing an OR operation on one or more of the following constants:

S_IRUSR (0x00000100)

Allow the owner of the semaphore set to read from it.

S_IWUSR (0x00000080)

Allow the owner of the semaphore set to write to it.

S_IRGRP (0x00000020)

Allow the group of the semaphore set to read from it.

S_IWGRP (0x00000010)

Allow the group of the semaphore set to write to it.

S_IROTH (0x00000004)

Allow others to read from the semaphore set.

S_IWOTH (0x00000002)

Allow others to write to the semaphore set.

IPC_CREAT (0x00000200)

Create the semaphore set if it does not exist.

IPC_EXCL (0x00000400)

Return an error if the IPC_CREAT flag is set and the semaphore set already exists.

Authorities

Authorization Required for semget()

Note: If the thread is accessing a semaphore set that already exists, the mode specified in the last 9 bits of semflg must be a subset of the mode of the existing semaphore set.

Return Value

Error Conditions

If semget() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

A semaphore set identifier exists for the parameter key, but permissions specified in the low-order 9 bits of semflg are not a subset of the current permissions.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

The semaphore set has been damaged by a previous semaphore operation.

[EEXIST]

File exists.

The file specified already exists and the specified operation requires that it not exist.

The named file, directory, or path already exists.

A semaphore identifier exists for the key parameter, and both the IPC_CREAT and IPC_EXCL flags are set in the semflg parameter.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

• The value of nsems is either less than or equal to zero, or greater than the system-imposed limit.
• A semaphore identifier exists for the parameter key, but the number of semaphores in the set associated with it is less than nsems and nsems is not zero.

[ENOENT]

No such path or directory.

The directory or a component of the path name specified does not exist.

A named file or directory does not exist or is an empty string.

A semaphore set identifier does not exist for the key parameter, and the IPC_CREAT flag is not set in the semflg parameter.

[ENOSPC]

No space available.

The requested operations required additional space on the device and there is no space left. This could also be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.

Insufficient space remains to hold the intended file, directory, or link.

A semaphore set identifier cannot be created because the system limit on the maximum number of allowed semaphore set identifiers would be exceeded.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

1. The best way to generate a unique key is to use the ftok() function.
   
   
2. A semctl() call specifying a cmd parameter of SETALL should be used to initialize the semaphore values after the semaphore set is created.

Related Information

• The <sys/sem.h> file (see Header Files for UNIX-Type Functions)
  
  
• ftok()--Generate IPC Key from File Name
  
  
• semctl()--Perform Semaphore Control Operations
  
  
• semop()--Perform Semaphore Operations on Semaphore Set

Example

See Code disclaimer information for information pertaining to code examples.

For an example of using this function, see Using Semaphores and Shared Memory in Examples: APIs.