Unix/Linux Go Back    


Linux 2.6 - man page for semctl (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


SEMCTL(P)			    POSIX Programmer's Manual				SEMCTL(P)

NAME
       semctl - XSI semaphore control operations

SYNOPSIS
       #include <sys/sem.h>

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

DESCRIPTION
       The  semctl()  function	operates  on  XSI  semaphores (see the Base Definitions volume of
       IEEE Std 1003.1-2001, Section 4.15, Semaphore).	It is unspecified whether  this  function
       interoperates  with the realtime interprocess communication facilities defined in Realtime
       .

       The semctl() function provides a variety of semaphore control operations as  specified  by
       cmd.  The  fourth  argument  is	optional  and  depends	upon  the operation requested. If
       required, it is of type union semun, which the application shall explicitly declare:

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

       The following semaphore control operations as specified by cmd are executed  with  respect
       to  the semaphore specified by semid and semnum. The level of permission required for each
       operation is shown with each command; see XSI Interprocess Communication  .  The  symbolic
       names for the values of cmd are defined in the <sys/sem.h> header:

       GETVAL Return the value of semval; see <sys/sem.h>. Requires read permission.

       SETVAL Set  the	value of semval to arg.val, where arg is the value of the fourth argument
	      to semctl(). When this command is successfully executed, the  semadj  value  corre-
	      sponding	to  the  specified  semaphore in all processes is cleared. Requires alter
	      permission; see XSI Interprocess Communication .

       GETPID Return the value of sempid. Requires read permission.

       GETNCNT
	      Return the value of semncnt. Requires read permission.

       GETZCNT
	      Return the value of semzcnt. Requires read permission.

       The following values of cmd operate on each semval in the set of semaphores:

       GETALL Return the value of semval for each semaphore in the semaphore set and  place  into
	      the  array  pointed  to by arg.array, where arg is the fourth argument to semctl().
	      Requires read permission.

       SETALL Set the value of semval for each semaphore in the semaphore set  according  to  the
	      array  pointed  to by arg.array, where arg is the fourth argument to semctl(). When
	      this command is successfully executed, the  semadj  values  corresponding  to  each
	      specified semaphore in all processes are cleared.  Requires alter permission.

       The following values of cmd are also available:

       IPC_STAT
	      Place  the  current  value of each member of the semid_ds data structure associated
	      with semid into the structure pointed to by arg.buf, where arg is the fourth  argu-
	      ment  to	semctl().  The	contents  of  this  structure are defined in <sys/sem.h>.
	      Requires read permission.

       IPC_SET
	      Set the value of the following members of the semid_ds  data  structure  associated
	      with semid to the corresponding value found in the structure pointed to by arg.buf,
	      where arg is the fourth argument to semctl():

	      sem_perm.uid
	      sem_perm.gid
	      sem_perm.mode

       The mode bits specified in IPC General Description are copied into the corresponding  bits
       of  the	sem_perm.mode  associated  with  semid.   The stored values of any other bits are
       unspecified.

       This command can only be executed by a process that has an  effective  user  ID	equal  to
       either  that  of a process with appropriate privileges or to the value of sem_perm.cuid or
       sem_perm.uid in the semid_ds data structure associated with semid.

       IPC_RMID
	      Remove the semaphore identifier specified by semid from the system and destroy  the
	      set  of semaphores and semid_ds data structure associated with it. This command can
	      only be executed by a process that has an effective user ID equal to either that of
	      a  process  with	appropriate  privileges  or  to  the  value  of  sem_perm.cuid or
	      sem_perm.uid in the semid_ds data structure associated with semid.

RETURN VALUE
       If successful, the value returned by semctl() depends on cmd as follows:

       GETVAL The value of semval.

       GETPID The value of sempid.

       GETNCNT
	      The value of semncnt.

       GETZCNT
	      The value of semzcnt.

       All others
	      0.

       Otherwise, semctl() shall return -1 and set errno to indicate the error.

ERRORS
       The semctl() function shall fail if:

       EACCES Operation permission is denied to the calling process; see XSI Interprocess  Commu-
	      nication .

       EINVAL The  value  of semid is not a valid semaphore identifier, or the value of semnum is
	      less than 0 or greater than or equal to sem_nsems, or the value of  cmd  is  not	a
	      valid command.

       EPERM  The  argument  cmd is equal to IPC_RMID or IPC_SET and the effective user ID of the
	      calling process is not equal to that of a process with appropriate  privileges  and
	      it is not equal to the value of sem_perm.cuid or sem_perm.uid in the data structure
	      associated with semid.

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

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       The  fourth parameter in the SYNOPSIS section is now specified as "..."	in order to avoid
       a clash with the ISO C standard when referring to the union semun (as defined in Issue  3)
       and for backwards-compatibility.

       The  POSIX  Realtime  Extension defines alternative interfaces for interprocess communica-
       tion. Application developers who need to use IPC should design their applications so  that
       modules	using  the IPC routines described in XSI Interprocess Communication can be easily
       modified to use the alternative interfaces.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       XSI  Interprocess  Communication  ,  Realtime  ,  semget()  ,  semop()  ,  sem_close()	,
       sem_destroy()  ,  sem_getvalue()  ,  sem_init() , sem_open() , sem_post() , sem_unlink() ,
       sem_wait() , the Base Definitions volume of IEEE Std 1003.1-2001, <sys/sem.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					SEMCTL(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:55 AM.