LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

Formatting & lang clean-ups; added data structure defns

This commit is contained in:
Michael Kerrisk 2004-11-10 17:27:07 +00:00
parent f998edca67
commit 70d0e5ef63
2 changed files with 217 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
man2/msgctl.2
View File

@ -26,8 +26,11 @@
.\" Added notes on CAP_IPC_OWNER requirement .\" Added notes on CAP_IPC_OWNER requirement
.\" Modified, 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net> .\" Modified, 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Language and formatting clean-ups
.\" Added msqid_ds and ipc_perm structure definitions
.\" .\"
.TH MSGCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" .TH MSGCTL 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual"
.SH NAME .SH NAME
msgctl \- message control operations msgctl \- message control operations
.SH SYNOPSIS .SH SYNOPSIS
@ -44,74 +47,115 @@ msgctl \- message control operations
.BI "int " cmd , .BI "int " cmd ,
.BI "struct msqid_ds *" buf ); .BI "struct msqid_ds *" buf );
.SH DESCRIPTION .SH DESCRIPTION
This function performs the control operation specified by .B msgctl
performs the control operation specified by
.I cmd .I cmd
on the message queue with identifier on the message queue with identifier
.IR msqid . .IR msqid .
Legal values for .PP
The
.I msqid_ds
data structure is defined in <sys/msg.h> as follows:
.nf
.in +4n
struct msqid_ds {
struct ipc_perm msg_perm; /* Ownership and permissions
time_t msg_stime; /* Time of last msgsnd() */
time_t msg_rtime; /* Time of last msgrcv() */
time_t msg_ctime; /* Time of last change */
unsigned long __msg_cbytes; /* Current number of bytes in
queue (non-standard) */
msgqnum_t msg_qnum; /* Current number of messages
in queue */
msglen_t msg_qbytes; /* Maximum number of bytes
allowed in queue */
pid_t msg_lspid; /* PID of last msgsnd() */
pid_t msg_lrpid; /* PID of last msgrcv() */
};
.in -4n
.fi
.PP
The
.I ipc_perm
structure is defined in <sys/ipc.h> as follows
(the highlighted fields are settable using
.BR IPC_SET ):
.PP
.nf
.in +4n
struct ipc_perm {
key_t key; /* Key supplied to msgget() */
uid_t \fBuid\fP; /* Effective UID of owner */
gid_t \fBgid\fP; /* Effective GID of owner */
uid_t cuid; /* Effective UID of creator */
gid_t cgid; /* Effective GID of creator */
unsigned short \fBmode\fP; /* Permissions */
unsigned short seq; /* Sequence number */
};
.in -4n
.fi
.PP
Valid values for
.I cmd .I cmd
are: are:
.TP .TP
.B IPC_STAT .B IPC_STAT
Copy info from the message queue data structure associated with Copy information from the kernel data structure associated with
.I msqid .I msqid
into the structure pointed to by into the
.I msqid_ds
structure pointed to by
.IR buf . .IR buf .
The caller must have read permission on the message queue. The caller must have read permission on the message queue.
.TP .TP
.B IPC_SET .B IPC_SET
Write the values of some members of the Write the values of some members of the
.B msqid_ds .I msqid_ds
structure pointed to by structure pointed to by
.I buf .I buf
to the message queue data structure, updating also its to the kernel data structure associated with this message queue,
.B msg_ctime updating also its
.I msg_ctime
member. member.
The following members of the structure can be updated: The following members of the structure are updated:
.nf .IR msg_qbytes ,
.sp .IR msg_perm.uid ,
.ft B .IR msg_perm.gid ,
msg_perm.uid and (the least significant 9 bits of)
msg_perm.gid .IR msg_perm.mode .
msg_perm.mode \fR/* only lowest 9-bits */\fP The effective UID of the calling process must match the owner
msg_qbytes
.fi
.ft R
.sp
The calling process must have appropriate (probably, root) privileges
or its effective user\-ID must be that of the creator
.RI ( msg_perm.cuid )
or owner
.RI ( msg_perm.uid ) .RI ( msg_perm.uid )
of the message queue. or creator
.RI ( msg_perm.cuid )
of the message queue, or the caller must be privileged.
Appropriate privilege (Linux: the Appropriate privilege (Linux: the
.B CAP_IPC_RESOURCE .B CAP_IPC_RESOURCE
capability) is required to raise the capability) is required to raise the
.B msg_qbytes .I msg_qbytes
value beyond the system parameter value beyond the system parameter
.BR MSGMNB . .BR MSGMNB .
.TP .TP
.B IPC_RMID .B IPC_RMID
Immediately remove the message queue and its associated data structure, Immediately remove the message queue,
awakening all waiting reader and writer processes (with an error awakening all waiting reader and writer processes (with an error
return and return and
.B errno .I errno
set to set to
.BR EIDRM ). .BR EIDRM ).
The calling process must have appropriate (probably, root) privileges The calling process must have appropriate privileges
or its effective user\-ID must be either that of the creator or owner or its effective user\-ID must be either that of the creator or owner
of the message queue. of the message queue.
.SH "RETURN VALUE" .SH "RETURN VALUE"
On success, the return value will be On success, the return value will be 0
.BR 0 , otherwise \-1
otherwise
.B \-1
with with
.B errno .I errno
indicating the error. indicating the error.
.SH ERRORS .SH ERRORS
On failure, On failure,
.B errno .I errno
is set to one of the following: is set to one of the following:
.TP 11 .TP 11
.B EACCES .B EACCES
@ -165,10 +209,10 @@ and the process is not privileged (Linux: it does not have the
.B CAP_SYS_ADMIN .B CAP_SYS_ADMIN
capability). capability).
.SH NOTES .SH NOTES
Various fields in a \fIstruct msqid_ds\fP were shorts under Linux 2.2 Various fields in the \fIstruct msqid_ds\fP were shorts under Linux 2.2
and have become longs under Linux 2.4. To take advantage of this, and have become longs under Linux 2.4. To take advantage of this,
a recompilation under glibc-2.1.91 or later should suffice. a recompilation under glibc-2.1.91 or later should suffice.
(The kernel distinguishes old and new calls by a IPC_64 flag in (The kernel distinguishes old and new calls by an IPC_64 flag in
.IR cmd .) .IR cmd .)
.SH "CONFORMING TO" .SH "CONFORMING TO"
SVr4, SVID. SVID does not document the EIDRM error condition. SVr4, SVID. SVID does not document the EIDRM error condition.

228
man2/semctl.2
View File

@ -29,8 +29,12 @@
.\" Added notes on CAP_IPC_OWNER requirement .\" Added notes on CAP_IPC_OWNER requirement
.\" Modified 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net> .\" Modified 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Language and formatting clean-ups
.\" Rewrote semun text
.\" Added semid_ds and ipc_perm structure definitions
.\" .\"
.TH SEMCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" .TH SEMCTL 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual"
.SH NAME .SH NAME
semctl \- semaphore control operations semctl \- semaphore control operations
.SH SYNOPSIS .SH SYNOPSIS
@ -42,7 +46,6 @@ semctl \- semaphore control operations
.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
The function
.B semctl .B semctl
performs the control operation specified by performs the control operation specified by
.I cmd .I cmd
@ -51,81 +54,110 @@ on the semaphore set identified by
or on the or on the
.IR semnum -th .IR semnum -th
semaphore of that set. semaphore of that set.
(Semaphores are numbered starting at 0.) (The semaphores in a set are numbered starting at 0.)
.PP .PP
This function has three or four arguments. When there This function has three or four arguments, depending on
are four, the call is .IR cmd .
.BI semctl( semid , semnum , cmd , arg ); When there are four, the fourth has the type
where the fourth argument .IR "union semun" .
.I arg The \fIcalling program\fP must define this union as follows:
has a type
.B union semun
defined as follows:
.nf .nf
#if defined(__GNU_LIBRARY__) && !defined(_SEM_SEMUN_UNDEFINED) .in +4n
/* union semun is defined by including <sys/sem.h> */
#else
/* according to X/OPEN we have to define it ourselves */
union semun { union semun {
int val; /* value for SETVAL */ int val; /* Value for SETVAL */
struct semid_ds *buf; /* buffer for IPC_STAT, IPC_SET */ struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */
unsigned short *array; /* array for GETALL, SETALL */ unsigned short *array; /* Array for GETALL, SETALL */
/* Linux specific part: */ struct seminfo *__buf; /* Buffer for IPC_INFO
struct seminfo *__buf; /* buffer for IPC_INFO */ (Linux specific) */
}; };
#endif .in -4n
.fi .fi
.PP .PP
Legal values for The
.I semid_ds
data structure is defined in <sys/sem.h> as follows:
.nf
.in +4n
struct semid_ds {
struct ipc_perm sem_perm; /* Ownership and permissions
time_t sem_otime; /* Last semop time */
time_t sem_ctime; /* Last change time */
unsigned short sem_nsems; /* No. of semaphores in set */
};
.in -4n
.fi
.PP
The
.I ipc_perm
structure is defined in <sys/ipc.h> as follows
(the highlighted fields are settable using
.BR IPC_SET ):
.PP
.nf
.in +4n
struct ipc_perm {
key_t key; /* Key supplied to semget() */
uid_t \fBuid\fP; /* Effective UID of owner */
gid_t \fBgid\fP; /* Effective GID of owner */
uid_t cuid; /* Effective UID of creator */
gid_t cgid; /* Effective GID of creator */
unsigned short \fBmode\fP; /* Permissions */
unsigned short seq; /* Sequence number */
};
.in -4n
.fi
.PP
Valid values for
.I cmd .I cmd
are: are:
.TP 12 .TP 12
.B IPC_STAT .B IPC_STAT
Copy info from the semaphore set data structure Copy information from the kernel data structure associated with
into the structure pointed to by .I semid
.IB arg .buf \fR. into the
.I semid_ds
structure pointed to by
.IR arg.buf .
The argument The argument
.I semnum .I semnum
is ignored. is ignored.
The calling process must have read access privileges on the semaphore set. The calling process must have read permission on the semaphore set.
.TP .TP
.B IPC_SET .B IPC_SET
Write the values of some members of the Write the values of some members of the
.B semid_ds .I semid_ds
structure pointed to by structure pointed to by
.IB arg .buf .I arg.buf
to the semaphore set data structure, updating also its to the kernel data structure associated with this semaphore set,
.B sem_ctime updating also its
.I sem_ctime
member. member.
Considered members from the user supplied The following members of the structure are updated:
.B "struct semid_ds" .IR sem_perm.uid ,
pointed to by .IR sem_perm.gid ,
.IB arg .buf and (the least significant 9 bits of)
are .IR sem_perm.mode .
.nf The effective UID of the calling process must match the owner
.sp .RI ( sem_perm.uid )
.ft B or creator
sem_perm.uid .RI ( sem_perm.cuid )
sem_perm.gid of the semaphore set, or the caller must be privileged.
sem_perm.mode \fR/* only lowest 9-bits */\fP
.fi
.ft R
.sp
The effective user\-ID of the calling process must be that of the
super\-user, or match the creator or owner of the semaphore set.
The argument The argument
.I semnum .I semnum
is ignored. is ignored.
.TP .TP
.B IPC_RMID .B IPC_RMID
Immediately remove the semaphore set and its data structures Immediately remove the semaphore set,
awakening all waiting processes (with an error return and awakening all processes blocked in
.B errno .BR semop ()
calls on the set (with an error return and
.I errno
set to set to
.BR EIDRM ). .BR EIDRM ).
The effective user\-ID of the calling process must be that of the The effective user\-ID of the calling process must be that of the
super\-user, or match the creator or owner of the semaphore set. superuser, or match the creator or owner of the semaphore set.
The argument The argument
.I semnum .I semnum
is ignored. is ignored.
@ -133,17 +165,19 @@ is ignored.
.B GETALL .B GETALL
Return Return
.B semval .B semval
(i.e., the current value)
for all semaphores of the set into for all semaphores of the set into
.IB arg .array \fR. .IB arg.array .
The argument The argument
.I semnum .I semnum
is ignored. is ignored.
The calling process must have read access privileges on the semaphore set. The calling process must have read permission on the semaphore set.
.TP .TP
.B GETNCNT .B GETNCNT
The system call returns the value of The system call returns the value of
.B semncnt .B semncnt
for the (i.e., the number of processes waiting for the value of
this semaphore to increase) for the
.IR semnum \-th .IR semnum \-th
semaphore of the set semaphore of the set
(i.e. the number of processes waiting for an increase of (i.e. the number of processes waiting for an increase of
@ -151,7 +185,7 @@ semaphore of the set
for the for the
.IR semnum \-th .IR semnum \-th
semaphore of the set). semaphore of the set).
The calling process must have read access privileges on the semaphore set. The calling process must have read permission on the semaphore set.
.TP .TP
.B GETPID .B GETPID
The system call returns the value of The system call returns the value of
@ -159,12 +193,12 @@ The system call returns the value of
for the for the
.IR semnum \-th .IR semnum \-th
semaphore of the set semaphore of the set
(i.e. the pid of the process that executed the last (i.e. the PID of the process that executed the last
.B semop .BR semop ()
call for the call for the
.IR semnum \-th .IR semnum \-th
semaphore of the set). semaphore of the set).
The calling process must have read access privileges on the semaphore set. The calling process must have read permission on the semaphore set.
.TP .TP
.B GETVAL .B GETVAL
The system call returns the value of The system call returns the value of
@ -172,12 +206,13 @@ The system call returns the value of
for the for the
.IR semnum \-th .IR semnum \-th
semaphore of the set. semaphore of the set.
The calling process must have read access privileges on the semaphore set. The calling process must have read permission on the semaphore set.
.TP .TP
.B GETZCNT .B GETZCNT
The system call returns the value of The system call returns the value of
.B semzcnt .B semzcnt
for the (i.e., the number of processes waiting for the value of
this semaphore to become zero) for the
.IR semnum \-th .IR semnum \-th
semaphore of the set semaphore of the set
(i.e. the number of processes waiting for (i.e. the number of processes waiting for
@ -185,51 +220,53 @@ semaphore of the set
of the of the
.IR semnum \-th .IR semnum \-th
semaphore of the set to become 0). semaphore of the set to become 0).
The calling process must have read access privileges on the semaphore set. The calling process must have read permission on the semaphore set.
.TP .TP
.B SETALL .B SETALL
Set Set
.B semval .B semval
for all semaphores of the set using for all semaphores of the set using
.IB arg .array , .IB arg.array ,
updating also the updating also the
.B sem_ctime .I sem_ctime
member of the member of the
.B semid_ds .I semid_ds
structure associated to the set. structure associated with the set.
Undo entries are cleared for altered semaphores in all processes. Undo entries (see
Processes sleeping on the wait queue are awakened if some .BR semop (2))
.B semval are cleared for altered semaphores in all processes.
becomes 0 or increases. If the changes to semaphore values would permit blocked
.BR semop ()
calls in other processes to proceed, then those processes are woken up.
The argument The argument
.I semnum .I semnum
is ignored. is ignored.
The calling process must have alter access privileges on the semaphore set. The calling process must have alter (write) permission on
the semaphore set.
.TP .TP
.B SETVAL .B SETVAL
Set the value of Set the value of
.B semval .B semval
to to
.IB arg .val .IB arg.val
for the for the
.IR semnum \-th .IR semnum \-th
semaphore of the set, updating also the semaphore of the set, updating also the
.B sem_ctime .I sem_ctime
member of the member of the
.B semid_ds .I semid_ds
structure associated to the set. structure associated with the set.
Undo entries are cleared for altered semaphores in all processes. Undo entries are cleared for altered semaphores in all processes.
Processes sleeping on the wait queue are awakened if If the changes to semaphore values would permit blocked
.B semval .BR semop ()
becomes 0 or increases. calls in other processes to proceed, then those processes are woken up.
The calling process must have alter access privileges on the semaphore set. The calling process must have alter permission on the semaphore set.
.SH "RETURN VALUE" .SH "RETURN VALUE"
On failure On failure
.B semctl .B semctl
returns returns \-1
.B \-1
with with
.B errno .I errno
indicating the error. indicating the error.
Otherwise the system call returns a nonnegative value depending on Otherwise the system call returns a nonnegative value depending on
.I cmd .I cmd
@ -256,7 +293,7 @@ All other
values return 0 on success. values return 0 on success.
.SH ERRORS .SH ERRORS
On failure, On failure,
.B errno .I errno
will be set to one of the following: will be set to one of the following:
.TP 11 .TP 11
.B EACCES .B EACCES
@ -280,9 +317,9 @@ capability.
.TP .TP
.B EFAULT .B EFAULT
The address pointed to by The address pointed to by
.IB arg .buf .IB arg.buf
or or
.IB arg .array .IB arg.array
isn't accessible. isn't accessible.
.TP .TP
.B EIDRM .B EIDRM
@ -297,11 +334,11 @@ or
.B EPERM .B EPERM
The argument The argument
.I cmd .I cmd
has value has the value
.B IPC_SET .B IPC_SET
or or
.B IPC_RMID .B IPC_RMID
but the but the effective user ID of the calling process is not the creator but the effective user ID of the calling process is not the creator
(as found in (as found in
.IR sem_perm.cuid ) .IR sem_perm.cuid )
or the owner or the owner
@ -315,14 +352,14 @@ capability.
.B ERANGE .B ERANGE
The argument The argument
.I cmd .I cmd
has value has the value
.B SETALL .B SETALL
or or
.B SETVAL .B SETVAL
and the value to which and the value to which
.B semval .B semval
has to be set (for some semaphore of the set) is less than 0 is to be set (for some semaphore of the set) is less than 0
or greater than the implementation value or greater than the implementation limit
.BR SEMVMX . .BR SEMVMX .
.SH NOTES .SH NOTES
The The
@ -333,15 +370,24 @@ and
control calls are used by the control calls are used by the
.BR ipcs (8) .BR ipcs (8)
program to provide information on allocated resources. program to provide information on allocated resources.
In the future these can be modified as needed or moved to a proc file system In the future these may modified or moved to a /proc file system
interface. interface.
.LP .LP
Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2 Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2
and have become longs under Linux 2.4. To take advantage of this, and have become longs under Linux 2.4. To take advantage of this,
a recompilation under glibc-2.1.91 or later should suffice. a recompilation under glibc-2.1.91 or later should suffice.
(The kernel distinguishes old and new calls by a IPC_64 flag in (The kernel distinguishes old and new calls by an IPC_64 flag in
.IR cmd .) .IR cmd .)
.PP .PP
In some earlier versions of glibc, the
.I semun
union was defined in <sys/sem.h>, but POSIX.1-2001 requires
that the caller define this union.
On versions of glibc where this union is \fInot\fP defined,
the macro
.B _SEM_SEMUN_UNDEFINED
is defined in <sys/sem.h>.
.PP
The following system limit on semaphore sets affects a The following system limit on semaphore sets affects a
.B semctl .B semctl
call: call:
@ -355,7 +401,7 @@ For greater portability it is best to always call
.B semctl .B semctl
with four arguments. with four arguments.
.LP .LP
Under Linux, the function Under Linux,
.B semctl .B semctl
is not a system call, but is implemented via the system call is not a system call, but is implemented via the system call
.BR ipc (2). .BR ipc (2).