unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.9)
Page:
Section:
Apropos / Subsearch:
optional field



System Calls                                             semop(2)



NAME
     semop, semtimedop - semaphore operations

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

     int semop(int semid, struct sembuf *sops, size_t nsops);

     int semtimedop(int semid, struct sembuf *sops, size_t nsops,
     const struct timespec *timeout);

DESCRIPTION
     The semop() function is used to perform atomically an  array
     of  semaphore operations on the set of semaphores associated
     with the semaphore identifier specified by semid.  The  sops
     argument  is  a  pointer to the array of semaphore-operation
     structures. The nsops argument is the number of such  struc-
     tures in the array.

     Each sembuf structure contains the following members:


          short     sem_num;    /* semaphore number */
          short     sem_op;     /* semaphore operation */
          short     sem_flg;    /* operation flags */

     Each semaphore operation specified by sem_op is performed on
     the  corresponding semaphore specified by semid and sem_num.
     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 section of  intro(2)
     for more information.

     A process maintains a value, semadj, for each  semaphore  it
     modifies.  This  value  contains  the  cumulative  effect of
     operations the process has performed on an individual  sema-
     phore with the SEM_UNDO flag set (so that they can be undone
     if the  process  terminates  unexpectedly).   The  value  of
     semadj  can  affect  the  behavior of calls to sempo(), sem-
     timedop(), exit(), and _exit()  (the  latter  two  functions



SunOS 5.9           Last change: 15 Oct 2000                    1






System Calls                                             semop(2)



     documented  on exit(2)), but is otherwise unobservable.  See
     below for details.

     The sem_op member specifies one of  three  semaphore  opera-
     tions:

     1. The sem_op member is a negative integer; {ALTER}

           o  If semval (see intro(2)) is greater than  or  equal
              to the absolute value of sem_op, the absolute value
              of sem_op  is  subtracted  from  semval.  Also,  if
              (sem_flg&SEM_UNDO)  is  true, the absolute value of
              sem_op is added to  the  calling  process's  semadj
              value (see exit(2)) for the specified semaphore.

           o  If semval is less than the absolute value of sem_op
              and  (sem_flg&IPC_NOWAIT)  is true, semop() returns
              immediately.

           o  If semval is less than the absolute value of sem_op
              and  (sem_flg&IPC_NOWAIT)  is false, semop() incre-
              ments the semncnt  associated  with  the  specified
              semaphore  and  suspends  execution  of the calling
              process  until  one  of  the  following  conditions
              occur:

                 o  The value of semval becomes greater  than  or
                    equal  to  the absolute value of sem_op. When
                    this occurs, the value of semncnt  associated
                    with  the specified semaphore is decremented,
                    the absolute value of  sem_op  is  subtracted
                    from  semval  and,  if  (sem_flg&SEM_UNDO) is
                    true, the absolute value of sem_op  is  added
                    to the calling process's semadj value for the
                    specified semaphore.

                 o  The semid for which the  calling  process  is
                    awaiting  action  is  removed from the system
                    (see semctl(2)). When this occurs,  errno  is
                    set to EIDRM and -1 is returned.

                 o  The calling process receives a signal that is
                    to  be caught. When this occurs, the value of
                    semncnt associated with the  specified  sema-
                    phore is decremented, and the calling process
                    resumes execution in the manner prescribed in
                    signal(3C).

     2. The sem_op member is a positive integer; {ALTER}

        The  value  of  sem_op  is  added  to  semval   and,   if
        (sem_flg&SEM_UNDO)  is  true,  the  value  of  sem_op  is



SunOS 5.9           Last change: 15 Oct 2000                    2






System Calls                                             semop(2)



        subtracted from the calling process's  semadj  value  for
        the specified semaphore.

     3. The sem_op member is 0; {READ}

           o  If semval is 0, semop() returns immediately.

           o  If   semval    is    not    equal    to    0    and
              (sem_flg&IPC_NOWAIT)   is   true,  semop()  returns
              immediately.

           o  If   semval    is    not    equal    to    0    and
              (sem_flg&IPC_NOWAIT)  is  false, semop() increments
              the semzcnt associated with the specified semaphore
              and suspends execution of the calling process until
              one of the following occurs:

                 o  The value of semval becomes 0, at which  time
                    the  value  of  semzcnt  associated  with the
                    specified semaphore  is  set  to  0  and  all
                    processes  waiting  on semval to become 0 are
                    awakened.

                 o  The semid for which the  calling  process  is
                    awaiting  action  is removed from the system.
                    When this occurs, errno is set to  EIDRM  and
                    -1 is returned.

                 o  The calling process receives a signal that is
                    to  be caught. When this occurs, the value of
                    semzcnt associated with the  specified  sema-
                    phore is decremented, and the calling process
                    resumes execution in the manner prescribed in
                    signal(3C).

     Upon successful completion, the value  of  sempid  for  each
     semaphore  specified  in the array pointed to by sops is set
     to the process ID of the calling process.

     The semtimedop() function behaves as semop() except when  it
     must  suspend  execution  of the calling process to complete
     its operation.  If semtimedop()  must  suspend  the  calling
     process   after  the  time  interval  specified  in  timeout
     expires, or if the timeout  expires  while  the  process  is
     suspended,  semtimedop()  returns  with  an  error.   If the
     timespec structure pointed to by timeout is zero-valued  and
     semtimedop()  needs  to  suspend the calling process to com-
     plete the requested  operation(s),  it  returns  immediately
     with an error.  If timeout is the NULL pointer, the behavior
     of semtimedop() is identical to that of semop().





SunOS 5.9           Last change: 15 Oct 2000                    3






System Calls                                             semop(2)



RETURN VALUES
     Upon successful completion, 0 is returned. Otherwise, -1  is
     returned and errno is set to indicate the error.

ERRORS
     The semop() and semtimedop() functions will fail if:

     E2BIG The nsops argument is greater than the  system-imposed
           maximum.

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

     EAGAIN
           The operation would result in suspension of  the  cal-
           ling process but (sem_flg&IPC_NOWAIT) is true.

     EFAULT
           The sops argument points to an illegal address.

     EFBIG The value of sem_num is less than 0 or greater than or
           equal  to  the number of semaphores in the set associ-
           ated with semid.

     EIDRM A semid was removed from the system.

     EINTR A signal was received.

     EINVAL
           The semid argument is not a valid  semaphore  identif-
           ier,  or the number of individual semaphores for which
           the calling process requests a SEM_UNDO  would  exceed
           the limit.

     ENOSPC
           The  limit  on  the  number  of  individual  processes
           requesting an SEM_UNDO would be exceeded.

     ERANGE
           An operation would cause a semval or a semadj value to
           overflow the system-imposed limit.

     The semtimedop() function will fail if:

     EAGAIN
           The timeout expired  before  the  requested  operation
           could be completed.

     The semtimedop() function will fail if one of the  following
     is detected:




SunOS 5.9           Last change: 15 Oct 2000                    4






System Calls                                             semop(2)



     EFAULT
           The timeout argument points to an illegal address.

     EINVAL
           The timeout argument specified  a  tv_sec  or  tv_nsec
           value  less than 0, or a tv_nsec value greater than or
           equal to 1000 million.

USAGE
     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).

SEE ALSO
     ipcs(1), mount_ufs(1M), intro(2), exec(2), exit(2), fork(2),
     semctl(2), semget(2)




























SunOS 5.9           Last change: 15 Oct 2000                    5