Man page typo

Man page typo

[Mihai Paraschivescu]

Hi!

My name is Mihail Paraschivescu, I'm from Romania. I have a lot of experience under Linux in C/C++ and a few days ago I got a new project related to System V message queues. So I start to document myself about all the things it may involve. While reading the man page of msgsnd(2) function I saw that among other thing it's written that:

"The queue capacity is defined by the msg_bytes field in the associated data structure for the message queue."

If I'm not wrong, the exact name of that field in the msqid_ds structure is msg_qbytes. The same thing appears also on the online manual pages, I checked it already.

I know this is a very minor typo, but I thought that it would be better to fix it such that other coders to get 100% correct information form this man page.

I am using Mandriva Linux 2010 and the man page is "part of release 3.23 of the Linux man-pages project".

Thanks a lot and have a nice day!

Mihail


      
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Man page typo

[Michael Witten]

On Sun, Apr 18, 2010 at 10:57, Mihai Paraschivescu <paraschivescu_mihail-/E1597aS9LQAvxtiuMwx3w@public.gmane.org> wrote:
> If I'm not wrong, the exact name of that field in
> the msqid_ds structure is msg_qbytes. The
> same thing appears also on the online manual
> pages, I checked it already.

You are correct.

The POSIX man pages do indeed list `msg_qbytes' for what seems
like the equivalent concept of what the Linux man page lists as
`msg_bytes'. The glibc header file <sys/msg.h> (specifically
<bits/msq.h>) defines `struct msqid_ds' with not `msg_bytes'
but rather `msg_qbytes'; the field `msg_qbytes' can indeed be
set with `msgctl()' according to glibc's implementation of that
function (see "sysdeps/unix/sysv/linux/i386/msgctl.c" in the
glibc source).

However, the Linux kernel seems to implement this messaging
system on top of a more general IPC subsystem; `MSGMNB' (as
referenced in the Linux man page) is used to set the field
`msg_ctlmnb' of an object of type `struct ipc_namespace'
(http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L115):

    112 void msg_init_ns(struct ipc_namespace *ns)
    113 {
    114         ns->msg_ctlmax = MSGMAX;
    115         ns->msg_ctlmnb = MSGMNB;              /* <------------------- */
    116
    117         recompute_msgmni(ns);
    118
    119         atomic_set(&ns->msg_bytes, 0);        /* see below */
    120         atomic_set(&ns->msg_hdrs, 0);
    121         ipc_init_ids(&ns->ids[IPC_MSG_IDS]);
    122 }

When creating a queue, an object of type `struct
msg_queue' is created, and it's `q_qbytes' field is
set to the associated namespace's `msg_ctlmnb' field
(http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L215):

    181 static int newque(struct ipc_namespace *ns, struct ipc_params *params)
    182 {
    183         struct msg_queue *msq;
    ...
    215         msq->q_qbytes = ns->msg_ctlmnb; /* <------- Essentially assign MSGMNB */
    ...
    223         return msq->q_perm.id;
    224 }

So, it would appear that the Kernel internally uses `q_qbytes'
of a `struct msg_queue' for what POSIX (userland side) considers
`msg_qbytes' of a `struct msqid_ds'.

This is corroborated by how the kernel implements the
`msgctl()' system call to set a queue's maximum byte capacity
(http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L412):

    412 static int msgctl_down(struct ipc_namespace *ns, int msqid, int cmd,
    413                        struct msqid_ds __user *buf, int version)
    414 {
    ...
    416         struct msqid64_ds uninitialized_var(msqid64);
    417         struct msg_queue *msq;
    418         int err;
    419
    420         if (cmd == IPC_SET) {
    421                 if (copy_msqid_from_user(&msqid64, buf, version))   /* Copy from userspace */
    422                         return -EFAULT;
    423         }
    ...
    440         case IPC_SET:
    441                 if (msqid64.msg_qbytes > ns->msg_ctlmnb &&
    442                     !capable(CAP_SYS_RESOURCE)) {
    443                         err = -EPERM;
    444                         goto out_unlock;
    445                 }
    446
    447                 msq->q_qbytes = msqid64.msg_qbytes;                 /* <------- Set here with a copy of input */
    ...
    462         }

So, it's pretty clear that the `q_qbytes' of a `struct msg_queue'
is indeed the kernelspace version of the POSIX `msg_qbytes' of a
`struct msqid_ds'.

So, my question is, what is the `msg_bytes' of
a `struct ipc_namespace'? Here's how it's used
in the kernel's implementation of `msgsnd()'
(http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L712):

    636 long do_msgsnd(int msqid, long mtype, void __user *mtext,
    637                 size_t msgsz, int msgflg)
    638 {
    639         struct msg_queue *msq;
    ...
    641         int err;
    642         struct ipc_namespace *ns;
    643
    644         ns = current->nsproxy->ipc_ns;  /* from current task */
    ...
    708                 /* noone is waiting for this message, enqueue it */
    709                 list_add_tail(&msg->m_list, &msq->q_messages);
    710                 msq->q_cbytes += msgsz;
    711                 msq->q_qnum++;
    712                 atomic_add(msgsz, &ns->msg_bytes);     /* <-------------------- */
    ...
    724         return err;
    725 }

As you can see, `q_qnum' of a `struct msg_queue' corresponds
to the POSIX `msg_qnum' of a `struct msqid_ds'; interestingly,
the kernel also keeps track of the number of message bytes
currently on the queue by using the field `q_cbytes' of a
`struct msg_queue', which corresponds to the "private" field
`__msg_cbytes' that glibc defines as an extension to the standard
POSIX `struct msqid_ds'.

More to the point, it would seem that the `msg_bytes' of a
`struct ipc_namespace' is just the more general IPC namespace
subsystem's personal copy of that byte count, so that whoever
referenced `msg_bytes' in the Linux man page made a mistake in
using it.

My suggestion is that these sentences from the current msgsnd(2):

    The queue capacity is defined by the msg_bytes field
    in the  associated data structure for the message queue.
    During queue creation this field is initialized to MSGMNB
    bytes, but this limit can be modified using msgctl(2).

should remove all references to such implementation details and
instead stick to the user interface:

    The queue capacity can be queried and set using
    msgctl(2) and the msg_qbytes field of its msqid_ds
    pointer parameter.

Mihai, submit a patch for msgsnd(2); checkout the source as
follows:

    git clone git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git

If you don't, I will :-D

Sincerely,
Michael Witten
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] msgsnd(2): msg_bytes -> msg_qbytes

[Michael Witten]

Mihail Paraschivescu <paraschivescu_mihail-/E1597aS9LQAvxtiuMwx3w@public.gmane.org> reported
here:

    http://marc.info/?l=linux-man&m=127160667709342&w=2
    http://www.spinics.net/lists/linux-man/msg01271.html

the following:

    "The queue capacity is defined by the msg_bytes field in
    the associated data structure for the message queue."

    If I'm not wrong, the exact name of that field in the
    msqid_ds structure is msg_qbytes. The same thing appears
    also on the online [POSIX] manual pages, I checked it
    already.

I provided a detailed confirmation with quotes from the
Linux kernel sources:

    http://marc.info/?l=linux-man&m=127181601631737&w=2
    http://www.spinics.net/lists/linux-man/msg01273.html

This patch (requested by Mihail) makes the correction and
removes unnecessary implementation details.
---
 man2/msgop.2 |   16 ++++++++--------
 1 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/man2/msgop.2 b/man2/msgop.2
index 2b29cac..f236c5a 100644
--- a/man2/msgop.2
+++ b/man2/msgop.2
@@ -102,14 +102,14 @@ by
 .PP
 If sufficient space is available in the queue,
 .BR msgsnd ()
-succeeds immediately.
+succeeds immediately;
-(The queue capacity is defined by the
-.I msg_bytes
-field in the associated data structure for the message queue.
-During queue creation this field is initialized to
-.B MSGMNB
-bytes, but this limit can be modified using
-.BR msgctl (2).)
+the queue capacity can be queried and set via
+.BR msgctl (2)
+by using the
+.I msg_qbytes
+field of that function's
+.I msqid_ds
+pointer parameter.
 If insufficient space is available in the queue, then the default
 behavior of
 .BR msgsnd ()
-- 
1.7.1

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] msgsnd(2): msg_bytes -> msg_qbytes

[Michael Kerrisk]

On Thu, Apr 29, 2010 at 1:59 AM, Michael Witten <mfwitten-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Mihail Paraschivescu <paraschivescu_mihail-/E1597aS9LQAvxtiuMwx3w@public.gmane.org> reported
> here:
>
>    http://marc.info/?l=linux-man&m=127160667709342&w=2
>    http://www.spinics.net/lists/linux-man/msg01271.html
>
> the following:
>
>    "The queue capacity is defined by the msg_bytes field in
>    the associated data structure for the message queue."
>
>    If I'm not wrong, the exact name of that field in the
>    msqid_ds structure is msg_qbytes. The same thing appears
>    also on the online [POSIX] manual pages, I checked it
>    already.
>
> I provided a detailed confirmation with quotes from the
> Linux kernel sources:
>
>    http://marc.info/?l=linux-man&m=127181601631737&w=2
>    http://www.spinics.net/lists/linux-man/msg01273.html
>
> This patch (requested by Mihail) makes the correction and
> removes unnecessary implementation details.

Michael, thanks for this patch, but see my notes in the thread:

Subject: Re: Man page typo
To: Michael Witten <mfwitten-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Cc: Mihai Paraschivescu <paraschivescu_mihail-/E1597aS9LQAvxtiuMwx3w@public.gmane.org>,
linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org

I don't think this patch is needed (other than the part that fixes the
file names).

Cheers,

Michael

> ---
>  man2/msgop.2 |   16 ++++++++--------
>  1 files changed, 8 insertions(+), 8 deletions(-)
>
> diff --git a/man2/msgop.2 b/man2/msgop.2
> index 2b29cac..f236c5a 100644
> --- a/man2/msgop.2
> +++ b/man2/msgop.2
> @@ -102,14 +102,14 @@ by
>  .PP
>  If sufficient space is available in the queue,
>  .BR msgsnd ()
> -succeeds immediately.
> +succeeds immediately;
> -(The queue capacity is defined by the
> -.I msg_bytes
> -field in the associated data structure for the message queue.
> -During queue creation this field is initialized to
> -.B MSGMNB
> -bytes, but this limit can be modified using
> -.BR msgctl (2).)
> +the queue capacity can be queried and set via
> +.BR msgctl (2)
> +by using the
> +.I msg_qbytes
> +field of that function's
> +.I msqid_ds
> +pointer parameter.
>  If insufficient space is available in the queue, then the default
>  behavior of
>  .BR msgsnd ()
> --
> 1.7.1
>
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Man page typo

[Michael Kerrisk]

Mihai, Michael,

On Wed, Apr 21, 2010 at 4:13 AM, Michael Witten <mfwitten-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On Sun, Apr 18, 2010 at 10:57, Mihai Paraschivescu <paraschivescu_mihail-/E1597aS9LQAvxtiuMwx3w@public.gmane.org> wrote:
>> If I'm not wrong, the exact name of that field in
>> the msqid_ds structure is msg_qbytes. The
>> same thing appears also on the online manual
>> pages, I checked it already.

I have corrected this in the man page (for 3.25).

> You are correct.
>
> The POSIX man pages do indeed list `msg_qbytes' for what seems
> like the equivalent concept of what the Linux man page lists as
> `msg_bytes'. The glibc header file <sys/msg.h> (specifically
> <bits/msq.h>) defines `struct msqid_ds' with not `msg_bytes'
> but rather `msg_qbytes'; the field `msg_qbytes' can indeed be
> set with `msgctl()' according to glibc's implementation of that
> function (see "sysdeps/unix/sysv/linux/i386/msgctl.c" in the
> glibc source).
>
> However, the Linux kernel seems to implement this messaging
> system on top of a more general IPC subsystem; `MSGMNB' (as
> referenced in the Linux man page) is used to set the field
> `msg_ctlmnb' of an object of type `struct ipc_namespace'
> (http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L115):
>
>    112 void msg_init_ns(struct ipc_namespace *ns)
>    113 {
>    114         ns->msg_ctlmax = MSGMAX;
>    115         ns->msg_ctlmnb = MSGMNB;              /* <------------------- */
>    116
>    117         recompute_msgmni(ns);
>    118
>    119         atomic_set(&ns->msg_bytes, 0);        /* see below */
>    120         atomic_set(&ns->msg_hdrs, 0);
>    121         ipc_init_ids(&ns->ids[IPC_MSG_IDS]);
>    122 }
>
> When creating a queue, an object of type `struct
> msg_queue' is created, and it's `q_qbytes' field is
> set to the associated namespace's `msg_ctlmnb' field
> (http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L215):
>
>    181 static int newque(struct ipc_namespace *ns, struct ipc_params *params)
>    182 {
>    183         struct msg_queue *msq;
>    ...
>    215         msq->q_qbytes = ns->msg_ctlmnb; /* <------- Essentially assign MSGMNB */
>    ...
>    223         return msq->q_perm.id;
>    224 }
>
> So, it would appear that the Kernel internally uses `q_qbytes'
> of a `struct msg_queue' for what POSIX (userland side) considers
> `msg_qbytes' of a `struct msqid_ds'.
>
> This is corroborated by how the kernel implements the
> `msgctl()' system call to set a queue's maximum byte capacity
> (http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L412):
>
>    412 static int msgctl_down(struct ipc_namespace *ns, int msqid, int cmd,
>    413                        struct msqid_ds __user *buf, int version)
>    414 {
>    ...
>    416         struct msqid64_ds uninitialized_var(msqid64);
>    417         struct msg_queue *msq;
>    418         int err;
>    419
>    420         if (cmd == IPC_SET) {
>    421                 if (copy_msqid_from_user(&msqid64, buf, version))   /* Copy from userspace */
>    422                         return -EFAULT;
>    423         }
>    ...
>    440         case IPC_SET:
>    441                 if (msqid64.msg_qbytes > ns->msg_ctlmnb &&
>    442                     !capable(CAP_SYS_RESOURCE)) {
>    443                         err = -EPERM;
>    444                         goto out_unlock;
>    445                 }
>    446
>    447                 msq->q_qbytes = msqid64.msg_qbytes;                 /* <------- Set here with a copy of input */
>    ...
>    462         }
>
> So, it's pretty clear that the `q_qbytes' of a `struct msg_queue'
> is indeed the kernelspace version of the POSIX `msg_qbytes' of a
> `struct msqid_ds'.
>
> So, my question is, what is the `msg_bytes' of
> a `struct ipc_namespace'? Here's how it's used
> in the kernel's implementation of `msgsnd()'
> (http://lxr.linux.no/#linux+v2.6.33/ipc/msg.c#L712):
>
>    636 long do_msgsnd(int msqid, long mtype, void __user *mtext,
>    637                 size_t msgsz, int msgflg)
>    638 {
>    639         struct msg_queue *msq;
>    ...
>    641         int err;
>    642         struct ipc_namespace *ns;
>    643
>    644         ns = current->nsproxy->ipc_ns;  /* from current task */
>    ...
>    708                 /* noone is waiting for this message, enqueue it */
>    709                 list_add_tail(&msg->m_list, &msq->q_messages);
>    710                 msq->q_cbytes += msgsz;
>    711                 msq->q_qnum++;
>    712                 atomic_add(msgsz, &ns->msg_bytes);     /* <-------------------- */
>    ...
>    724         return err;
>    725 }
>
> As you can see, `q_qnum' of a `struct msg_queue' corresponds
> to the POSIX `msg_qnum' of a `struct msqid_ds'; interestingly,
> the kernel also keeps track of the number of message bytes
> currently on the queue by using the field `q_cbytes' of a
> `struct msg_queue', which corresponds to the "private" field
> `__msg_cbytes' that glibc defines as an extension to the standard
> POSIX `struct msqid_ds'.
>
> More to the point, it would seem that the `msg_bytes' of a
> `struct ipc_namespace' is just the more general IPC namespace
> subsystem's personal copy of that byte count, so that whoever
> referenced `msg_bytes' in the Linux man page made a mistake in
> using it.
>
> My suggestion is that these sentences from the current msgsnd(2):
>
>    The queue capacity is defined by the msg_bytes field
>    in the  associated data structure for the message queue.
>    During queue creation this field is initialized to MSGMNB
>    bytes, but this limit can be modified using msgctl(2).
>
> should remove all references to such implementation details and
> instead stick to the user interface:
>
>    The queue capacity can be queried and set using
>    msgctl(2) and the msg_qbytes field of its msqid_ds
>    pointer parameter.

Michael, your analysis of the code is detailed, but the pieces that
you describe as implementation details are either actually important
userspace details. Associated data" is a general concept for SVIPC,
and MSGMNB is a user visible limit (that can be modified vua /proc).

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html