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

FreeBSD Manual Pages


home | help
semctl(2)			 System	Calls			     semctl(2)

       semctl -	semaphore control operations

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

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

       The  semctl()  function	provides a variety of semaphore	control	opera-
       tions as	specified by cmd. The fourth argument is  optional,  depending
       upon  the  operation  requested.	 If required, it is of type  union se-
       mun, which must be explicitly declared by the application program.

       union semun {
	       int	       val;
	       struct semid_ds *buf;
	       ushort_t	       *array;
       } arg ;

       The permission required for a semaphore operation is given as  {token},
       where  token is the type	of permission needed.  The types of permission
       are interpreted as follows:

       00400	READ by	user
       00200	ALTER by user
       00040	READ by	group
       00020	ALTER by group
       00004	READ by	others
       00002	ALTER by others

       See the Semaphore Operation Permissions subsection of  the  DEFINITIONS
       section of intro(2) for more information. The following semaphore oper-
       ations as specified by cmd are executed with respect to	the  semaphore
       specified by semid and semnum.

       GETVAL	       Return the value	of  semval (see	intro(2)). {READ}

       SETVAL	       Set  the	value of  semval to arg.val. {ALTER} When this
		       command is successfully executed, the semadj value cor-
		       responding  to the specified semaphore in all processes
		       is cleared.

       GETPID	       Return the value	of (int) sempid. {READ}

       GETNCNT	       Return the value	of semncnt. {READ}

       GETZCNT	       Return the value	of semzcnt. {READ}

       The following operations	return and set,	respectively, every semval  in
       the set of semaphores.

       GETALL	       Place  semvals  into  array  pointed  to	 by arg.array.

       SETALL	       Set semvals  according  to  the	array  pointed	to  by
		       arg.array.  {ALTER}. When this cmd is successfully exe-
		       cuted, the semadj values	corresponding to  each	speci-
		       fied semaphore in all processes are cleared.

       The following operations	are also available.

       IPC_STAT	       Place  the  current  value  of  each member of the data
		       structure associated  with  semid  into	the  structure
		       pointed	to  by arg.buf.	The contents of	this structure
		       are defined in intro(2).	{READ}

       IPC_SET	       Set the value of	the  following	members	 of  the  data
		       structure  associated  with  semid to the corresponding
		       value found in the structure pointed to by arg.buf:

		       sem_perm.mode  /* access	permission bits	only */

		       This command can	be executed only by a process that has
		       either  the  {PRIV_IPC_OWNER} privilege or an effective
		       user  ID	 equal	to  the	 value	of  msg_perm.cuid   or
		       msg_perm.uid  in	 the  data  structure  associated with
		       msqid. Only a process  with  the	 {PRIV_SYS_IPC_CONFIG}
		       privilege can raise the value of	msg_qbytes.

       IPC_RMID	       Remove the semaphore identifier specified by semid from
		       the system and destroy the set of semaphores  and  data
		       structure  associated with it. This command can be exe-
		       cuted only by a process that has	 the  {PRIV_IPC_OWNER}
		       privilege or an effective user ID equal to the value of
		       sem_perm.cuid or	sem_perm.uid in	the data structure as-
		       sociated	with semid.

       Upon  successful	 completion, the value returned	depends	on cmd as fol-

       GETVAL	       the value of semval

       GETPID	       the value of (int) sempid

       GETNCNT	       the value of semncnt

       GETZCNT	       the value of semzcnt

       All other successful completions	return	0; otherwise, -1  is  returned
       and errno is set	to indicate the	error.

       The semctl() function will fail if:

       EACCES	       Operation  permission  is denied	to the calling process
		       (see intro(2)).

       EFAULT	       The source or target is not a valid address in the user

       EINVAL	       The semid argument is not a valid semaphore identifier;
		       the semnum argument is less  than  0  or	 greater  than
		       sem_nsems  -1;  or the cmd argument is not a valid com-
		       mand or is IPC_SET and sem_perm.uid or sem_perm.gid  is
		       not valid.

       EPERM	       The  cmd	 argument is equal to IPC_RMID or IPC_SET, the
		       effective user ID of the	calling	process	is  not	 equal
		       to  the	value  of sem_perm.cuid	or sem_perm.uid	in the
		       data   structure	   associated	 with	 semid,	   and
		       {PRIV_IPC_OWNER}	 is  not asserted in the effective set
		       of the calling process.

       EOVERFLOW       The cmd argument	is IPC_STAT and	 uid  or  gid  is  too
		       large  to  be  stored  in  the  structure pointed to by

       ERANGE	       The cmd argument	is SETVAL or SETALL and	the  value  to
		       which  semval  is  to be	set is greater than the	system
		       imposed maximum.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |

       ipcs(1),	intro(2), semget(2), semop(2),	attributes(5),	privileges(5),

SunOS 5.10			  1 Feb	2003			     semctl(2)


Want to link to this manual page? Use this URL:

home | help