system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-09-06 17:18:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add manuals for POSIX message queue.

Browse source
This commit is contained in:
David Xu 2005-11-30 04:12:37 +00:00
parent 8d98402040
commit 968cc4bd61
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=152942
8 changed files with 1077 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
lib/libc/sys/Makefile.inc
View file

@ -70,8 +70,10 @@ MAN+= _exit.2 accept.2 access.2 acct.2 adjtime.2 \
kldunload.2 kqueue.2 kse.2 ktrace.2 link.2 lio_listio.2 listen.2 \
lseek.2 \
madvise.2 mincore.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.2 \
mlockall.2 mmap.2 modfind.2 modnext.2 modstat.2 mount.2 \
mprotect.2 msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 ntp_gettime.2 \
mlockall.2 mmap.2 modfind.2 modnext.2 modstat.2 mount.2 mprotect.2 \
mq_close.2 mq_getattr.2 mq_notify.2 mq_open.2 mq_receive.2 mq_send.2 \
mq_setattr.2 \
msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 ntp_gettime.2 \
nfssvc.2 open.2 pathconf.2 pipe.2 poll.2 profil.2 ptrace.2 quotactl.2 \
read.2 readlink.2 reboot.2 recv.2 rename.2 revoke.2 rfork.2 rmdir.2 \
rtprio.2 select.2 semctl.2 semget.2 semop.2 send.2 sendfile.2 \

87
lib/libc/sys/mq_close.2 Normal file
View file

@ -0,0 +1,87 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_CLOSE 2
.Os
.Sh NAME
.Nm mq_close
.Nd "close a message queue (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In mqueue.h
.Ft int
.Fn mq_close "mqd_t mqdes"
.Sh DESCRIPTION
The
.Fn mq_close
syscall removes the association between the message queue descriptor,
.Fa mqdes ,
and its message queue. The results of using this message queue descriptor
after successful return from this
.Fn mq_close ,
and until the return of this message queue descriptor from a subsequent
.Fn mq_open ,
are undefined.
.Pp
If the process has successfully attached a notification request to the
message queue via this
.Fa mqdes ,
this attachment will be removed, and the message queue is available for
another process to attach for notification.
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_close
syscall returns a value of zero; otherwise, the syscall returns a
value of -1 and set
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_close
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa mqdes
argument is not a valid message queue descriptor.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_unlink 2
.Sh STANDARDS
The
.Fn mq_close
system call conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .

107
lib/libc/sys/mq_getattr.2 Normal file
View file

@ -0,0 +1,107 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_CLOSE 2
.Os
.Sh NAME
.Nm mq_getattr
.Nd "get message queue attributes (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In mqueue.h
.Ft int
.Fn mq_getattr "mqd_t mqdes" "struct mq_attr *mqstat"
.Sh DESCRIPTION
The
.Fn mq_getattr
syscall obtains status information and attributes of the message queue and
the open message queue description associated with the message queue
descriptor.
.Pp
The
.Fa mqdes
argument specifies a message queue descriptor.
.Pp
The results are returned in the
.Vt mq_attr
structure referenced by the mqstat argument.
.Pp
Upon return, the following members will have the values associated with the
open message queue description as set when the message queue was opened and
as modified by subsequent
.Fn mq_setattr
calls:
.Va mq_flags.
.Pp
The following attributes of the message queue will be returned as set at
message queue creation:
.Va mq_maxmsg ,
.Va mq_msgsize .
.Pp
Upon return, the following members within the
.Vt mq_attr
structure referenced by the mqstat argument will be set to the current state
of the message queue:
.Pp
.Bl -tag -width Er
.It Va mq_flags
The number of messages currently on the queue.
.El
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_getattr
syscall returns zero. Otherwise, the syscall returns -1 and set
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_getattr
syscall call
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa mqdes
argument is not a valid message queue descriptor.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_setattr 2 ,
.Xr mq_timedsend 2 ,
.Sh STANDARDS
The
.Fn mq_getattr
system call conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .

103
lib/libc/sys/mq_notify.2 Normal file
View file

@ -0,0 +1,103 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_NOTIFY 2
.Os
.Sh NAME
.Nm mq_notify
.Nd "notify process that a message is available (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In mqueue.h
.Ft int
.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification"
.Sh DESCRIPTION
If the argument notification is not
.Dv NULL ,
this syscall will register the calling process to be notified of message
arrival at an empty message queue associated with the specified message
queue descriptor,
.Fa mqdes.
The notification specified by the notification argument will be sent to
the process when the message queue transitions from empty to non-empty.
At any time, only one process may be registered for notification by a
message queue. If the calling process or any other process has already
registered for notification of message arrival at the specified message
queue, subsequent attempts to register for that message queue will fail.
.Pp
If notification is
.Dv NULL
and the process is currently registered for notification by the specified
message queue, the existing registration will be removed.
.Pp
When the notification is sent to the registered process, its registration
is removed. The message queue then is available for registration.
.Pp
If a process has registered for notification of message arrival at a
message queue and some thread is blocked in
.Fn mq_receive
waiting to receive a message when a message arrives at the queue, the
arriving message will satisfy the appropriate
.Fn mq_receive .
The resulting behavior is as if the message queue remains empty, and no
notification will be sent.
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_notify
syscall returns a value of zero; otherwise, the function returns a value
of -1 and set
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_notify
syscall call
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa mqdes
argument is not a valid message queue descriptor.
.It Bq Er EBUSY
process is already registered for notification by the message queue.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_timedsend 2
.Sh STANDARDS
The
.Fn mq_notify
system call conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .

278
lib/libc/sys/mq_open.2 Normal file
View file

@ -0,0 +1,278 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_OPEN 2
.Os
.Sh NAME
.Nm mq_open
.Nd "open a message queue (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In mqueue.h
.Ft mqd_t
.Fn mq_open "const char *name" "int oflag" "..."
.Sh DESCRIPTION
The
.Fn mq_open
system call establishs the connection between a process and a message queue
with a message queue descriptor. It creates an open message queue
description that refers to the message queue, and a message queue descriptor
that refers to that open message queue description. The message queue
descriptor is used by other functions to refer to that message queue. The
.Fa name
argument points to a string naming a message queue. It is unspecified
whether the name appears in the file system and is visible to other functions
that take pathnames as arguments. The
.Fa name
argument conforms to the construction rules for a pathname. If
.Fa name
begins with the slash character, then processes calling
.Fn mq_open
with the same value of
.Fa name
refers to the same message queue object, as long as that name has not been
removed. If
.Fa name
does not begin with the slash character, the effect is implementation-defined.
The interpretation of slash characters other than the leading slash character
in
.Fa name
is implementation-defined. If the
.Fa name
argument is not the name of an existing message queue and creation is not
requested,
.Fn mq_open
will fail and returns an error.
.Pp
A message queue descriptor may be implemented using a file descriptor, in
which case applications can open up to at least
.Brq Dv OPEN_MAX
file and message queues.
.Pp
The
.Fa oflag
argument requests the desired receive and/or send access to the message
queue. The requested access permission to receive messages or send messages
would be granted if the calling process would be granted read or write access,
respectively, to an equivalently protected file.
.Pp
The value of
.Fa oflag
is the bitwise-inclusive OR of values from the following list.
Applications should specify exactly one of the first three values (access
modes) below in the value of
.Fa oflag :
.Bl -tag -width Er
.It Bq Er O_RDONLY
Open the message queue for receiving messages. The process can use the
returned message queue descriptor with
.Fn mq_receive ,
but not
.Fn mq_send .
A message queue may be open multiple times in the same or different processes
for receiving messages.
.It Bq Er O_WRONLY
Open the queue for sending messages. The process can use the returned
message queue descriptor with
.Fn mq_send
but not
.Fn mq_receive .
A message queue may be open multiple times in the same or different processes
for sending messages.
.It Bq Er O_RDWR
Open the queue for both receiving and sending messages. The process can use
any of the functions allowed for
.Dv O_RDONLY
and
.Dv O_WRONLY .
A message queue may be open multiple times in the same or different processes
for sending messages.
.El
.Pp
Any combination of the remaining flags may be specified in the value of
.Fa oflag :
.Bl -tag -width Er
.It Bq Er O_CREAT
Create a message queue. It requires two additional arguments:
.Fa mode ,
which is of type
.Vt mode_t ,
and
.Fa attr ,
which is a pointer to an
.Vt mq_attr
structure. If the pathname
.Fa name
has already been used to create a message queue that still exists, then
this flag has no effect, except as noted under
.Dv O_EXCL .
Otherwise, a message queue will be created without any messages
in it. The user ID of the message queue will be set to the effective user ID
of the process, and the group ID of the message queue will be set to the
effective group ID of the process. The permission bits of the message queue
will be set to the value of the
.Fa mode
argument, except those set in the file mode creation mask of the process.
When bits in
.Fa mode
other than the file permission bits are specified, the effect is
unspecified. If
.Fa attr
is
.Dv NULL ,
the message queue is created with implementation-defined default message
queue attributes. If attr is non-NULL and the calling process has the
appropriate privilege on name, the message queue mq_maxmsg and mq_msgsize
attributes will be set to the values of the corresponding members in the
.Vt mq_attr
structure referred to by
.Fa attr .
If
.Fa attr
is non-NULL, but the calling process does not have the appropriate privilege
on name, the
.Fn mq_open
function will fail and return an error without creating the message queue.
.It Bq Er O_EXCL
If
.Dv O_EXCL
and
.Dv O_CREAT
are set,
.Fn mq_open
will fail if the message queue name exists.
.It Bq Er O_NONBLOCK
Determines whether an
.Fn mq_send
or
.Fn mq_receive
waits for resources or messages that are not currently available, or fails
with errno set to
.Er EAGAIN ;
see
.Fn mq_send
and
.Fn mq_receive
for details.
.Pp
The
.Fn mq_open
function does not add or remove messages from the queue.
.Sh NOTES
FreeBSD implements message queue based on file descriptor. The descriptor
is inherited by child after
.Fn fork .
The descriptor is closed in new image after
.Fn exec .
.Fn select
and
.Fn kevent
syscalls are supported for message queue descriptor.
.Sh RETURN VALUES
Upon successful completion, the function returns a message queue
descriptor; otherwise, the function returns (mqd_t)-1 and set
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_open
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
The message queue exists and the permissions specified by
.Fa oflag
are denied, or the message queue does not exist and permission to create the
message queue is denied
.It Bq Er EEXIST
.Dv O_CREAT
and
.Dv O_EXCL
are set and the named message queue already exists.
.It Bq Er EINTR
The
.Fn mq_open
function was interrupted by a signal.
.It Bq Er EINVAL
The
.Fn mq_open
function is not supported for the given name.
.It Bq Er EINVAL
.Dv O_CREAT
was specified in
.Fa oflag ,
the value of attr is not
.Dv NULL ,
and either
.Va mq_maxmsg
or
.Va mq_msgsize
was less than or equal to zero.
.It Bq Er EMFILE
Too many message queue descriptors or file descriptors are currently in use
by this process.
.It Bq Er ENAMETOOLONG
The length of the name argument exceeds
.Brq Dv PATH_MAX
or a pathname component
is longer than
.Brq Dv NAME_MAX .
.It Bq Er ENFILE
Too many message queues are currently open in the system.
.It Bq Er ENOENT
.Dv O_CREAT
is not set and the named message queue does not exist.
.It Bq Er ENOSPC
There is insufficient space for the creation of the new message queue.
.El
.Sh SEE ALSO
.Xr mq_close 2 ,
.Xr mq_getattr 2 ,
.Xr mq_receive 2 ,
.Xr mq_send 2 ,
.Xr mq_setattr 2 ,
.Xr mq_timedreceive 3 ,
.Xr mq_timedsend 3
.Xr mq_unlink 3
.Sh STANDARDS
The
.Fn mq_open
system call conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .
.Sh BUGS
This implementation places strict requirements on the value of
.Fa name :
it must begin with a slash
.Pq Ql / ,
contain no other slash characters.

190
lib/libc/sys/mq_receive.2 Normal file
View file

@ -0,0 +1,190 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_SEND 2
.Os
.Sh NAME
.Nm mq_receive , mq_timedreceive
.Nd "receive a message from message queue (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In mqueue.h
.Ft ssize_t
.Fo mq_receive
.Fa "mqd_t mqdes"
.Fa "char *msg_ptr"
.Fa "size_t msg_len"
.Fa "unsigned *msg_prio"
.Fc
.Ft ssize_t
.Fo mq_timereceive
.Fa "mqd_t mqdes"
.Fa "char *msg_ptr"
.Fa "size_t msg_len"
.Fa "unsigned *msg_prio"
.Fa "const struct timespec *abs_timeout"
.Fc
.Sh DESCRIPTION
The
.Fn mq_receive
syscall receives oldest of the highest priority message(s) from the
message queue specified by
.Fa mqdes .
If the size of the buffer in bytes, specified by the
.Fa msg_len
argument, is less than the
.Fa mq_msgsize
attribute of the message queue, the syscall will fail and return an
error. Otherwise, the selected message will be removed from the queue
and copied to the buffer pointed to by the
.Fa msg_ptr
argument.
.Pp
If the value of
.Fa msg_len
is greater than
.Brq Dv SSIZE_MAX ,
the result is implementation-defined.
.Pp
If the argument
.Fa msg_prio
is not NULL, the priority of the selected message will be stored in the
location referenced by
.Fa msg_prio .
If the specified message queue is empty and
.Dv O_NONBLOCK
is not set in the message queue description associated with
.Fa mqdes ,
.Fn mq_receive
will block until a message is enqueued on the message queue or until
.Fn mq_receive
is interrupted by a signal. If more than one thread is waiting to receive
a message when a message arrives at an empty queue and the Priority
Scheduling option is supported, then the thread of highest priority that
has been waiting the longest will be selected to receive the message.
Otherwise, it is unspecified which waiting thread receives the message.
If the specified message queue is empty and
.Dv O_NONBLOCK
is set in the message queue description associated with mqdes, no message
will be removed from the queue, and
.Fn mq_receive
will return an error.
.Pp
The
.Fn mq_timedreceive
syscall will receive the oldest of the highest priority messages from the
message queue specified by
.Fa mqdes
as described for the
.Fn mq_receive
syscall. However, if
.Dv O_NONBLOCK
was not specified when the message queue was opened via the
.Fn mq_open
syscall, and no message exists on the queue to satisfy the receive, the wait
for such a message will be terminated when the specified timeout expires. If
.Dv O_NONBLOCK
is set, this syscall is equivalent to
.Fn mq_receive .
.Pp
The timeout expires 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 timeout is based on the CLOCK_REALTIME clock.
.Pp
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_receive
and
.Fn mq_timedreceive
syscalls return the length of the selected message in bytes and the
message is removed from the queue. Otherwise, no message is removed
from the queue, the syscalls returns a value of -1, and set
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_receive
and
.Fn mq_timedreceive
system calls
will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
.Dv O_NONBLOCK
flag is set in the message queue description associated with
.Fa mqdes ,
and the specified message queue is empty.
.It Bq Er EBADF
The
.Fa mqdes
argument is not a valid message queue descriptor open for reading.
.It Bq Er EMSGSIZE
The specified message buffer size,
.Fa msg_len ,
is less than the message size attribute of the message queue.
.It Bq Er EINTR
The
.Fn mq_receive
or
.Fn mq_timedreceive
operation was interrupted by a signal.
.It Bq Er EINVAL
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 ETIMEDOUT
The
.Dv O_NONBLOCK
flag was not set when the message queue was opened, but no message arrived
on the queue before the specified timeout expired.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_timesend 2
.Sh STANDARDS
The
.Fn mq_receive
and
.Fn mq_timereceive
system calls conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .

204
lib/libc/sys/mq_send.2 Normal file
View file

@ -0,0 +1,204 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_SEND 2
.Os
.Sh NAME
.Nm mq_send , mq_timedsend
.Nd "send a message to message queue (REALTIME)"
.Sh LIBRARY
.Lb libc
.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
.Ft int
.Fo mq_timesend
.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
syscall adds 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
should 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
will behave 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
should 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
will block 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 and
the Priority Scheduling option is supported, then the thread of the
highest priority that has been waiting the longest will be unblocked
to send its message. Otherwise, it is unspecified which waiting thread
is unblocked. 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
syscall will add a message to the message queue specified by
.Fa mqdes
in the manner defined for the
.Fn mq_send
syscall. 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 syscall is
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 timeout is based on the CLOCK_REALTIME clock.
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_send
and
.Fn mq_timedsend
syscalls return a value of zero. Otherwise, no message will be
enqueued, the syscalls returns -1, and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn mq_send
and
.Fn mq_timedsend
system calls
will 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.
.It Bq Er EINVAL
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_open 2 ,
.Xr mq_receive 2 ,
.Xr mq_setattr 2 ,
.Xr mq_timereceive 2
.Sh STANDARDS
The
.Fn mq_send
and
.Fn mq_timesend
system calls conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .

104
lib/libc/sys/mq_setattr.2 Normal file
View file

@ -0,0 +1,104 @@
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_CLOSE 2
.Os
.Sh NAME
.Nm mq_setattr
.Nd "set message queue attributes (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In mqueue.h
.Ft int
.Fo mq_setattr
.Fa "mqd_t mqdes"
.Fa "struct mq_attr *restrict mqstat"
.Fa "struct mq_attr *restrict omqstat"
.Fc
.Sh DESCRIPTION
The
.Fn mq_setattr
syscall sets attributes associated with the open message queue description
referenced by the message queue descriptor specified by
.Fa mqdes .
The message queue attributes corresponding to the following members defined
in the
.Vt mq_attr
structure will be set to the specified values upon successful completion of
.Fn mq_setattr :
.Pp
.Bl -tag -width Er
.It Va mq_flags
The value of this member is the bitwise-logical OR of zero or more of
.Dv O_NONBLOCK
and any implementation-defined flags.
.El
.Pp
The values of the
.Va mq_maxmsg ,
.Va mq_msgsize ,
and
.Va mq_curmsgs
embers of the
.Vt mq_attr
structure are ignored by
.Fn mq_setattr .
.Sh RETURN VALUES
Upon successful completion, the function returns a value of zero and the
attributes of the message queue will have been changed as specified.
.Pp
Otherwise, the message queue attributes are unchanged, and the function
returns a value of -1 and set
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_setattr
syscall call
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa mqdes
argument is not a valid message queue descriptor.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_timedsend 2 ,
.Sh STANDARDS
The
.Fn mq_setattr
system call conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
.Fx 7.0 .