Date: Fri, 30 Nov 2012 19:38:35 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Pawel Jakub Dawidek <pjd@FreeBSD.org> Cc: Robert Watson <rwatson@FreeBSD.org>, freebsd-arch@FreeBSD.org Subject: Re: Print a (rate-limited) warning when UMA zone is full. Message-ID: <20121130185557.I2742@besplex.bde.org> In-Reply-To: <20121130073208.GA1409@garage.freebsd.pl> References: <20121129090147.GB1370@garage.freebsd.pl> <alpine.BSF.2.00.1211291027430.59662@fledge.watson.org> <20121130084954.Q1018@besplex.bde.org> <20121130073208.GA1409@garage.freebsd.pl>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, 30 Nov 2012, Pawel Jakub Dawidek wrote:
> On Fri, Nov 30, 2012 at 09:53:41AM +1100, Bruce Evans wrote:
>>>> When UMA zone is created, one can add configure a warning that should be
>>>> printed when UMA zone is full by calling:
>>>>
>>>> uma_zone_set_warning(socket_zone,
>>>> "kern.ipc.maxsockets limit exceeded, please see tuning(7).");
>>
>> Please don't clone messages of this form. It has bad grammar, bad
>> style and a garbage pointer. Many of these were cloned from previous
>> messages of this form.
>>
>> Bad grammar:
>> 1. Redundant "limit". kern.ipc.maxsockets is already a limit.
>
> I don't think I can agree here. kern.ipc.maxsockets is not only a limit
> - it is a string, a sysctl, a tunable... being specific that we are
> talking about kern.ipc.maxsockets limit is a good thing, IMHO.
There is nothing to disagree on -- this is a matter of fact. If the
sysctl were named kern.ipc.limitsockets ("limit" instead of "max")
or just "limit", then the redundancy would be even clearer and uglier.
>> 2. Wrong object. The thing not being exceeded is the number of sockets,
>> not the limit on the number of sockets.
>> 3. Wrong verb. It is impossible to exceed an enforcible, enforced limit
>> This seems hard to fix without making the message too verbose. A full
>> description would say something to the effect that that the limit would
>> be exeeded if exceeding it were possible and permitted. Or some
>> conventional wording for this situation could be used. The above has
>> conventional wording, but has too many errors for me.
>
> I agree 'exceeded' is wrong word here, I copied the message from
> kern.maxfiles warning, but really the messages in the patch were just
> examples how the new function can be used.
>
> How about this:
>
> The kern.ipc.maxsockets limit has be reached.
>
> The message is short. It tells what to tune. It gives sysctl name, so
> hopefully sysctl description will tell more about this limit. I'm not a
> native English speaker, so I'm open to other suggestions of course.
"has be reached" should be "has been reached", which sounds too formal
and verbose to me. It has a complicated tense, so it may be especially
difficult for non-native English speakers.
Further fixes to the kern.ipc.maxpipekva message (change "exceeded" to
"reached" and remove the reference to tuning(7)) and copying them here
gives:
kern.ipc.maxsockets reached
If you want to use "limit" and have perfect grammar, then correct use
would be:
The limit on the number of sockets (kern.ipc.maxsockets) [has been] reached.
This is too verbose for me.
>> 6. termination with a ".'. Error messages are conventionally not terminated
>
> We probably won't reach an agreement here. In my opinion every sentence
> should be terminated with a period. Also it is a warning not an error
> message.
Again, there is nothing to disagree on. It is a fact that error messages
and sysctl descriptions are conventionally not terminated with a "." in
BSD. This at least saves space. For error messages, it avoids some
technical problems. The perror(), err() and warn() APIs append a colon,
a space, strerror(errno) (except for perror(NULL), and a newline. Any
termination of the application's string by a "." would give the garbage
punctuation ".:" after the colon is appended. These APIs never append
a "." after strerror(errno). This is a major source of unterminated error
messages.
If you insist on the ".", then I will insist on perfect grammar (within
space constraints), including when something adds a prefix or a suffix :-).
Perfect grammar is difficult using the err() family, and terminating
with a "." is impossible for err() and warn(). You would have to subvert
the API and use errx() and warnx() with %s and strerror(errno) to get
enough control over the output to just terminate it with a ".".
Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121130185557.I2742>