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

Formatting & lag clean-ups; added /proc file notes

This commit is contained in:
Michael Kerrisk 2004-11-10 17:24:20 +00:00
parent c952e22670
commit fe1c5199cc
2 changed files with 158 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
man2/msgop.2
View File

@ -30,8 +30,11 @@
.\" instead of .B)
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Added notes on capability requirements
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Language and formatting clean-ups
.\" Added notes on /proc files
.\"
.TH MSGOP 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
.TH MSGOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual"
.SH NAME
msgop \- message operations
.SH SYNOPSIS
@ -57,7 +60,18 @@ msgop \- message operations
.BI "long " msgtyp ,
.BI "int " msgflg );
.SH DESCRIPTION
To send or receive a message, the calling process allocates a structure
The
.BR msgsnd ()
and
.BR msgrcv ()
system calls are used, respectively, to send messages to,
and receive messages from, a message queue.
The calling process must have write permission on the message queue
in order to send a message, and read permission to receive a message.
.PP
The
.I msgp
argument is a pointer to caller-defined structure
of the following general form:
.sp
.B
@ -84,24 +98,23 @@ Messages of zero length (i.e., no
field) are permitted.
The
.I mtype
field must have a strictly positive integer value that can be
field must have a strictly positive integer value.
This value can be
used by the receiving process for message selection
(see the section about
.BR msgrcv ).
.PP
The calling process must have write permission to send
and read permission to receive a message on the queue.
(see the description of
.BR msgrcv ()
below).
.PP
The
.B msgsnd
.BR msgsnd ()
system call appends a copy of the message pointed to by
.I msgp
to the message queue whose identifier is specified
by
.IR msqid .
.PP
If sufficient space is available on the queue,
.B msgsnd
If sufficient space is available in the queue,
.BR msgsnd ()
succeeds immediately.
(The queue capacity is defined by the
.I msg_bytes
@ -109,20 +122,20 @@ field in the associated data structure for the message queue.
During queue creation this field is initialised to
.B MSGMNB
bytes, but this limit can be modified using
.BR msgctl .)
If insufficient space is available on the queue, then the default
.BR msgctl ().)
If insufficient space is available in the queue, then the default
behaviour of
.B msgsnd
.BR msgsnd ()
is to block until space becomes available.
If
.B IPC_NOWAIT
is asserted in
.B msgflg
is specified in
.IR msgflg ,
then the call instead fails with the error
.BR EAGAIN .
A blocked
.B msgsnd
.BR msgsnd ()
call may also fail if the queue is removed
(in which case the system call fails with
.I errno
@ -135,7 +148,7 @@ set to
.BR EINTR ).
.RB ( msgsnd " and " msgrcv
are never automatically restarted after being interrupted by a
signal handler, regardless of the setting of the
signal handler, regardless of the setting of the
.B SA_RESTART
flag when establishing a signal handler.)
.PP
@ -152,7 +165,7 @@ is incremented by 1.
is set to the current time.
.PP
The system call
.B msgrcv
.BR msgrcv ()
reads a message from the message queue specified by
.I msqid
into the
@ -170,13 +183,19 @@ of the structure pointed to by the
argument.
If the message text has length greater than
.IR msgsz ,
then if the
.I msgflg
argument asserts
.BR MSG_NOERROR ,
then the behaviour depends on whether
.BR MSG_NOERROR
is specified in
.IR msgflg .
If
.BR MSG_NOERROR
is specified, then
the message text will be truncated (and the truncated part will be
lost), otherwise the message isn't removed from the queue and
the system call fails returning with
lost); if
.BR MSG_NOERROR
is not specified, then
the message isn't removed from the queue and
the system call fails returning \-1 with
.I errno
set to
.BR E2BIG .
@ -187,53 +206,51 @@ specifies the type of message requested as follows:
.IP
If
.I msgtyp
is
.BR 0 ,
is 0,
then the first message in the queue is read.
.IP
If
.I msgtyp
is greater than
.BR 0 ,
then the first message on the queue of type
is greater than 0,
then the first message in the queue of type
.I msgtyp
is read, unless
.B MSG_EXCEPT
was asserted in
was specified in
.IR msgflg ,
in which case
the first message on the queue of type not equal to
the first message in the queue of type not equal to
.I msgtyp
will be read.
.IP
If
.I msgtyp
is less than
.BR 0 ,
then the first message on the queue with the lowest type less than or
is less than 0,
then the first message in the queue with the lowest type less than or
equal to the absolute value of
.I msgtyp
will be read.
.PP
The
.I msgflg
argument asserts none, one or more (or\-ing them) of the following
flags:
.IP
argument is a bit mask constructed by ORing together zero or more
of the following flags:
.TP
.B IPC_NOWAIT
For immediate return if no message of the requested type is on the queue.
The system call fails with errno set to
For immediate return if no message of the requested type is in the queue.
The system call fails with
.I errno
set to
.BR ENOMSG .
.IP
.TP
.B MSG_EXCEPT
Used with
.I msgtyp
greater than
.B 0
to read the first message on the queue with message type that differs
greater than 0
to read the first message in the queue with message type that differs
from
.IR msgtyp .
.IP
.TP
.B MSG_NOERROR
To truncate the message text if longer than
.I msgsz
@ -241,11 +258,11 @@ bytes.
.PP
If no message of the requested type is available and
.B IPC_NOWAIT
isn't asserted in
isn't specified in
.IR msgflg ,
the calling process is blocked until one of the following conditions occurs:
.IP
A message of the desired type is placed on the queue.
A message of the desired type is placed in the queue.
.IP
The message queue is removed from the system.
In this case the system call fails with
@ -271,39 +288,37 @@ is decremented by 1.
.I msg_rtime
is set to the current time.
.SH "RETURN VALUE"
On a failure both functions return
.B \-1
On failure both functions return \-1
with
.I errno
indicating the error,
otherwise
.B msgsnd
returns
.B 0
.BR msgsnd ()
returns 0
and
.B msgrvc
.BR msgrvc ()
returns the number of bytes actually copied into the
.I mtext
array.
.SH ERRORS
When
.B msgsnd
fails, at return
.BR msgsnd ()
fails,
.I errno
will be set to one among the following values:
.TP
.TP 11
.B EACCES
The calling process does not have write permission on the message queue,
and does not have the
.BR CAP_IPC_OWNER
capability.
.TP 11
.TP
.B EAGAIN
The message can't be sent due to the
.I msg_qbytes
limit for the queue and
.B IPC_NOWAIT
was asserted in
was specified in
.IR mgsflg .
.TP
.B EFAULT
@ -333,8 +348,8 @@ The system has not enough memory to make a copy of the supplied
.IR msgbuf .
.PP
When
.B msgrcv
fails, at return
.BR msgrcv ()
fails,
.I errno
will be set to one among the following values:
.TP 11
@ -343,7 +358,7 @@ The message text length is greater than
.I msgsz
and
.B MSG_NOERROR
isn't asserted in
isn't specified in
.IR msgflg .
.TP
.B EACCES
@ -363,36 +378,37 @@ the message queue was removed.
.TP
.B EINTR
While the process was sleeping to receive a message,
the process received a signal that had to be caught.
the process caught a signal.
.TP
.B EINVAL
Illegal
.I msgqid
value, or
was invalid, or
.I msgsz
less than
.BR 0 .
was less than 0.
.TP
.B ENOMSG
.B IPC_NOWAIT
was asserted in
was specified in
.I msgflg
and no message of the requested type existed on the message queue.
.SH NOTES
The followings are system limits affecting a
.B msgsnd
The following are system limits affecting a
.BR msgsnd ()
system call:
.TP 11
.B MSGMAX
Maximum size for a message text: the implementation set this value to
8192 bytes.
Maximum size for a message text: 8192 bytes
(on Linux, this limit can be read and modified via
.IR /proc/sys/kernel/msgmax ).
.TP
.B MSGMNB
Default maximum size in bytes of a message queue: 16384 bytes.
The super\-user can increase the size of a message queue beyond
Default maximum size in bytes of a message queue: 16384 bytes
(on Linux, this limit can be read and modified via
.IR /proc/sys/kernel/msgmnb ).
The superuser can increase the size of a message queue beyond
.B MSGMNB
by a
.B msgctl
.BR msgctl ()
system call.
.PP
The implementation has no intrinsic limits for the system wide maximum

118
man2/semop.2
View File

@ -24,8 +24,11 @@
.\" Modified 2002-01-08, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
.\" Modified 2004-05-27, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Language and formatting clean-ups
.\" Added notes on /proc files
.\"
.TH SEMOP 2 2003-04-28 "Linux 2.4" "Linux Programmer's Manual"
.TH SEMOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual"
.SH NAME
semop, semtimedop \- semaphore operations
.SH SYNOPSIS
@ -47,8 +50,7 @@ semop, semtimedop \- semaphore operations
.BI "unsigned " nsops ,
.BI "struct timespec *" timeout );
.SH DESCRIPTION
A semaphore is represented by an anonymous structure
including the following members:
Each semaphore in a semaphore set has the following associated values:
.sp
.in +4n
.nf
@ -59,23 +61,23 @@ pid_t sempid; /* process that did last op */
.sp
.in -4n
.fi
The function
.B semop
performs operations on selected members of the semaphore set indicated by
.BR semop ()
performs operations on selected semaphores in the set indicated by
.IR semid .
Each of the
.I nsops
elements in the array pointed to by
.I sops
specifies an operation to be performed on a semaphore by a
.B "struct sembuf"
including the following members:
specifies an operation to be performed on a single semaphore.
The elements of this structure are of type
.BR "struct sembuf" ,
containing the following members:
.sp
.in +4n
.nf
unsigned short sem_num; /* semaphore number */
short sem_op; /* semaphore operation */
short sem_flg; /* operation flags */
unsigned short sem_num; /* semaphore number */
short sem_op; /* semaphore operation */
short sem_flg; /* operation flags */
.sp
.in -4n
.fi
@ -85,9 +87,9 @@ are
.B IPC_NOWAIT
and
.BR SEM_UNDO .
If an operation asserts
If an operation specifies
.BR SEM_UNDO ,
it will be undone when the process exits.
it will be automatically undone when the process terminates.
.PP
The set of operations contained in
.I sops
@ -105,8 +107,7 @@ fields, as noted below.
Each operation is performed on the
.IR sem_num \-th
semaphore of the semaphore set, where the first semaphore of the set
is semaphore
.BR 0 .
is numbered 0.
There are three types of operation, distinguished by the value of
.IR sem_op .
.PP
@ -117,7 +118,7 @@ the semaphore value
.RI ( semval ).
Furthermore, if
.B SEM_UNDO
is asserted for this operation, the system updates the process undo count
is specified for this operation, the system updates the process undo count
.RI ( semadj )
for this semaphore.
This operation can always proceed \- it never forces a process to wait.
@ -125,16 +126,17 @@ The calling process must have alter permission on the semaphore set.
.PP
If
.I sem_op
is zero, the process must have read access permission on the semaphore
is zero, the process must have read permission on the semaphore
set.
This is a "wait-for-zero" operation: if
.I semval
is zero, the operation can immediately proceed.
Otherwise, if
.B IPC_NOWAIT
is asserted in
is specified in
.IR sem_flg ,
the system call fails with
.BR semop ()
fails with
.I errno
set to
.B EAGAIN
@ -153,7 +155,9 @@ becomes 0, at which time the value of
is decremented.
.IP \(bu
The semaphore set
is removed: the system call fails, with
is removed:
.BR semop ()
fails, with
.I errno
set to
.BR EIDRM .
@ -161,7 +165,9 @@ set to
The calling process catches a signal:
the value of
.I semzcnt
is decremented and the system call fails, with
is decremented and
.BR semop ()
fails, with
.I errno
set to
.BR EINTR .
@ -169,8 +175,10 @@ set to
The time limit specified by
.I timeout
in a
.B semtimedop
call expires: the system call fails, with
.BR semtimedop ()
call expires:
.BR semop ()
fails, with
.I errno
set to
.BR EAGAIN .
@ -190,7 +198,7 @@ is subtracted from
.IR semval ,
and, if
.B SEM_UNDO
is asserted for this operation, the system updates the process undo count
is specified for this operation, the system updates the process undo count
.RI ( semadj )
for this semaphore.
If the absolute value of
@ -199,9 +207,10 @@ is greater than
.IR semval ,
and
.B IPC_NOWAIT
is asserted in
is specified in
.IR sem_flg ,
the system call fails, with
.BR semop ()
fails, with
.I errno
set to
.B EAGAIN
@ -225,11 +234,13 @@ is subtracted from
.I semval
and, if
.B SEM_UNDO
is asserted for this operation, the system updates the process undo count
is specified for this operation, the system updates the process undo count
.RI ( semadj )
for this semaphore.
.IP \(bu
The semaphore set is removed from the system: the system call fails with
The semaphore set is removed from the system:
.BR semop ()
fails, with
.I errno
set to
.BR EIDRM .
@ -237,7 +248,9 @@ set to
The calling process catches a signal:
the value of
.I semncnt
is decremented and the system call fails with
is decremented and
.BR semop ()
fails, with
.I errno
set to
.BR EINTR .
@ -245,7 +258,7 @@ set to
The time limit specified by
.I timeout
in a
.B semtimedop
.BR semtimedop ()
call expires: the system call fails, with
.I errno
set to
@ -262,10 +275,9 @@ In addition, the
.\" .I sem_ctime
is set to the current time.
.PP
The function
.B semtimedop
behaves identically to the function
.B semop
.BR semtimedop ()
behaves identically to
.BR semop ()
except that in those cases were the calling process would sleep,
the duration of that sleep is limited by the amount of elapsed
time specified by the
@ -273,7 +285,8 @@ time specified by the
structure whose address is passed in the
.I timeout
parameter. If the specified time limit has been reached,
the system call fails with
.BR semtimedop ()
fails with
.I errno
set to
.B EAGAIN
@ -285,14 +298,16 @@ If the
parameter is
.BR NULL ,
then
.B semtimedop
.BR semtimedop ()
behaves exactly like
.BR semop .
.BR semop ().
.SH "RETURN VALUE"
If successful the system call returns
.BR 0 ,
otherwise it returns
.B \-1
If successful
.BR semop ()
and
.BR semtimedop ()
return 0;
otherwise they return -1
with
.I errno
indicating the error.
@ -319,7 +334,7 @@ capability.
.B EAGAIN
An operation could not proceed immediately and either
.BR IPC_NOWAIT
was asserted in its
was specified in
.I sem_flg
or the time limit specified in
.I timeout
@ -354,7 +369,7 @@ has a non-positive value.
.B ENOMEM
The
.I sem_flg
of some operation asserted
of some operation specified
.B SEM_UNDO
and the system does not have enough memory to allocate the undo
structure.
@ -371,15 +386,15 @@ The
.I sem_undo
structures of a process aren't inherited across a
.BR fork (2)
system call, but they are inherited across a
system call, but they are inherited across an
.BR execve (2)
system call.
.PP
.B semop
.BR semop ()
is never automatically restarted after being interrupted by a signal handler,
regardless of the setting of the
.B SA_RESTART
flags when establishing a signal handler.
flag when establishing a signal handler.
.PP
.I semadj
is a per\-process integer which is simply the (negative) count
@ -402,13 +417,16 @@ for a semaphore can all be retrieved using appropriate
calls.
.PP
The followings are limits on semaphore set resources affecting a
.B semop
.BR semop ()
call:
.TP
.B SEMOPM
Maximum number of operations allowed for one
.B semop
call (32).
.BR semop ()
call (32)
(on Linux, this limit can be read and modified via the third field of
.IR /proc/sys/kernel/sem ).
.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
.TP
.B SEMVMX
Maximum allowable value for