Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > S

semctl(2)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

semctl() — semaphore control operations

SYNOPSIS

#include <sys/sem.h> int semctl(int semid, int semnum, int cmd, ... ); union semun { int val; struct semid_ds *buf; ushort *array; } arg;

DESCRIPTION

The semctl() system call provides a variety of semaphore control operations as specified by cmd. The fourth argument is optional and depends on the operation requested. If present, it must be of type union semun, which the application program must explicitly declare. For the meaning of unspecified variables, see semaphore identifier in glossary(9).

The following values for cmd are executed with respect to the semaphore specified by semid and semnum:

GETVAL

Returns the semaphore value. Requires semaphore Read permission.

SETVAL

Sets the value of the semaphore to arg.val, where arg is the fourth argument of semctl() taken as a union semun. When this cmd is successfully executed, the semadj value corresponding to the specified semaphore in all processes is cleared. Requires semaphore Alter permission.

GETPID

Returns the pid of the last process that performed a semaphore operation on this semaphore. Requires semaphore Read permission.

GETNCNT

Returns count of the number of processes that are currently suspended awaiting this semaphore's value to become greater than its current value. Requires semaphore Read permission.

GETZCNT

Returns count of the number of processes that are currently suspended awaiting this semaphore's value to become zero. Requires semaphore Read permission.

The following values for cmd return and set, respectively, every semaphore in the set of semaphores.

GETALL

Place semaphore value into array pointed to by arg.array, where arg is the fourth argument of semctl() taken as a union semun. Requires semaphore Read permission.

SETALL

Set semaphore value according to the array pointed to by arg.array, where arg is the fourth argument of semctl() taken as a union semun. When this cmd is successfully executed, the semadj values corresponding to each specified semaphore in all processes are cleared. Requires semaphore Alter permission.

The following values for cmd are also available:

IPC_STAT

Place the current value of each member of the data structure associated with semid into the structure pointed to by arg.buf, where arg is the fourth argument of semctl() taken as a union semun. The contents of this structure are defined in glossary(9). Requires semaphore Read permission.

IPC_SET

Set the value of the following members of the data structure associated with semid to the corresponding value found in the structure pointed to by arg.buf, where arg is the fourth argument of semctl() taken as a union semun:

sem_perm.uid sem_perm.gid sem_perm.mode /* only low 9 bits */

This cmd can only be executed by a process that has an effective user ID equal to either that of a user with the OWNER privilege or to the value of either sem_perm.uid or sem_perm.cuid in the data structure associated with semid.

IPC_RMID

Remove the semaphore identifier specified by semid from the system and destroy the set of semaphores and data structure associated with it. This cmd can only be executed by a process that has an effective user ID equal to either that of a user with the OWNER privilege or to the value of either sem_perm.uid or sem_perm.cuid in the data structure associated with semid.

Security Restrictions

Some or all of the actions associated with this system call are subject to compartmental restrictions. See compartments(5) for more information about compartmentalization on systems that support that feature. Compartmental restrictions can be overridden if the process possesses the COMMALLOWED privilege (PRIV_COMMALLOWED). Processes owned by the superuser may not have this privilege. Processes owned by any user may have this privilege, depending on system configuration.

Some or all of the actions associated with this system call require one or more privileges. Processes owned by the superuser have many, though not all, privileges. Processes owned by other users may have privilege(s), depending on system configuration. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

Upon successful completion, semctl() returns a value based on cmd.

All others return 0.

If it fails, it returns -1 and sets errno to indicate the error.

ERRORS

If semctl() fails, it sets errno to one of the following values:

EACCES

Operation permission is denied to the calling process (see semaphore operation permissions in glossary(9).

EFAULT

cmd is SETVAL, GETALL, SETALL, IPC_SET, or IPC_STAT, and arg is an invalid pointer.

EINVAL

semid is not a valid semaphore identifier.

EINVAL

semnum is less than zero or greater than or equal sem_nsems.

EINVAL

cmd is not a valid command, or the command contains invalid parameters.

EPERM

cmd is equal to IPC_RMID or IPC_SET and the process does not have an effective user ID equal to either that of a user with the OWNER privilege or to the value of either sem_perm.uid or sem_perm.cuid in the data structure associated with semid.

ERANGE

cmd is SETVAL or SETALL and the value to which semaphore value is to be set is greater than the system imposed maximum.

EXAMPLES

The following call to semctl() initializes the set of 4 semaphores to the values 0, 1, 0, and 1 respectively. This example assumes the process has a valid semid representing a set of 4 semaphores as shown in the semget(2) manual entry. For an example of performing "P" and "V" operations on the semaphores below, refer to semop(2).

union semun { int val; struct semid_ds *buf; ushort *array; } arg; ushort semarray[4]; semarray[0] = 0; semarray[1] = 1; semarray[2] = 0; semarray[3] = 1; arg.array = &semarray[0]; semctl (mysemid, 0, SETALL, arg);

STANDARDS CONFORMANCE

semctl(): SVID2, SVID3, XPG2, XPG3, XPG4

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.