sema (1) --- manipulate user semaphores                  08/27/84


          | _U_s_a_g_e

          |      sema -(w | n | t | d | c) {<semaphore>}
          |      sema -o {<pathname>} [-i <integer>]
                    <semaphore> ::= integer


            _D_e_s_c_r_i_p_t_i_o_n

          |      'Sema'  gives  access  to Prime's user semaphores, which are
          |      available to all users.  There is  no  mechanism  to  assure
          |      that  semaphores are used properly (i.e.  - preventing dead-
          |      lock or race conditions).

          |      'Sema' performs the function indicated by its  argument,  on
          |      the  semaphore  number  or  pathname  given.   When multiple
          |      semaphores or pathnames are supplied, the operation given is
          |      performed on each argument in the order listed on  the  com-
          |      mand line.  The functions available are:

          |      -w   (wait)  increment  the  semaphore's  counter.   If  the
          |           resulting value is positive, enqueue on the semaphore's
                      waiting list and block execution (sleep) until awakened
                      by some other process.

          |      -n   (notify) decrement  the  counter.   If  the  result  is
          |           positive  or  zero,  dequeue a process from the waiting
                      list and wake it up.

          |      -t   (test) print the value of the counter (in  decimal)  on
                      standard output.

          |      -d   (drain)  initialize  a  semaphore  for  use.   Set  the
          |           counter to zero, dequeue all waiting processes and wake
                      them up.

          |      -o   (open)  initialize   a   semaphore   for   use.    This
          |           initializes  named  semaphores  for use and returns the
          |           semaphore numbers on standard output.  A  semaphore  is
          |           opened only if the user has read access to the pathname
          |           given  and  if  the  pathname is on the current system.
          |           One semaphore is opened for  each  pathname  specified.
          |           All  semaphores  opened  on  the  same pathname are the
          |           same.  This allows the user to restrict access  to  the
          |           semaphores  by  restricting  access access to the files
          |           used to open the semaphores.  This may be achieved with
          |           access control lists or  passworded  directories.   The
          |           numbered  semaphores  (1-64) are considered always open
          |           and any attempt to open one of them will result  in  an
          |           error.

          |      -i   (initialize)  when  used  with  the  "-o" (open) option
          |           causes the semaphores that are opened to be initialized
          |           to the value specified.  This initialization only takes
          |           place the first time the semaphore is opened.  If  mul-
          |           tiple  users  have  opened a semaphore, only first time


            sema (1)                      - 1 -                      sema (1)




            sema (1) --- manipulate user semaphores                  08/27/84


          |           cause  the  initialization  to   take   place.    Since
          |           initializing  a  semaphore to a positive value does not
          |           make sense, only non-positive values are  allowed.   If
          |           this option is omitted, the default is 0.

          |      -c   (close)  close  a  named  semaphore.   This removes the
          |           user's number from the list of  current  users  of  the
                      semaphore  and  makes  the  semaphore  unavailable  for
          |           further  use  for  that  user.   Since   the   numbered
          |           semaphores are always open, any attempt to close one of
          |           them will result in an error.


            _E_x_a_m_p_l_e_s

          |      sema -w 1
          |      sema -n 1 2 3
          |      sema -t [iota 62]
          |      sema -d -32
          |      set sema_number = [sema -o //system/restricted_file -i -1]
          |      sema -c [sema_number]


            _M_e_s_s_a_g_e_s

                 "Usage:  sema ..."  for nonsensical arguments.
          |      "no  available  semaphores"  when  all  named semaphores are
          |           allocated.
          |      "<pathname>:  invalid semaphore  name"  when  the  semaphore
          |           used has not been opened.
          |      "<pathname>:   semaphore overflow" when another notify would
          |           exceed the limit on the semaphore.
          |      "<pathname>:  on a remote disk" when the pathname is not  on
          |           the current system.
          |      "<pathname>:   file  not found" when the file used to open a
          |           semaphore cannot be read.
          |      "<pathname>:  can't open semaphore" when some unknown reason
          |           causes an error.
          |      "<integer>:  initial value greater than 0" when  an  initial
          |           value is specified that is greater than 0.


            _S_e_e _A_l_s_o

          |      _P_r_i_m_e_'_s  _S_u_b_r_o_u_t_i_n_e_s _R_e_f_e_r_e_n_c_e _G_u_i_d_e (_D_O_C_3_6_2_1_-_1_9_0_P), section
          |      21, for a complete description of semaphores as  implemented
          |      in  Primos and for a description of the system calls used by
          |      'sema'.

                 Peter Freeman:  _S_o_f_t_w_a_r_e _S_y_s_t_e_m_s _P_r_i_n_c_i_p_l_e_s, for  a  discus-
                 sion of how semaphores of this type can be used.







            sema (1)                      - 2 -                      sema (1)