semop(2) [netbsd man page]
SEMOP(2) BSD System Calls Manual SEMOP(2) NAME
semop -- semaphore operations LIBRARY
Standard C Library (libc, -lc) SYNOPSIS
#include <sys/sem.h> int semop(int semid, struct sembuf *sops, size_t nsops); DESCRIPTION
semop() provides a number of atomic operations on a set of semaphores. The semaphore set is specified by semid, sops is an array of sema- phore operations, and nsops is the number of operations in this array. The sembuf structures in the array contain the following members: unsigned short sem_num; /* semaphore # */ short sem_op; /* semaphore operation */ short sem_flg; /* operation flags */ Each operation (specified in sem_op) is applied to semaphore number sem_num in the set of semaphores specified by semid. The value of sem_op determines the action taken in the following way: o sem_op is less than 0. The current process is blocked until the value of the semaphore is greater than or equal to the absolute value of sem_op. The absolute value of sem_op is then subtracted from the value of the semaphore, and the calling process continues. Negative values of sem_op are thus used to enter critical regions. o sem_op is greater than 0. Its value is added to the value of the specified semaphore. This is used to leave critical regions. o sem_op is equal to 0. The calling process is blocked until the value of the specified semaphore reaches 0. The behaviour of each operation is influenced by the flags set in sem_flg in the following way: IPC_NOWAIT In the case where the calling process would normally block, waiting for a semaphore to reach a certain value, IPC_NOWAIT makes the call return immediately, returning a value of -1 and setting errno to EAGAIN. SEM_UNDO Keep track of the changes that this call makes to the value of a semaphore, so that they can be undone when the calling process terminates. This is useful to prevent other processes waiting on a semaphore to block forever, should the process that has the semaphore locked terminate in a critical section. RETURN VALUES
Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error. ERRORS
semop() will fail if: [EINVAL] There is no semaphore associated with semid. [EIDRM] The semaphore set was removed while the process was waiting for one of its semaphores to reach a certain value. [EACCES] The calling process has no permission to access the specified semaphore set. [E2BIG] The value of nsops is too big. The maximum is defined as MAX_SOPS in <sys/sem.h>. [EFBIG] sem_num in one of the sem_buf structures is less than 0, or greater than the actual number of semaphores in the set speci- fied by semid. [ENOSPC] SEM_UNDO was requested, and there is not enough space left in the kernel to store the undo information. [EAGAIN] The requested operation can not immediately be performed, and IPC_NOWAIT was set in sem_flg. [EFAULT] sops points to an illegal address. SEE ALSO
semctl(2), semget(2) STANDARDS
The semop system call conforms to X/Open System Interfaces and Headers Issue 5 (``XSH5''). HISTORY
Semaphores appeared in the first release of AT&T System V UNIX. BSD
November 3, 2005 BSD
Check Out this Related Man Page
semop(2) System Calls Manual semop(2) NAME
semop - Performs semaphore operations SYNOPSIS
#include <sys/sem.h> int semop( int semid, struct sembuf *sops, size_t nsops); The following declaration of the nsops parameter does not conform to current standards and is supported only for backward compatibility: u_int nsops Application developers may want to specify #include statements for <sys/types.h> and <sys/ipc.h> before the one for <sys/sem.h> if programs are being developed for multiple platforms. The additional #include statements are not required on Tru64 UNIX systems or by ISO or X/Open standards, but may be required on other vendors' systems that conform to these standards. STANDARDS
Interfaces documented on this reference page conform to industry standards as follows: semop(): XSH5.0 Refer to the standards(5) reference page for more information about industry standards and associated tags. PARAMETERS
Specifies the ID of the semaphore set. Points to the user-defined array of sembuf structures that contain the semaphore operations. The number of sembuf structures in the array. DESCRIPTION
The semop() function performs operations on the semaphores in the specified semaphore set. The semaphore operations are defined in the sops array. The sops array contains nsops elements, each of which is represented by a sembuf structure. The sembuf structure (from sys/sem.h) is shown here: struct sembuf { u_short sem_num; short sem_op; short sem_flg; }; The fields in the sembuf structure are defined as follows: Specifies an individual semaphore within the semaphore set. Specifies the oper- ation to perform on the semaphore. Specifies various flags for the operations. The possible values are: Instructs the kernel to adjust the process's adjust-on-exit value for a modified semaphore. When the process exits, the kernel uses this value to restore the semaphore to the value it had before any modifications by the process. This flag is used to prevent semaphore locking by a process that no longer exists. Instructs the kernel to return an error condition if a requested operation would cause the process to sleep. If the kernel returns an error condition, none of the requested semaphore operations are performed. The sem_op operation is specified as a negative integer, a positive integer, or 0 (zero). The effects of these three values are described below. If sem_op is a negative integer and the calling process has modify permission, the semop() function does one of the following: If the sema- phore's current value (in semval) is equal to or greater than the absolute value of sem_op, the absolute value of sem_op is subtracted from semval. If SEM_UNDO is set, the absolute value of sem_op is added to the calling process' adjust-on-exit value for the semaphore. If sem- val is less than the absolute value of sem_op and IPC_NOWAIT is set, semop() returns immediately. If semval is less than the absolute value of sem_op and IPC_NOWAIT is not set, semop() increments the semaphore's semncnt value and suspends the calling process. If the process is suspended, it sleeps until one of the following occurs: The semval value becomes equal to or greater than the absolute value of sem_op. In this case, the semaphore's semncnt value is decremented; the absolute value of sem_op is subtracted from semval; and, if SEM_UNDO is set, the absolute value of sem_op is added to the calling process's adjust-on-exit value for the semaphore. The semaphore set (specified by semid) is removed from the system. In this case, errno is set equal to [EIDRM] and a value of -1 is returned to the calling process. The calling process catches a signal. In this case, the semaphore's semncnt value is decremented, and the calling process resumes execution as directed by the sigaction() function. If sem_op is a positive integer and the calling process has modify permission, semop() adds the sem_op value to the semaphore's current semval value. If SEM_UNDO is set, the sem_op value is subtracted from the calling process's adjust-on-exit value for the semaphore. If sem_op is 0 (zero) and the calling process has read permission, semop() does one of the following: If semval is 0, semop() returns imme- diately. If semval is not equal to 0 and IPC_NOWAIT is set, semop() returns immediately. If semval is not equal to 0 and IPC_NOWAIT is not set, semop() increments the semaphore's semzcnt value and suspends the calling process. If the process is suspended, it sleeps until one of the following occurs: The semval value becomes 0 (zero). In this case, the semaphore's semncnt value is decremented. The semaphore set (specified by semid) is removed from the system. In this case, errno is set equal to [EIDRM] and a value of -1 is returned to the calling process. The calling process catches a signal. In this case, the semaphore's semncnt value is decremented, and the calling process resumes execution as directed by the sigaction() function. The calling process must have read (sense) or write (alter) permission to the semaphore set for all access control policies for each speci- fied operation. If any operation accesses the semaphore set in a way that is not allowed according to one of the access control policies, access is denied. NOTES
[Tru64 UNIX] Semaphore operations are performed atomically; that is, either all of the requested operations are performed, or none are. If the kernel goes to sleep while doing the operations, it restores all of the semaphores in the set to their previous values, at the start of the semop() function. RETURN VALUES
Upon successful completion, the semop() function returns a value of 0 (zero) and the sempid value for each semaphore that is operated upon is set to the process ID of the calling process. If the semop() function fails, a value of -1 is returned and errno is set to indicate the error. ERRORS
The semop() function sets errno to the specified values for the following conditions: The nsops parameter is greater than the system- defined maximum. The calling process does not have the required permission. The process does not have read or write access permission to the semaphore set with respect to all access control policies. Both sem_flg and IPC_NOWAIT are true, but the requested operation has caused the calling process to be suspended. Indicates that the requested address is in some way invalid, for example, out of bounds. The sem_num parameter is less than 0 (zero) or greater than or equal to the number of semaphores in semid. The semaphore ID specified by the semid parameter has been removed from the system. The semop() function was interrupted by a signal. The semid parameter is not a valid semaphore ID, or the number of semaphores for which SEM_UNDO is requested exceeds the system-defined limit. The system-defined limit on the number of processes using SEM_UNDO was exceeded. An operation caused a semval to overflow the system-defined limit, or an operation caused an adjust-on-exit value to exceed the system-defined limit. [Tru64 UNIX] The requested operation is not supported by this imple- mentation. RELATED INFORMATION
Functions: exec(2), exit(2), fork(2), semctl(2), semget(2) Data Structures: semid_ds(4) Standards: standards(5) delim off semop(2)