.\"	$NetBSD: mq_send.3,v 1.2 2010/03/22 22:00:37 joerg Exp $
.\"
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
.\"
.Dd January 5, 2009
.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_close 3 ,
.Xr mq_getattr 3 ,
.Xr mq_notify 3 ,
.Xr mq_open 3 ,
.Xr mq_receive 3 ,
.Xr mq_setattr 3 ,
.Xr mq_unlink 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
http://www.opengroup.org/unix/online.html .