diff options
author | davidxu <davidxu@FreeBSD.org> | 2005-12-03 01:34:41 +0000 |
---|---|---|
committer | davidxu <davidxu@FreeBSD.org> | 2005-12-03 01:34:41 +0000 |
commit | 0a233aabf5d8dcd5271f5d6035f0d002ca7450ce (patch) | |
tree | 4ea2d93e7ac2b1ffe5c6aa79e399af7e953f75d9 | |
parent | 863654c1a1b78c4955ad3799658ffc6397d2ec6f (diff) | |
download | FreeBSD-src-0a233aabf5d8dcd5271f5d6035f0d002ca7450ce.zip FreeBSD-src-0a233aabf5d8dcd5271f5d6035f0d002ca7450ce.tar.gz |
Fix lots of markup and content bug.
Submitted by: ru
-rw-r--r-- | lib/libc/sys/mq_close.2 | 18 | ||||
-rw-r--r-- | lib/libc/sys/mq_getattr.2 | 34 | ||||
-rw-r--r-- | lib/libc/sys/mq_notify.2 | 33 | ||||
-rw-r--r-- | lib/libc/sys/mq_open.2 | 140 | ||||
-rw-r--r-- | lib/libc/sys/mq_receive.2 | 49 | ||||
-rw-r--r-- | lib/libc/sys/mq_send.2 | 46 | ||||
-rw-r--r-- | lib/libc/sys/mq_setattr.2 | 20 |
7 files changed, 201 insertions, 139 deletions
diff --git a/lib/libc/sys/mq_close.2 b/lib/libc/sys/mq_close.2 index 3f0461c..c2968fb 100644 --- a/lib/libc/sys/mq_close.2 +++ b/lib/libc/sys/mq_close.2 @@ -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 . diff --git a/lib/libc/sys/mq_getattr.2 b/lib/libc/sys/mq_getattr.2 index 72798d2..f34c498 100644 --- a/lib/libc/sys/mq_getattr.2 +++ b/lib/libc/sys/mq_getattr.2 @@ -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 . diff --git a/lib/libc/sys/mq_notify.2 b/lib/libc/sys/mq_notify.2 index cae6e16..f4009e4 100644 --- a/lib/libc/sys/mq_notify.2 +++ b/lib/libc/sys/mq_notify.2 @@ -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 . diff --git a/lib/libc/sys/mq_open.2 b/lib/libc/sys/mq_open.2 index 5d5a3f7..a128e9a 100644 --- a/lib/libc/sys/mq_open.2 +++ b/lib/libc/sys/mq_open.2 @@ -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. diff --git a/lib/libc/sys/mq_receive.2 b/lib/libc/sys/mq_receive.2 index b6dd2cf..2103e09 100644 --- a/lib/libc/sys/mq_receive.2 +++ b/lib/libc/sys/mq_receive.2 @@ -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 . diff --git a/lib/libc/sys/mq_send.2 b/lib/libc/sys/mq_send.2 index c021b89..0d63a40 100644 --- a/lib/libc/sys/mq_send.2 +++ b/lib/libc/sys/mq_send.2 @@ -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 . diff --git a/lib/libc/sys/mq_setattr.2 b/lib/libc/sys/mq_setattr.2 index 21608f9..b50348c 100644 --- a/lib/libc/sys/mq_setattr.2 +++ b/lib/libc/sys/mq_setattr.2 @@ -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 . |