d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix lots of markup and content bug.

Browse Source 
Submitted by: ru
This commit is contained in:
David Xu 2005-12-03 01:34:41 +00:00
parent b09abb4b2c
commit 951ac754b9
7 changed files with 201 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
lib/libc/sys/mq_close.2
View File

@ -42,9 +42,10 @@
.Sh DESCRIPTION
The
.Fn mq_close
system call removes the association between the message queue descriptor,
system call removes the association between the message queue descriptor,
.Fa mqdes ,
and its message queue. The results of using this message queue descriptor
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
@ -57,12 +58,7 @@ message queue via this
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
system call returns a value of zero; otherwise, the system call returns a
value of -1 and set
.Va errno
to indicate the error.
.Rv -std
.Sh ERRORS
The
.Fn mq_close
@ -80,8 +76,10 @@ argument is not a valid message queue descriptor.
.Sh STANDARDS
The
.Fn mq_close
system call conform to
system call conforms to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues first appeared in
.Fx 7.0 .

34
lib/libc/sys/mq_getattr.2
View File

@ -28,7 +28,7 @@
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_CLOSE 2
.Dt MQ_GETATTR 2
.Os
.Sh NAME
.Nm mq_getattr
@ -52,35 +52,33 @@ argument specifies a message queue descriptor.
.Pp
The results are returned in the
.Vt mq_attr
structure referenced by the mqstat argument.
structure referenced by the
.Fa 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.
.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 .
.Va mq_maxmsg , 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
structure referenced by the
.Fa mqstat
argument will be set to the current state
of the message queue:
.Pp
.Bl -tag -width Er
.Bl -tag -width ".Va mq_flags"
.It Va mq_flags
The number of messages currently on the queue.
The number of messages currently on the queue.
.El
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_getattr
system call returns zero. Otherwise, the system call returns -1 and set
.Va errno
to indicate the error.
.Rv -std
.Sh ERRORS
The
.Fn mq_getattr
@ -96,12 +94,14 @@ argument is not a valid message queue descriptor.
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_setattr 2 ,
.Xr mq_timedsend 2 ,
.Xr mq_timedsend 2
.Sh STANDARDS
The
.Fn mq_getattr
system call conform to
system call conforms to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues first appeared in
.Fx 7.0 .

33
lib/libc/sys/mq_notify.2
View File

@ -44,22 +44,28 @@ If the argument notification is not
.Dv NULL ,
this system call 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
queue descriptor,
.Fa mqdes .
The notification specified by the
.Fa 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
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
If
.Fa 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.
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
@ -70,12 +76,7 @@ arriving message will satisfy the appropriate
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
system call returns a value of zero; otherwise, the function returns a value
of -1 and set
.Va errno
to indicate the error.
.Rv -std
.Sh ERRORS
The
.Fn mq_notify
@ -87,7 +88,7 @@ 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.
Process is already registered for notification by the message queue.
.El
.Sh SEE ALSO
.Xr mq_open 2 ,
@ -96,8 +97,10 @@ process is already registered for notification by the message queue.
.Sh STANDARDS
The
.Fn mq_notify
system call conform to
system call conforms to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues first appeared in
.Fx 7.0 .

140
lib/libc/sys/mq_open.2
View File

@ -31,7 +31,7 @@
.Dt MQ_OPEN 2
.Os
.Sh NAME
.Nm mq_open
.Nm mq_open
.Nd "open a message queue (REALTIME)"
.Sh LIBRARY
.Lb libc
@ -42,45 +42,54 @@
.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
system call establishes 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
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
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
that take pathnames as arguments.
The
.Fa name
argument conforms to the construction rules for a pathname. If
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
with the same value of
.Fa name
refers to the same message queue object, as long as that name has not been
removed. If
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
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.
will fail and return an error.
.Pp
A message queue descriptor may be implemented using a file descriptor, in
which case applications can open up to at least
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
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
@ -90,25 +99,28 @@ 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
.Bl -tag -width ".Dv O_NONBLOCK"
.It Dv 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
.It Dv 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
.It Dv 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
@ -119,37 +131,45 @@ for sending messages.
.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:
.Bl -tag -width ".Dv O_NONBLOCK"
.It Dv 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
which is a pointer to an
.Vt mq_attr
structure. If the pathname
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
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
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
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
queue attributes.
If attr is
.Pf non- Dv NULL
and the calling process has the
appropriate privilege on name, the message queue
.Va mq_maxmsg
and
@ -160,11 +180,13 @@ structure referred to by
.Fa attr .
If
.Fa attr
is non-NULL, but the calling process does not have the appropriate privilege
is
.Pf non- Dv 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
.It Dv O_EXCL
If
.Dv O_EXCL
and
@ -172,36 +194,44 @@ and
are set,
.Fn mq_open
will fail if the message queue name exists.
.It Bq Er O_NONBLOCK
.It Dv 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
with
.Va errno
set to
.Er EAGAIN ;
see
.Fn mq_send
.Xr mq_send 2
and
.Fn mq_receive
.Xr mq_receive 2
for details.
.El
.Pp
The
.Fn mq_open
function does not add or remove messages from the queue.
system call does not add or remove messages from the queue.
.Sh NOTES
FreeBSD implements message queue based on file descriptor. The descriptor
.Fx
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
.Xr fork 2 .
The descriptor is closed in a new image after
.Xr exec 3 .
The
.Xr select 2
and
.Fn kevent
.Xr kevent 2
system calls 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
descriptor; otherwise, the function returns
.Po Vt mqd_t Pc Ns \-1
and sets the global variable
.Va errno
to indicate the error.
.Sh ERRORS
@ -214,7 +244,7 @@ will fail if:
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
message queue is denied.
.It Bq Er EEXIST
.Dv O_CREAT
and
@ -232,7 +262,9 @@ function is not supported for the given name.
.Dv O_CREAT
was specified in
.Fa oflag ,
the value of attr is not
the value of
.Fa attr
is not
.Dv NULL ,
and either
.Va mq_maxmsg
@ -243,7 +275,9 @@ was less than or equal to zero.
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
The length of the
.Fa name
argument exceeds
.Brq Dv PATH_MAX
or a pathname component
is longer than
@ -263,19 +297,21 @@ There is insufficient space for the creation of the new message queue.
.Xr mq_send 2 ,
.Xr mq_setattr 2 ,
.Xr mq_timedreceive 3 ,
.Xr mq_timedsend 3
.Xr mq_timedsend 3 ,
.Xr mq_unlink 3
.Sh STANDARDS
The
.Fn mq_open
system call conform to
system call conforms to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues 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.
.Pq Ql /
and contain no other slash characters.

49
lib/libc/sys/mq_receive.2
View File

@ -28,7 +28,7 @@
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_SEND 2
.Dt MQ_RECEIVE 2
.Os
.Sh NAME
.Nm mq_receive , mq_timedreceive
@ -45,7 +45,7 @@
.Fa "unsigned *msg_prio"
.Fc
.Ft ssize_t
.Fo mq_timereceive
.Fo mq_timedreceive
.Fa "mqd_t mqdes"
.Fa "char *msg_ptr"
.Fa "size_t msg_len"
@ -61,14 +61,15 @@ message queue specified by
If the size of the buffer in bytes, specified by the
.Fa msg_len
argument, is less than the
.Fa mq_msgsize
.Va mq_msgsize
attribute of the message queue, the system call will fail and return an
error. Otherwise, the selected message will be removed from the queue
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
If the value of
.Fa msg_len
is greater than
.Brq Dv SSIZE_MAX ,
@ -76,7 +77,9 @@ 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
is not
.Dv 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
@ -86,14 +89,17 @@ is not set in the message queue description associated with
.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
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
is set in the message queue description associated with
.Fa mqdes ,
no message
will be removed from the queue, and
.Fn mq_receive
will return an error.
@ -105,12 +111,14 @@ message queue specified by
.Fa mqdes
as described for the
.Fn mq_receive
system call. However, if
system call.
However, if
.Dv O_NONBLOCK
was not specified when the message queue was opened via the
.Fn mq_open
system call, 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
for such a message will be terminated when the specified timeout expires.
If
.Dv O_NONBLOCK
is set, this system call is equivalent to
.Fn mq_receive .
@ -124,18 +132,21 @@ 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
The timeout is based on the
.Dv CLOCK_REALTIME
clock.
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_receive
and
.Fn mq_timedreceive
system calls 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 system call return a value of -1, and set
message is removed from the queue.
Otherwise, no message is removed
from the queue, the system call returns a value of \-1,
and the global variable
.Va errno
to indicate the error.
is set to indicate the error.
.Sh ERRORS
The
.Fn mq_receive
@ -177,14 +188,16 @@ on the queue before the specified timeout expired.
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_timesend 2
.Xr mq_timedsend 2
.Sh STANDARDS
The
.Fn mq_receive
and
.Fn mq_timereceive
.Fn mq_timedreceive
system calls conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues first appeared in
.Fx 7.0 .

46
lib/libc/sys/mq_send.2
View File

@ -45,7 +45,7 @@
.Fa "unsigned msg_prio"
.Fc
.Ft int
.Fo mq_timesend
.Fo mq_timedsend
.Fa "mqd_t mqdes"
.Fa "const char *msg_ptr"
.Fa "size_t msg_len"
@ -59,14 +59,14 @@ system call adds the message pointed to by the argument
.Fa msg_ptr
to the message queue specified by
.Fa mqdes .
The
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
.Va mq_msgsize
attribute of the message queue, or
.Fn mq_send
will fail.
@ -76,7 +76,8 @@ If the specified message queue is not full,
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
argument.
A message with a larger numeric value of
.Fa msg_prio
will be inserted before messages with lower values of
.Fa msg_prio .
@ -96,12 +97,15 @@ is not set in the message queue description associated with
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
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
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 ,
@ -115,12 +119,14 @@ system call will add a message to the message queue specified by
.Fa mqdes
in the manner defined for the
.Fn mq_send
system call. However, if the specified message queue is full and
system call.
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
the specified timeout expires.
If
.Dv O_NONBLOCK
is set in the message queue description, this system call is
equivalent to
@ -129,20 +135,24 @@ equivalent to
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
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.
The timeout is based on the
.Dv CLOCK_REALTIME
clock.
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_send
and
.Fn mq_timedsend
system calls return a value of zero. Otherwise, no message will be
enqueued, the system calls return -1, and
system calls return a value of zero.
Otherwise, no message will be
enqueued, the system calls return \-1, and
the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
@ -167,7 +177,7 @@ argument is not a valid message queue descriptor open for writing.
A signal interrupted the call to
.Fn mq_send
or
.Fn mq_timedsend.
.Fn mq_timedsend .
.It Bq Er EINVAL
The value of
.Fa msg_prio
@ -191,14 +201,16 @@ expired before the message could be added to the queue.
.Xr mq_open 2 ,
.Xr mq_receive 2 ,
.Xr mq_setattr 2 ,
.Xr mq_timereceive 2
.Xr mq_timedreceive 2
.Sh STANDARDS
The
.Fn mq_send
and
.Fn mq_timesend
.Fn mq_timedsend
system calls conform to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues first appeared in
.Fx 7.0 .

20
lib/libc/sys/mq_setattr.2
View File

@ -28,7 +28,7 @@
.\" $FreeBSD$
.\"
.Dd November 29, 2005
.Dt MQ_CLOSE 2
.Dt MQ_SETATTR 2
.Os
.Sh NAME
.Nm mq_setattr
@ -54,8 +54,7 @@ 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
.Bl -tag -width ".Va mq_flags"
.It Va mq_flags
The value of this member is the bitwise-logical OR of zero or more of
.Dv O_NONBLOCK
@ -63,11 +62,10 @@ and any implementation-defined flags.
.El
.Pp
The values of the
.Va mq_maxmsg ,
.Va mq_msgsize ,
.Va mq_maxmsg , mq_msgsize ,
and
.Va mq_curmsgs
embers of the
members of the
.Vt mq_attr
structure are ignored by
.Fn mq_setattr .
@ -76,7 +74,7 @@ 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
returns a value of \-1 and sets the global variable
.Va errno
to indicate the error.
.Sh ERRORS
@ -93,12 +91,14 @@ argument is not a valid message queue descriptor.
.Sh SEE ALSO
.Xr mq_open 2 ,
.Xr mq_send 2 ,
.Xr mq_timedsend 2 ,
.Xr mq_timedsend 2
.Sh STANDARDS
The
.Fn mq_setattr
system call conform to
system call conforms to
.St -p1003.1-2004 .
.Sh HISTORY
Support for POSIX message queue first appeared in
Support for
.Tn POSIX
message queues first appeared in
.Fx 7.0 .