\"      $NetBSD: mq_send.3,v 1.4 2012/03/15 19:04:47 njoly Exp $
\"
\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
\"
Dd June 7, 2010
Dt MQ_SEND 3
Os
Sh NAME
Nm mq_send , mq_timedsend
Nd send a message to a message queue (REALTIME)
Sh LIBRARY
Lb librt
Sh SYNOPSIS
In mqueue.h
Ft int
Fo mq_send
Fa "mqd_t mqdes"
Fa "const char *msg_ptr"
Fa "size_t msg_len"
Fa "unsigned msg_prio"
Fc
In mqueue.h
In time.h
Ft int
Fo mq_timedsend
Fa "mqd_t mqdes"
Fa "const char *msg_ptr"
Fa "size_t msg_len"
Fa "unsigned msg_prio"
Fa "const struct timespec *abs_timeout"
Fc
Sh DESCRIPTION
The
Fn mq_send
function will add the message pointed to by the argument
Fa msg_ptr
to the message queue specified by
Fa mqdes .
The
Fa msg_len
argument specifies the length of the message, in bytes, pointed to by
Fa msg_ptr .
The value of
Fa msg_len
will be less than or equal to the
Fa mq_msgsize
attribute of the message queue, or
Fn mq_send
will fail.
Pp
If the specified message queue is not full,
Fn mq_send
behaves as if the message is inserted into the message queue at the
position indicated by the
Fa msg_prio
argument.
A message with a larger numeric value of
Fa msg_prio
will be inserted before messages with lower values of
Fa msg_prio .
A message will be inserted after other messages in the queue,
if any, with equal
Fa msg_prio .
The value of
Fa msg_prio
will be less than
Brq Dv MQ_PRIO_MAX .
Pp
If the specified message queue is full and
Dv O_NONBLOCK
is not set in the message queue description associated with
Fa mqdes ,
Fn mq_send
blocks until space becomes available to enqueue the message, or until
Fn mq_send
is interrupted by a signal.
If more than one thread is waiting to send when space becomes available
in the message queue, then the thread of the highest priority that has
been waiting the longest will be unblocked to send its message.
If the specified message queue is full and
Dv O_NONBLOCK
is set in the message queue description associated with
Fa mqdes ,
the message will not be queued and
Fn mq_send
will return an error.
Pp
The
Fn mq_timedsend
function will add a message to the message queue specified by
Fa mqdes
in the manner defined for the
Fn mq_send
function.
However, if the specified message queue is full and
Dv O_NONBLOCK
is not set in the message queue description associated with
Fa mqdes ,
the wait for sufficient room in the queue will be terminated
when the specified timeout expires.
If
Dv O_NONBLOCK
is set in the message queue description, this function will be equivalent to
Fn mq_send .
Pp
The timeout will expire when the absolute time specified by
Fa abs_timeout
passes, as measured by the clock on which timeouts are based (that is,
when the value of that clock equals or exceeds
Fa abs_timeout ) ,
or if the absolute time specified by
Fa abs_timeout
has already been passed at the time of the call.
Pp
The resolution of the timeout is based on the CLOCK_REALTIME clock.
The
Fa timespec
argument is defined in the
In time.h
header.
Pp
Under no circumstance will the operation fail with a timeout if there is
sufficient room in the queue to add the message immediately.
The validity of the
Fa abs_timeout
parameter need not be checked when there is sufficient room in the queue.
Sh RETURN VALUES
Upon successful completion, the
Fn mq_send
and
Fn mq_timedsend
functions return a value of zero.
Otherwise, no message will be enqueued,
the functions will return \-1, and the global variable
Va errno
will be set to indicate the error.
Sh ERRORS
The
Fn mq_send
and
Fn mq_timedsend
functions fail if:
Bl -tag -width Er
It Bq Er EAGAIN
The
Dv O_NONBLOCK
flag is set in the message queue description associated with
Fa mqdes ,
and the specified message queue is full.
It Bq Er EBADF
The
Fa mqdes
argument is not a valid message queue descriptor open for writing.
It Bq Er EINTR
A signal interrupted the call to
Fn mq_send
or
Fn mq_timedsend .
It Bq Er EINVAL
The value of
Fa msg_prio
was outside the valid range, or
the process or thread would have blocked, and the
Fa abs_timeout
parameter specified a nanoseconds field value less than zero
or greater than or equal to 1000 million.
It Bq Er EMSGSIZE
The specified message length,
Fa msg_len ,
exceeds the message size attribute of the message queue.
It Bq Er ETIMEDOUT
The
Dv O_NONBLOCK
flag was not set when the message queue was opened,
but the timeout expired before the message could be added to the queue.
El
Sh SEE ALSO
Xr mq 3 ,
Xr mq_receive 3
Sh STANDARDS
These functions are expected to conform to the
St -p1003.1-2001
standard.
Sh HISTORY
The
Fn mq_send
and
Fn mq_timedsend
functions first appeared in
Nx 5.0 .
Sh COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document.
The original Standard can be obtained online at
Lk http://www.opengroup.org/unix/online.html .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.