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 returns the semaphore ID associated with the specified semaphore key.

Parameters

key

(Input) Key associated with the semaphore set. Specifying a key of IPC_PRIVATE guarantees that a unique semaphore set is created. A key also can be generated by the caller or by calling 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 0, or is obtained by performing an OR operation on one or more of the following constants:

S_IRUSR

Permits the creator of the semaphore set to read it.

S_IWUSR

Permits the creator of the semaphore set to write it.

S_IRGRP

Permits the group associated with the semaphore set to read it.

S_IWGRP

Permits the group associated with the semaphore set to write it.

S_IROTH

Permits others to read the semaphore set.

S_IWOTH

Permits others to write the semaphore set.

IPC_CREAT

Creates the semaphore set if it does not already exist.

IPC_EXCL

Causes semget() to fail if IPC_CREAT is also set and the semaphore set already exists.

Authorities

Figure 1-12. Authorization Required for semget()

Object Referred to	Authority Required	errno
Semaphore set to be created	None	None
Existing semaphore set to be accessed	See Note	EACCES
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

value

semget() was successful. The value returned is the semaphore ID associated with the key parameter.

-1

semget() was not successful. The errno variable is set to indicate the error.

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.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

A semaphore identifier exists for the parameter key, but operation permission as specified by the low-order 9 bits of semflg would not be granted.

[EDAMAGE]

A damaged object was encountered.

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

The value of key corresponds to a semaphore set that has been marked as 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 parameter key, but ((semflg & IPC_CREAT) && (semflg & IPC_EXCL)) is not zero. (& is a bitwise AND; && is a logical AND.)

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

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 identifier does not exist for the parameter key, and (semflg & IPC_CREAT) is equal to zero.

[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 identifier is to be created but the system-imposed limit on the maximum number of allowed semaphores system-wide 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. semget() creates a semaphore set and its associated semid_ds data structure if one of the following is true:

   • The semaphore key is IPC_PRIVATE.

   • A semaphore set is not already associated with the semaphore key, and the IPC_CREAT flag is set.

2. When the semaphore set is created, the semid_ds data structure associated with the semaphore set is initialized as follows:

   • The sem_perm.cuid and sem_perm.uid values are set to the current user ID (uid) of the thread.

   • The sem_perm.cgid and sem_perm.gid values are set to the current group ID (gid) of the thread.

   • The sem_perm.mode is set according to the permissions specified in semflg.

   • The number of semaphores, sem_nsems, is set to the nsems parameter.

   • sem_otime is set to zero and sem_ctime is set to the current time.

3. 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

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