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+Linux%2fi386+9>

home | help