unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



semop(2)							     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
  <&lt;sys/types.h>&gt;	and <&lt;sys/ipc.h>&gt;	before the one for <&lt;sys/sem.h>&gt; if programs
  are being developed for multiple platforms. The additional #include state-
  ments	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 stan-
  dards.

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 indus-
  try standards	and associated tags.

PARAMETERS

  semid	    Specifies the ID of	the semaphore set.

  sops	    Points to the user-defined array of	sembuf structures that con-
	    tain the semaphore operations.

  nsops	    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:

  sem_num   Specifies an individual semaphore within the semaphore set.

  sem_op    Specifies the operation to perform on the semaphore.

  sem_flg   Specifies various flags for	the operations.	 The possible values
	    are:

	    SEM_UNDO  Instructs	the kernel to adjust the process's adjust-
		      on-exit value for	a modified semaphore.  When the	pro-
		      cess 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.

	    IPC_NOWAIT
		      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 permis-
  sion,	the semop() function does one of the following:

    +  If the semaphore'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 semval 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 decre-
       mented; 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	cal-
       ling 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 execu-
       tion as directed	by the sigaction() function.

  If sem_op is a positive integer and the calling process has modify permis-
  sion,	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 immediately.

    +  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() incre-
       ments 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 execu-
       tion 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 specified opera-
  tion.	 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:

  [E2BIG]   The	nsops parameter	is greater than	the system-defined maximum.

  [EACCES]  The	calling	process	does not have the required permission.

  [EACCES]  The	process	does not have read or write access permission to the
	    semaphore set with respect to all access control policies.

  [EAGAIN]  Both sem_flg and IPC_NOWAIT	are true, but the requested operation
	    has	caused the calling process to be suspended.

  [EFAULT]  Indicates that the requested address is in some way	invalid, for
	    example, out of bounds.

  [EFBIG]   The	sem_num	parameter is less than 0 (zero)	or greater than	or
	    equal to the number	of semaphores in semid.

  [EIDRM]   The	semaphore ID specified by the semid parameter has been
	    removed from the system.

  [EINTR]   The	semop()	function was interrupted by a signal.

  [EINVAL]  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.

  [ENOSPC]  The	system-defined limit on	the number of processes	using
	    SEM_UNDO was exceeded.

  [ERANGE]  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.

  [ENOSYS]  [Tru64 UNIX]  The requested	operation is not supported by this
	    implementation.

RELATED	INFORMATION

  Functions: exec(2), exit(2), fork(2),	semctl(2), semget(2)

  Data Structures: semid_ds(4)

  Standards: standards(5)