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

FreeBSD Manual Pages

  
 
  

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

NAME
       semctl -	semaphore control operations

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

       int semctl(int semid, int semnum, int cmd, ...);

DESCRIPTION
       The  function semctl performs the control operation specified by	cmd on
       the semaphore set identified by semid, or on the	semnum-th semaphore of
       that set.  (Semaphores are numbered starting at 0.)

       This  function  has  three  or four arguments. When there are four, the
       call is semctl(semid,semnum,cmd,arg); where the fourth argument arg has
       a type union semun defined as follows:

       #if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED)
       /* union	semun is defined by including <sys/sem.h> */
       #else
       /* according to X/OPEN we have to define	it ourselves */
       union semun {
	     int val;		       /* value	for SETVAL */
	     struct semid_ds *buf;     /* buffer for IPC_STAT, IPC_SET */
	     unsigned short *array;    /* array	for GETALL, SETALL */
				       /* Linux	specific part: */
	     struct seminfo *__buf;    /* buffer for IPC_INFO */
       };
       #endif

       Legal values for	cmd are:

       IPC_STAT	   Copy	 info  from  the semaphore set data structure into the
		   structure pointed to	by arg.buf.  The  argument  semnum  is
		   ignored.   The calling process must have read access	privi-
		   leges on the	semaphore set.

       IPC_SET	   Write the values of some members of the semid_ds  structure
		   pointed  to by arg.buf to the semaphore set data structure,
		   updating also its  sem_ctime	 member.   Considered  members
		   from	 the  user  supplied  struct  semid_ds	pointed	 to by
		   arg.buf are

			sem_perm.uid
			sem_perm.gid
			sem_perm.mode  /* only lowest 9-bits */

		   The effective user-ID of the	calling	process	must  be  that
		   of  the  super-user,	 or  match the creator or owner	of the
		   semaphore set.  The argument	semnum is ignored.

       IPC_RMID	   Immediately remove the semaphore set	and  its  data	struc-
		   tures awakening all waiting processes (with an error	return
		   and errno set to EIDRM).   The  effective  user-ID  of  the
		   calling  process  must  be that of the super-user, or match
		   the creator or owner	of the semaphore  set.	 The  argument
		   semnum is ignored.

       GETALL	   Return semval for all semaphores of the set into arg.array.
		   The argument	semnum is ignored.  The	calling	 process  must
		   have	read access privileges on the semaphore	set.

       GETNCNT	   The	system	call returns the value of semncnt for the sem-
		   num-th semaphore of the set (i.e. the number	 of  processes
		   waiting  for	 an increase of	semval for the semnum-th sema-
		   phore of the	set).  The  calling  process  must  have  read
		   access privileges on	the semaphore set.

       GETPID	   The	system	call  returns the value	of sempid for the sem-
		   num-th semaphore of the set (i.e. the pid  of  the  process
		   that	 executed  the last semop call for the semnum-th sema-
		   phore of the	set).  The  calling  process  must  have  read
		   access privileges on	the semaphore set.

       GETVAL	   The	system	call  returns the value	of semval for the sem-
		   num-th semaphore of the set.	 The calling process must have
		   read	access privileges on the semaphore set.

       GETZCNT	   The	system	call returns the value of semzcnt for the sem-
		   num-th semaphore of the set (i.e. the number	 of  processes
		   waiting for semval of the semnum-th semaphore of the	set to
		   become 0).  The calling process must	have read access priv-
		   ileges on the semaphore set.

       SETALL	   Set	semval	for all	semaphores of the set using arg.array,
		   updating also the sem_ctime member of the  semid_ds	struc-
		   ture	 associated  to	the set.  Undo entries are cleared for
		   altered semaphores in all processes.	 Processes sleeping on
		   the	wait  queue  are  awakened if some semval becomes 0 or
		   increases.  The argument semnum is  ignored.	  The  calling
		   process  must have alter access privileges on the semaphore
		   set.

       SETVAL	   Set the value of semval to arg.val for the semnum-th	 sema-
		   phore of the	set, updating also the sem_ctime member	of the
		   semid_ds structure associated to the	set.  Undo entries are
		   cleared for altered semaphores in all processes.  Processes
		   sleeping on the wait	queue are awakened if semval becomes 0
		   or  increases.   The	calling	process	must have alter	access
		   privileges on the semaphore set.

RETURN VALUE
       On failure semctl returns -1 with errno indicating the  error.	Other-
       wise  the  system  call returns a nonnegative value depending on	cmd as
       follows:

       GETNCNT	  the value of semncnt.

       GETPID	  the value of sempid.

       GETVAL	  the value of semval.

       GETZCNT	  the value of semzcnt.

       All other cmd values return 0 on	success.

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

       EACCES	  The calling process has no access permissions	needed to exe-
		  cute cmd.

       EFAULT	  The  address pointed to by arg.buf or	arg.array isn't	acces-
		  sible.

       EIDRM	  The semaphore	set was	removed.

       EINVAL	  Invalid value	for cmd	or semid.

       EPERM	  The argument cmd has value IPC_SET or	IPC_RMID but the call-
		  ing  process has insufficient	privileges to execute the com-
		  mand.

       ERANGE	  The argument cmd has value SETALL or SETVAL and the value to
		  which	 semval	 has to	be set (for some semaphore of the set)
		  is less than 0 or  greater  than  the	 implementation	 value
		  SEMVMX.

NOTES
       The  IPC_INFO,  SEM_STAT	 and  SEM_INFO	control	 calls are used	by the
       ipcs(8) program to provide information on allocated resources.  In  the
       future  these  can be modified as needed	or moved to a proc file	system
       interface.

       Various fields in a struct semid_ds were	shorts	under  Linux  2.2  and
       have  become longs under	Linux 2.4. To take advantage of	this, a	recom-
       pilation	under glibc-2.1.91 or later should suffice.  (The kernel  dis-
       tinguishes old and new calls by a IPC_64	flag in	cmd.)

       The following system limit on semaphore sets affects a semctl call:

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

       For greater portability it is best to  always  call  semctl  with  four
       arguments.

       Under  Linux,  the  function semctl is not a system call, but is	imple-
       mented via the system call ipc(2).

CONFORMING TO
       SVr4, SVID.  SVr4 documents more	error conditions EINVAL	and EOVERFLOW.

SEE ALSO
       ipc(2), shmget(2), shmat(2), shmdt(2), ipc(5)

Linux 2.4.1			  2001-12-21			     SEMCTL(2)

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

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

home | help