View Source: msgrcv(2) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
MSGOP
!!!MSGOP
NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
NOTES
CONFORMING TO
NOTE
SEE ALSO
----
!!NAME


msgop - message operations
!!SYNOPSIS


__# 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 */__
};__


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.


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 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.


If ''msgtyp'' is greater than __0__, 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 __0__, 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:


__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''.


__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:


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.
!!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.
!!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 __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__).
!!CONFORMING TO


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.
!!SEE ALSO


ipc(5), msgctl(2), msgget(2),
msgrcv(2), msgsnd(2)
----
7 pages link to msgrcv(2):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:23:43 am by "perry"
Edit PageHistory Diff Info LikePages