182 lines
4.3 KiB
Groff
182 lines
4.3 KiB
Groff
'\"macro stdmacro
|
|
.TH BLOCKPROC 2 LOCAL
|
|
.SH NAME
|
|
blockproc, unblockproc, setblockproccnt, blockprocall, unblockprocall, setblockproccntall \- routines to block/unblock processes
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.B #include <sys/types.h>
|
|
.br
|
|
.B #include <sys/prctl.h>
|
|
.sp
|
|
.B "int blockproc (pid_t pid);"
|
|
.sp
|
|
.B "int unblockproc (pid_t pid);"
|
|
.sp
|
|
.B "int setblockproccnt (pid_t pid, int count);"
|
|
.sp
|
|
.B "int blockprocall (pid_t pid);"
|
|
.sp
|
|
.B "int unblockprocall (pid_t pid);"
|
|
.sp
|
|
.B "int setblockproccntall (pid_t pid, int count);"
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
.B integer*4 function blockproc (pid)
|
|
.br
|
|
.B integer*4 pid;
|
|
.PP
|
|
.br
|
|
.B integer*4 function unblockproc (pid)
|
|
.br
|
|
.B integer*4 pid;
|
|
.PP
|
|
.br
|
|
.B integer*4 function setblockproccnt (pid, count)
|
|
.br
|
|
.B integer*4 pid;
|
|
.br
|
|
.B integer*4 count;
|
|
.PP
|
|
.br
|
|
.B integer*4 function blockprocall (pid)
|
|
.br
|
|
.B integer*4 pid;
|
|
.PP
|
|
.br
|
|
.B integer*4 function unblockprocall (pid)
|
|
.br
|
|
.B integer*4 pid;
|
|
.PP
|
|
.br
|
|
.B integer*4 function setblockproccntall (pid, count)
|
|
.br
|
|
.B integer*4 pid;
|
|
.br
|
|
.B integer*4 count;
|
|
.Op
|
|
.SH 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
|
|
.I blockproc
|
|
decrements the count.
|
|
When the count becomes negative, the process is suspended.
|
|
When
|
|
.I 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.
|
|
.PP
|
|
In order to guarantee a known starting place, the
|
|
.I setblockproccnt
|
|
function may be called,
|
|
which will force the semaphore count to the value given by
|
|
.IR count .
|
|
New processes have their semaphore zeroed.
|
|
Normally,
|
|
.I 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
|
|
.I n
|
|
other processes to complete, it could set its block count to
|
|
.I -n.
|
|
This would immediately force the process to block.
|
|
Then as each process finishes, it unblocks the waiting process.
|
|
When the
|
|
.I n'th
|
|
process finishes the waiting process will be awakened.
|
|
.PP
|
|
The
|
|
.I blockprocall,
|
|
.I unblockprocall,
|
|
and
|
|
.I setblockproccntall
|
|
system calls perform the same actions as
|
|
.I blockproc,
|
|
.I unblockproc,
|
|
and
|
|
.I setblockproccnt,
|
|
respectively,
|
|
but act on all processes in the given process' share group.
|
|
A share group is a group of processes created with the
|
|
.I 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.
|
|
.PP
|
|
A process may block another provided that standard
|
|
UNIX permissions are satisfied.
|
|
.PP
|
|
A process may determine whether another is blocked by using the
|
|
.I 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.
|
|
.PP
|
|
These interfaces are not supported for POSIX Threads applications.
|
|
.PP
|
|
These routines
|
|
will fail and no operation will be performed if one or more of the
|
|
following are true:
|
|
.TP 15
|
|
.SM
|
|
\%[ESRCH]
|
|
The
|
|
.I pid
|
|
specified does not exist.
|
|
.TP
|
|
.SM
|
|
\%[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.
|
|
.TP
|
|
.SM
|
|
\%[EPERM]
|
|
The target process is a POSIX Threads application.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The count value that would result from the requested
|
|
.IR blockproc ,
|
|
.I unblockproc
|
|
or
|
|
.I setblockproccnt
|
|
is less than
|
|
.SM
|
|
.B PR_MINBLOCKCNT
|
|
or greater than
|
|
.SM
|
|
.B PR_MAXBLOCKCNT
|
|
as defined in
|
|
.IR sys/prctl.h .
|
|
.SH "SEE ALSO"
|
|
sproc(2), prctl(2).
|
|
.SH DIAGNOSTICS
|
|
Upon successful completion, 0 is returned.
|
|
Otherwise, a value of \-1 is
|
|
returned to the calling process, and
|
|
.I errno\^
|
|
is set to indicate the error.
|
|
When using the
|
|
.I blockprocall,
|
|
.I unblockprocall,
|
|
and
|
|
.I 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
|
|
.I errno\^
|
|
to indicate the error of the last failure to occur.
|