Re: [patch 1/3] kmsg: Kernel message catalog macros.

[Joe Perches <joe@perches.com>]

On Sun, 2008-08-10 at 02:08 +0200, Martin Schwidefsky wrote:
> On Thu, 2008-08-07 at 08:59 -0700, Joe Perches wrote:
> > On Thu, 2008-08-07 at 10:31 +0200, Martin Schwidefsky wrote:
> > > 1) The message tag is for the user of the system. If it does not have a
> > > fixed position it gets confusing.
> > I think the message tag today is not useful for a user.
> > It seems a barely useful maintainer value.
> > Perhaps the message tag allows for run-time language
> > translation and maybe a bit better selective logging.
> Aehhm, .. what ? If a user does not understand a message directly
> how can he NOT be interested in the kmsg tag? As a random example
> consider the situation when the user gets the message
> 
> 	monwriter.1: Writing monitor data failed with rc=5
> 
> Usually a user will go "Huh?" except if he is a z/VM expert. Looking
> at the source code won't help too much either:
> 
> static int monwrite_diag(struct monwrite_hdr *myhdr, char *buffer, int fcn)
> {
>         struct appldata_product_id id;
>         int rc;
> 
>         strcpy(id.prod_nr, "LNXAPPL");
>         id.prod_fn = myhdr->applid;
>         id.record_nr = myhdr->record_num;
>         id.version_nr = myhdr->version;
>         id.release_nr = myhdr->release;
>         id.mod_lvl = myhdr->mod_level;
>         rc = appldata_asm(&id, fcn, (void *) buffer, myhdr->datalen);
>         if (rc <= 0)
>                 return rc;
>         if (rc == 5)
>                 return -EPERM;
>         kmsg_err(1,"Writing monitor data failed with rc=%i\n", rc);
>         return -EINVAL;
> }
> 
> What the user should do is to cut-copy-paste the kmsg tag monwriter.1
> and pass it to man:
> 
> # man monwriter.1
> 
> What the user will then get is the man page that has been generated
> from the kmsg comment with "make D=2":
> 
> --- snip
> monwriter.1(9)                                                  monwriter.1(9)
> 
> Message
>        monwriter.1: Writing monitor data failed with rc=%i
> 
> Severity
>        Error
> 
> Parameters
>        @1: return code
> 
> Description
>        The  monitor  stream  application  device driver used the z/VM diagnose
>        call DIAG X'DC' to start writing monitor data. z/VM returned  an  error
>        and  the  monitor data cannot be written. If the return code is 5, your
>        z/VM guest virtual machine is not authorized to write monitor data.
> 
> User action
>        If the return code is 5, ensure that your z/VM guest virtual  machine's
>        entry in the z/VM directory includes the OPTION APPLMON statement.  For
>        other return codes see the section about DIAGNOSE Code X'DC'  in  "z/VM
>        CP Programming Services".

Doesn't this example better illustrate the barely useful
user value of such a message and documentation?

In your example, monwriter.1 with a return code of 5 isn't possible.