 |
Index for
Section 2 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
semctl(2)
NAME
semctl - Performs semaphore control operations
SYNOPSIS
#include <sys/sem.h>
int semctl(
int semid,
int semnum,
int cmd,
...);
Application developers may want to specify #include statements for
<sys/types.h> and <sys/ipc.h> before the one for <sys/sem.h> if programs
are being developed for multiple platforms. The additional #include
statements are not required on Tru64 UNIX systems or by ISO or X/Open
standards, but may be required on other vendors' systems that conform to
these standards.
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
semctl(): XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
semid Specifies the ID of the semaphore set.
semnum Specifies the number of the semaphore to be processed.
cmd Specifies the type of command. See the DESCRIPTION section for a
list of available commands.
The fourth argument is optional and depends on the operation requested. If
required, it is of the type union semun, which the application program must
explicitly declare as follows:
union semun {
int val;
struct semid_ds *buf;
u_short *array;
} arg );
The members of this structure are described as follows:
val Contains the semaphore value to which semval is set when the
SETVAL command is performed.
buf Points to a structure of type semid_ds. (For information about
this structure, semid_ds(4).) When you specify the IPC_STAT
command, semctl() copies the contents of the semid_ds structure
identified by semid into arg.buf. When you specify the IPC_SET
command, semctl() copies the contents of the arg.buf parameter
into the semid_ds structure identified by the semid parameter.
array Points to an array of semval values. These semval values are
returned by the GETALL command and set by the SETALL command.
DESCRIPTION
The semctl() function allows a process to perform various operations on an
individual semaphore within a semaphore set, on all semaphores within a
semaphore set, and on the semid_ds structure associated with the semaphore
set. It also allows a process to remove the semaphore set's ID and its
associated semid_ds structure.
The cmd value determines which operation is performed. The following
commands operate on the specified semaphore (that is, the one specified by
the semnum parameter) within the semaphore set identified by semid:
GETVAL Returns the value of semval. This command requires read
permission.
SETVAL Sets the value of semval to arg.val. When this command
successfully executes, the kernel clears the semaphore's adjust-
on-exit value in all processes. This command requires modify
permission.
GETPID Returns the value of sempid. This command requires read
permission.
GETNCNT Returns the value of semncnt. This command requires read
permission.
GETZCNT Returns the value of semzcnt. This command requires read
permission.
The following commands operate on all the semaphores in the semaphore set:
GETALL Returns all the semval values and places them in the array
pointed to by arg.array. This command requires read permission.
SETALL Sets all the semval values according to the array pointed to by
arg.array. When this command successfully executes, the kernel
clears the semaphore's adjust-on-exit value in all processes.
This command requires modify permission.
You can also use the following IPC commands:
IPC_STAT Queries the semaphore ID by copying the contents of its
associated semid_ds structure into the structure pointed to by
arg.buf. This command requires read permission.
IPC_SET Sets the semaphore set by copying the values in the arg.buf
structure into corresponding fields in the semid_ds structure
associated with the semaphore ID. This operation is restricted.
The effective user ID of the calling process must have superuser
privilege or must be equal to the value of sem_perm.cuid or
sem_perm.uid in the structure associated with the semaphore ID.
The fields are set as follows:
·
The sem_perm.uid field is set to the owner's user ID.
·
The sem_perm.gid field is set to the owner's group ID.
·
The sem_perm.mode field is set to the access modes for the
semaphore set. Only the low-order nine bits are set.
IPC_RMID Removes the semaphore ID and destroys the set of semaphores and
the semid_ds data structure associated with it. This operation
is restricted. The effective user ID of the calling process must
have superuser privilege or equal to the value of sem_perm.cuid
or sem_perm.uid in the associated semid_ds structure.
RETURN VALUES
Upon successful completion, the value returned depends on the cmd parameter
as follows:
GETVAL Returns the value of semval.
GETPID Returns the value of sempid.
GETNCNT Returns the value of semncnt.
GETZCNT Returns the value of semzcnt.
All other commands return a value of 0 (zero).
If the semctl() function fails, it returns a value of -1 and sets errno to
indicate the error.
ERRORS
The semctl() function sets errno to the specified values for the following
conditions:
[EACCES] The calling process does not have the required permission.
[EFAULT] [Tru64 UNIX] The cmd parameter is IPC_STAT or IPC_SET and an
error occurred in accessing the arg structure.
[EINVAL] The semid parameter is not a valid semaphore ID; the value of
semnum is less than 0 (zero) or greater than sem_nsems; or cmd is
not a valid command.
[ENOMEM] [Tru64 UNIX] The system does not have enough memory to complete
the function.
[EPERM] Either the cmd parameter is equal to IPC_RMID and the effective
user ID of the calling process does not have appropriate
privilege, or the cmd parameter is equal to IPC_SET and the
effective user ID of the calling process is not equal to the
value of sem_perm.cuid or sem_perm.uid in the semid_ds structure
associated with the semaphore ID.
[ERANGE] The cmd parameter is SETVAL or SETALL and the value to which
semval is to be set is greater than the system-defined maximum.
RELATED INFORMATION
Functions: semget(2), semop(2)
Data structures: semid_ds(4)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|