Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SEMOP(2)		   Linux Programmer's Manual		      SEMOP(2)

NAME
       semop - semaphore operations

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

       int semop(int semid, struct sembuf *sops, unsigned nsops);

DESCRIPTION
       A semaphore is represented by an	anonymous structure including the fol-
       lowing members:

	   unsigned short  semval;   /*	semaphore value	*/
	   unsigned short  semzcnt;  /*	# waiting for zero */
	   unsigned short  semncnt;  /*	# waiting for increase */
	   pid_t	   sempid;   /*	process	that did last op */

       The function semop performs operations on selected members of the sema-
       phore  set indicated by semid.  Each of the nsops elements in the array
       pointed to by sops specifies an operation to be performed  on  a	 sema-
       phore by	a struct sembuf	including the following	members:

	   unsigned short sem_num;  /* semaphore number	*/
	   short sem_op;	    /* semaphore operation */
	   short sem_flg;	    /* operation flags */

       Flags  recognized in sem_flg are	IPC_NOWAIT and SEM_UNDO.  If an	opera-
       tion asserts SEM_UNDO, it will be undone	when the process exits.

       The set of operations contained in sops is performed  atomically,  that
       is, the operations are performed	at the same time, and only if they can
       all be simultaneously performed.	 The behaviour of the system  call  if
       not all operations can be performed immediately depends on the presence
       of the IPC_NOWAIT flag in  the  individual  sem_flg  fields,  as	 noted
       below.

       Each  operation	is  performed on the sem_num-th	semaphore of the sema-
       phore set, where	the first semaphore of the set is semaphore 0.	 There
       are three types of operation, distinguished by the value	of sem_op.

       If  sem_op  is a	positive integer, the operation	adds this value	to the
       semaphore value (semval).  Furthermore, if  SEM_UNDO  is	 asserted  for
       this  operation,	the system updates the process undo count (semadj) for
       this semaphore.	This operation can always proceed - it never forces  a
       process to wait.	 The calling process must have alter permission	on the
       semaphore set.

       If sem_op is zero, the process must have	read access permission on  the
       semaphore set.  This is a "wait-for-zero" operation: if semval is zero,
       the operation can immediately proceed.	Otherwise,  if	IPC_NOWAIT  is
       asserted	 in  sem_flg,  the  system call	fails with errno set to	EAGAIN
       (and none of the	operations in sops is performed).   Otherwise  semzcnt
       (the  count  of	processes waiting until	this semaphore's value becomes
       zero) is	incremented by one and the process sleeps  until  one  of  the
       following occurs:

       o      semval  becomes  0, at which time	the value of semzcnt is	decre-
	      mented.

       o      The semaphore set	is removed: the	system call fails, with	 errno
	      set to EIDRM.

       o      The  calling  process  catches a signal: the value of semzcnt is
	      decremented and the system call fails, with errno	set to EINTR.

       If sem_op is less than zero, the	process	must have alter	permission  on
       the  semaphore set.  If semval is greater than or equal to the absolute
       value of	sem_op,	the operation can proceed  immediately:	 the  absolute
       value of	sem_op is subtracted from semval, and, if SEM_UNDO is asserted
       for this	operation, the system updates the process undo count  (semadj)
       for  this  semaphore.   If the absolute value of	sem_op is greater than
       semval, and IPC_NOWAIT is asserted in sem_flg, the system  call	fails,
       with  errno  set	 to EAGAIN (and	none of	the operations in sops is per-
       formed).	 Otherwise semncnt (the	counter	of processes waiting for  this
       semaphore's  value  to  increase) is incremented	by one and the process
       sleeps until one	of the following occurs:

       o      semval becomes greater than or equal to the  absolute  value  of
	      sem_op,  at  which time the value	of semncnt is decremented, the
	      absolute value of	sem_op	is  subtracted	from  semval  and,  if
	      SEM_UNDO	is asserted for	this operation,	the system updates the
	      process undo count (semadj) for this semaphore.

       o      The semaphore set	is removed from	the system:  the  system  call
	      fails with errno set to EIDRM.

       o      The  calling  process  catches a signal: the value of semncnt is
	      decremented and the system call fails with errno set to EINTR.

       On successful completion, the sempid value for each semaphore specified
       in the array pointed to by sops is set to the process ID	of the calling
       process.	 In addition, the sem_otime is set to the current time.

RETURN VALUE
       If successful the system	call returns 0,	otherwise it returns  -1  with
       errno indicating	the error.

ERRORS
       On failure, errno is set	to one of the following:

       E2BIG  The argument nsops is greater than SEMOPM, the maximum number of
	      operations allowed per system call.

       EACCES The calling process has no access	permissions on	the  semaphore
	      set as required by one of	the specified operations.

       EAGAIN An  operation  could  not	proceed	immediately and	IPC_NOWAIT was
	      asserted in its sem_flg.

       EFAULT The address pointed to by	sops isn't accessible.

       EFBIG  For some operation the value  of	sem_num	 is  less  than	 0  or
	      greater than or equal to the number of semaphores	in the set.

       EIDRM  The semaphore set	was removed.

       EINTR  While blocked in this system call, the process caught a signal.

       EINVAL The  semaphore set doesn't exist,	or semid is less than zero, or
	      nsops has	a non-positive value.

       ENOMEM The sem_flg of some operation asserted SEM_UNDO and  the	system
	      does not have enough memory to allocate the undo structure.

       ERANGE For  some	 operation  sem_op+semval  is greater than SEMVMX, the
	      implementation dependent maximum value for semval.

NOTES
       The sem_undo structures of a process aren't inherited across a  fork(2)
       system call, but	they are inherited across a execve(2) system call.

       semop  is  never	 automatically	restarted after	being interrupted by a
       signal handler, regardless of the setting of the	SA_RESTART flags  when
       establishing a signal handler.

       semadj is a per-process integer which is	simply the (negative) count of
       all semaphore operations	performed specifying the SEM_UNDO flag.	  When
       a  semaphore's value is directly	set using the SETVAL or	SETALL request
       to semctl(2), the corresponding semadj  values  in  all	processes  are
       cleared.

       The  semval, sempid, semzcnt, and semnct	values for a semaphore can all
       be retrieved using appropriate semctl(2)	calls.

       The followings are limits on semaphore set resources affecting a	 semop
       call:

       SEMOPM Maximum number of	operations allowed for one semop call (32).

       SEMVMX Maximum  allowable  value	 for  semval: implementation dependent
	      (32767).

       The implementation has no intrinsic limits for the adjust on exit maxi-
       mum  value  (SEMAEM), the system	wide maximum number of undo structures
       (SEMMNU)	and the	per-process maximum  number  of	 undo  entries	system
       parameters.

BUGS
       When  a	process	terminates, its	set of associated semadj structures is
       used to undo the	effect of all of the semaphore operations it performed
       with  the SEM_UNDO flag.	 This raises a difficulty: if one (or more) of
       these semaphore adjustments would result	in an attempt  to  decrease  a
       semaphore's  value  below  zero,	what should an implementation do?  One
       possible	approach would be to block until all the semaphore adjustments
       could  be  performed.  This is however undesirable since	it could force
       process termination to block for	 arbitrarily  long  periods.   Another
       possibility  is	that such semaphore adjustments	could be ignored alto-
       gether (somewhat	analogously to failing when  IPC_NOWAIT	 is  specified
       for  a semaphore	operation).  Linux adopts a third approach: decreasing
       the semaphore value as far as possible (i.e.,  to  zero)	 and  allowing
       process termination to proceed immediately.

CONFORMING TO
       SVr4,  SVID.  SVr4 documents additional error conditions	EINVAL,	EFBIG,
       ENOSPC.

SEE ALSO
       ipc(5), semctl(2), semget(2), sigaction(2)

Linux 2.4			  2002-01-08			      SEMOP(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | NOTES | BUGS | CONFORMING TO | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=semop&sektion=2&manpath=Red+Hat+9>

home | help