BLOCKPROC(2)                                                      BLOCKPROC(2)


NAME
     blockproc, unblockproc, setblockproccnt, blockprocall, unblockprocall,
     setblockproccntall - routines to block/unblock processes

C SYNOPSIS
     #include <sys/types.h>
     #include <sys/prctl.h>

     int blockproc (pid_t pid);

     int unblockproc (pid_t pid);

     int setblockproccnt (pid_t pid, int count);

     int blockprocall (pid_t pid);

     int unblockprocall (pid_t pid);

     int setblockproccntall (pid_t pid, int count);

DESCRIPTION
     These routines provide a complete set of blocking/unblocking capabilities
     for processes.  Blocking is implemented with a counting semaphore in the
     kernel.  Each call to blockproc decrements the count.  When the count
     becomes negative, the process is suspended.  When unblockproc is called,
     the count is incremented.  If the count becomes non-negative (>= 0), the
     process is restarted.  This provides both a simple, race free
     synchronization ability between two processes and a much more powerful
     capability to synchronize multiple processes.

     In order to guarantee a known starting place, the setblockproccnt
     function may be called, which will force the semaphore count to the value
     given by count.  New processes have their semaphore zeroed.  Normally,
     count should be set to 0.  If the resulting block count is greater than
     or equal to zero and the process is currently blocked, it will be
     unblocked.  If the resulting block count is less than zero, the process
     will be blocked.  Using this, a simple rendezvous mechanism can be set
     up.  If one process wants to wait for n other processes to complete, it
     could set its block count to -n. This would immediately force the process
     to block.  Then as each process finishes, it unblocks the waiting
     process.  When the n'th process finishes the waiting process will be
     awakened.

     The blockprocall, unblockprocall, and setblockproccntall system calls
     perform the same actions as blockproc, unblockproc, and setblockproccnt,
     respectively, but act on all processes in the given process' share group.
     A share group is a group of processes created with the sproc(2) system
     call.  If a process does not belong to a share group, the effect of the
     plural form of a call will be the same as that of the singular form.


     A process may block another provided that standard UNIX permissions are
     satisfied.

     A process may determine whether another is blocked by using the prctl(2)
     system call.  It should be noted that since other processes may unblock
     the subject process at any time, the answer should be interpreted as a
     snapshot only.

     These interfaces are not supported for POSIX Threads applications.

     These routines will fail and no operation will be performed if one or
     more of the following are true:

     [ESRCH]        The pid specified does not exist.

     [EPERM]        The caller is not operating on itself, its effective user
                    ID is not super-user, and its real or effective user ID
                    does not match the real or effective user ID of the target
                    process.

     [EPERM]        The target process is a POSIX Threads application.

     [EINVAL]       The count value that would result from the requested
                    blockproc, unblockproc or setblockproccnt is less than
                    PR_MINBLOCKCNT or greater than PR_MAXBLOCKCNT as defined
                    in sys/prctl.h.

SEE ALSO
     sproc(2), prctl(2).

DIAGNOSTICS
     Upon successful completion, 0 is returned.  Otherwise, a value of -1 is
     returned to the calling process, and errno is set to indicate the error.
     When using the blockprocall, unblockprocall, and setblockproccntall
     calls, an error may occur on any of the processes in the share group.
     These calls will attempt to perform the given action on each process in
     the share group despite earlier errors, and set errno to indicate the
     error of the last failure to occur.


                                                                        Page 2