Differences between current version and revision by previous author of msgop(2).
Other diffs: Previous Major Revision, Previous Revision, or view the Annotated Edit History
| Newer page: | version 3 | Last edited on Saturday, March 15, 2003 1:23:39 am | by PerryLorier | |
| Older page: | version 1 | Last edited on Tuesday, June 4, 2002 12:23:43 am | by perry | Revert |
@@ -1,339 +1,118 @@
-MSGOP
-!!!MSGOP
-NAME
-SYNOPSIS
-DESCRIPTION
-RETURN VALUE
-ERRORS
-NOTES
-CONFORMING TO
-NOTE
-SEE ALSO
-----
!!NAME
+msgop - message operations
-
-msgop - message operations
!!SYNOPSIS
+ __#include <sys/types.h>__
+ __#include <sys/ipc.h>__
+ __#include <sys/msg.h>__
+ __int msgsnd ( int__ ''msqid''__, struct msgbuf *__''msgp''__, size_t__ ''msgsz''__, int__ ''msgflg'' __)__
+ __ssize_t msgrcv ( int__ ''msqid''__, struct msgbuf *__''msgp''__, size_t__ ''msgsz''__, long__ ''msgtyp''__, int__ ''msgflg'' __)__
-__# include
-____int msgsnd ( int__ ''msqid''__, struct msgbuf *__''msgp''__, size_t__ ''msgsz''__, int__ ''msgflg'' __)__
-
-
-__ssize_t msgrcv ( int__ ''msqid''__, struct msgbuf
-*__''msgp''__, size_t__ ''msgsz''__, long__
-''msgtyp''__, int__ ''msgflg''
-__)__
!!DESCRIPTION
+To send or receive a message, the calling process allocates a structure that looks like the following
+ __struct msgbuf {__
+ __long mtype;__ /* message type, must be __
+ __char mtext[[1];__ /* message data */__
+ __};__
-To send or receive a message
, the calling process allocates
-looks like
the following
+but with an array __mtext__ of size ''msgsz''
, a non-negative integer value. The
structure member __mtype__ must have a strictly positive integer value
+
that can be used by the receiving process for message selection (see
the section about __msgrcv__).
+The calling process must have write access permissions to send and read access permissions to receive a message on the queue.
-__struct msgbuf {
-long mtype;
__ /*
message type, must be __
-char mtext[[1];__ /*
message data */__
-};__
+The
__msgsnd
__ system call enqueues a copy of the
message pointed to by the ''msgp'' argument on the
message queue whose identifier is specified by the value of the ''msqid'' argument.
+The argument ''msgflg'' specifies the system call behaviour if enqueuing the new message will require more than __msg_qbytes__ in the queue. Asserting __IPC_NOWAIT__ the message will not be sent and the system call fails returning with __errno__ set to [EAGAIN]. Otherwise the process is suspended until the condition for the suspension no longer exists (in which case the message is sent and the system call succeeds), or the queue is removed (in which case the system call fails with __errno__ set to [EIDRM]), or the process receives a signal that has to be caught (in which case the system call fails with __errno__ set to [EINTR]).
-but with an array __mtext__ of size ''msgsz'', a
-non-negative integer value. The structure member
-__mtype__ must have a strictly positive integer value
-that can be used by the receiving process for message
-selection (see the section about
-__msgrcv__).
+Upon successful completion the message queue data structure is updated as follows:
-The calling process must have write access permissions to
-send and read access permissions to receive a message on the
-queue.
-
-
-The __msgsnd__ system call enqueues a copy of the message
-pointed to by the ''msgp'' argument on the message queue
-whose identifier is specified by the value of the
-''msqid'' argument.
-
-
-The argument ''msgflg'' specifies the system call
-behaviour if enqueuing the new message will require more
-than __msg_qbytes__ in the queue. Asserting
-__IPC_NOWAIT__ the message will not be sent and the
-system call fails returning with __errno__ set to
-__EAGAIN__. Otherwise the process is suspended until the
-condition for the suspension no longer exists (in which case
-the message is sent and the system call succeeds), or the
-queue is removed (in which case the system call fails with
-__errno__ set to __EIDRM__), or the process receives a
-signal that has to be caught (in which case the system call
-fails with __errno__ set to __EINTR__).
-
-
-Upon successful completion the message queue data structure
-is updated as follows:
-
-
-
-
-
+__msg_lspid__ is set to the process-ID of the calling process.
__msg_qnum__ is incremented by 1.
-
__msg_stime__ is set to the current time.
+The system call __msgrcv__ reads a message from the message queue specified by ''msqid'' into the __msgbuf__ pointed to by the ''msgp'' argument removing from the queue, on success, the read message.
-The system call __msgrcv__ reads a message from the
-message queue specified by
''msqid
'' into
the
-msgbuf
__ pointed to by the ''msgp'' argument
-removing from
the queue
, on success
, the read
-message.
+The argument
''msgsz
'' specifies
the maximum size in bytes for the member
__mtext
__ of the structure
pointed to by the ''msgp'' argument. If
the message text has length greater than ''msgsz''
, then if the ''msgflg'' argument asserts __MSG_NOERROR__
, 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 __errno__ set to [E2BIG]
.
-The argument ''msgsz
'' specifies the maximum size in
-bytes for the member __mtext__
of the structure pointed
-to by the ''msgp'' argument. If the
message text has
-length greater than ''msgsz'', then if the ''msgflg''
-argument asserts __MSG_NOERROR__, 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 __errno__ set to
-__E2BIG__.
+The argument ''msgtyp
'' specifies the type
of message requested as follows:
+If ''msgtyp'' is __0__, then the message on the queue's front is read.
-The argument
''msgtyp'' specifies
the type of
message
-requested as follows:
+If
''msgtyp'' is greater than ____, then
the first
message on the queue of type ''msgtyp'' is read if __MSG_EXCEPT__ isn't asserted by the ''msgflg''
+argument, otherwise the first message on the queue of type not equal to ''msgtyp'' will be read.
-
-If ''msgtyp'' is ____, then the message on the
-queue's front is read.
-
-
-If ''msgtyp'' is greater than ____, then the first
-message on the queue of type ''msgtyp'' is read if
-__MSG_EXCEPT__ isn't asserted by the ''msgflg''
-argument, otherwise the first message on the queue of type
-not equal to ''msgtyp'' will be read.
-
-
-
-
-
+If ''msgtyp'' is less than ____, then the first message on the queue with the lowest type less than or equal to the absolute value of ''msgtyp'' will be
read.
+The ''msgflg'' argument asserts none, one or more (or-ing them) among the following flags:
-The ''msgflg'' argument asserts none, one or more (or-ing
-them) among
the following flags:
+__IPC_NOWAIT__ For immediate return if no message of
the requested type is on the queue. The system call fails with errno set to __ENOMSG__.
+__MSG_EXCEPT__ Used with ''msgtyp'' greater than __0__ to read the first message on the queue with message type that differs from ''msgtyp''.
-__IPC
_NOWAIT
__ For immediate return
if no message of the
-requested type is on the queue. The system call fails with
-errno set to __ENOMSG__
.
+__MSG
_NOERROR
__ To truncate the message text
if longer than ''msgsz'' bytes
.
+If no message of the requested type is available and __IPC_NOWAIT__ isn't asserted in ''msgflg'', the calling process is blocked until one of the following conditions occurs:
-__MSG_EXCEPT__ Used with ''msgtyp'' greater than
-____ to read
the first message
on the queue with message
-type that differs from ''msgtyp''
.
+A message of
the desired type is placed
on the queue.
+The message queue is removed from the system. In such a case the system call fails with __errno__ set to [EIDRM].
-__MSG
_NOERROR
__ To truncate the message text if longer
-than ''msgsz'' bytes
.
+The calling process receives a signal that has to be caught. In such a case the system call fails with
__errno
__ set to [EINTR]
.
+Upon successful completion the message queue data structure is updated as follows:
-If no message of the requested type is available and
-__IPC_NOWAIT__ isn't asserted in ''msgflg'', the
-calling process is blocked until one of the following
-conditions occurs:
-
-
-A message of the desired type is placed on the
-queue.
-
-
-The message queue is removed from the system. In such a case
-the system call fails with __errno__ set to
-__EIDRM__.
-
-
-The calling process receives a signal that has to be caught.
-In such a case the system call fails with __errno__ set
-to __EINTR__.
-
-
-Upon successful completion the message queue data structure
-is updated as follows:
-
-
-
-
-
+__msg_lrpid__ is set to the process-ID of the calling process.
__msg_qnum__ is decremented by 1.
+__msg_rtime__ is set to the current time.
-__msg_rtime__ is set to the current time.
!!RETURN VALUE
+On a failure both functions return __-1__ with __errno__ indicating the error, otherwise __msgsnd__ returns __0__ and __msgrvc__ returns the number of bytes actually copied into the __mtext__ array.
-
-On a failure both functions return __-1__ with
-__errno__ indicating the error, otherwise __msgsnd__
-returns __0__ and __msgrvc__ returns the number of
-bytes actually copied into the __mtext__
-array.
!!ERRORS
+When __msgsnd__ fails, at return __errno__ will be set to one among the following values:
+;[EAGAIN]: The message can't be sent due to the __msg_qbytes__ limit for the queue and __IPC_NOWAIT__ was asserted in ''mgsflg''.
+;[EACCES]: The calling process has no write access permissions on the message queue.
+;[EFAULT]: The address pointed to by ''msgp'' isn't accessible.
+;[EIDRM]: The message queue was removed.
+;[EINTR]: Sleeping on a full message queue condition, the process received a signal that had to be caught.
+;[EINVAL]: Invalid ''msqid'' value, or nonpositive ''mtype'' value, or invalid ''msgsz'' value (less than 0 or greater than the system value __MSGMAX__).
+;[ENOMEM]: The system has not enough memory to make a copy of the supplied __msgbuf__.
-When __msgsnd
__ fails, at return __errno__ will be set
-
+When __msgrcv
__ fails, at return __errno__ will be set to one among the following values:
+;[E2BIG]: The message text length is greater than ''msgsz'' and __MSG_NOERROR__ isn't asserted in ''msgflg''.
+;[EACCES]: The calling process has no read access permissions on the message queue.
+;[EFAULT]: The address pointed to by ''msgp'' isn't accessible.
+;[EIDRM]: While the process was sleeping to receive a message, the message queue was removed.
+;[EINTR]: While the process was sleeping to receive a message, the process received a signal that had to be caught.
+;[EINVAL]: Illegal ''msgqid'' value, or ''msgsz'' less than __0__.
+;[ENOMSG]: __IPC_NOWAIT__ was asserted in ''msgflg'' and no message of the requested type existed on the message queue.
-__EAGAIN__
-
-
-The message can't be sent due to the __msg_qbytes__ limit
-for the queue and __IPC_NOWAIT__ was asserted in
-''mgsflg''.
-
-
-__EACCES__
-
-
-The calling process has no write access permissions on the
-message queue.
-
-
-__EFAULT__
-
-
-The address pointed to by ''msgp'' isn't
-accessible.
-
-
-__EIDRM__
-
-
-The message queue was removed.
-
-
-__EINTR__
-
-
-Sleeping on a full message queue condition, the process
-received a signal that had to be caught.
-
-
-__EINVAL__
-
-
-Invalid ''msqid'' value, or nonpositive ''mtype''
-value, or invalid ''msgsz'' value (less than 0 or greater
-than the system value __MSGMAX__).
-
-
-__ENOMEM__
-
-
-The system has not enough memory to make a copy of the
-supplied __msgbuf__.
-
-
-When __msgrcv__ fails, at return __errno__ will be set
-to one among the following values:
-
-
-__E2BIG__
-
-
-The message text length is greater than ''msgsz'' and
-__MSG_NOERROR__ isn't asserted in
-''msgflg''.
-
-
-__EACCES__
-
-
-The calling process has no read access permissions on the
-message queue.
-
-
-__EFAULT__
-
-
-The address pointed to by ''msgp'' isn't
-accessible.
-
-
-__EIDRM__
-
-
-While the process was sleeping to receive a message, the
-message queue was removed.
-
-
-__EINTR__
-
-
-While the process was sleeping to receive a message, the
-process received a signal that had to be
-caught.
-
-
-__EINVAL__
-
-
-Illegal ''msgqid'' value, or ''msgsz'' less than
-__0__.
-
-
-__ENOMSG__
-
-
-__IPC_NOWAIT__ was asserted in ''msgflg'' and no
-message of the requested type existed on the message
-queue.
!!NOTES
+The followings are system limits affecting a __msgsnd__ system call:
+;__MSGMAX__: Maximum size for a message text: the implementation set this value to 4080 bytes.
+;__MSGMNB__: Default maximum size in bytes of a message queue: policy dependent. The super-user can increase the size of a message queue beyond __MSGMNB__ by a __msgctl__ system call.
+The implementation has no intrinsic limits for the system wide maximum number of message headers (__MSGTQL__) and for the system wide maximum size in bytes of the message
+pool (__MSGPOOL__).
-The followings are system limits affecting a __msgsnd__
-system call:
-
-
-__MSGMAX__
-
-
-Maximum size for a message text: the implementation set this
-value to 4080 bytes.
-
-
-__MSGMNB__
-
-
-Default maximum size in bytes of a message queue: policy
-dependent. The super-user can increase the size of a message
-queue beyond __MSGMNB__ by a __msgctl__ system
-call.
-
-
-The implementation has no intrinsic limits for the system
-wide maximum number of message headers (__MSGTQL__) and
-for the system wide maximum size in bytes of the message
-pool (__MSGPOOL__).
!!CONFORMING TO
+SVr4, SVID.
-
-SVr4, SVID.
!!NOTE
+The pointer argument is declared as ''struct msgbuf *'' with libc4, libc5, glibc 2.0, glibc 2.1. It is declared as ''void *'' (''const void *'' for ''msgsnd()'') with
+glibc 2.2, following the SUSv2.
-
-The pointer argument is declared as ''struct msgbuf *''
-with libc4, libc5, glibc 2.0, glibc 2.1. It is declared as
-''void *'' (''const void *'' for ''msgsnd()'') with
-glibc 2.2, following the SUSv2.
!!SEE ALSO
-
-
-
-
-----
+ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2)
