From per@hedeland.org  Sun Feb  9 16:29:46 2003
Return-Path: <per@hedeland.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 209CF37B401
	for <FreeBSD-gnats-submit@freebsd.org>; Sun,  9 Feb 2003 16:29:46 -0800 (PST)
Received: from pluto.hedeland.org (as1-2-8.mal.s.bonet.se [194.236.4.19])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 64B0643F3F
	for <FreeBSD-gnats-submit@freebsd.org>; Sun,  9 Feb 2003 16:29:44 -0800 (PST)
	(envelope-from per@hedeland.org)
Received: from pluto.hedeland.org (localhost [127.0.0.1])
	by pluto.hedeland.org (8.12.6/8.12.6) with ESMTP id h1A0Tfpg009784
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 10 Feb 2003 01:29:41 +0100 (CET)
	(envelope-from per@pluto.hedeland.org)
Received: (from per@localhost)
	by pluto.hedeland.org (8.12.6/8.12.6/Submit) id h1A0TeaI009783;
	Mon, 10 Feb 2003 01:29:40 +0100 (CET)
Message-Id: <200302100029.h1A0TeaI009783@pluto.hedeland.org>
Date: Mon, 10 Feb 2003 01:29:40 +0100 (CET)
From: Per Hedeland <per@hedeland.org>
Reply-To: Per Hedeland <per@hedeland.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] Incorrect errno strings in intro(2)
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         48125
>Category:       docs
>Synopsis:       [PATCH] Incorrect errno strings in intro(2)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Feb 09 16:30:13 PST 2003
>Closed-Date:    Sun Feb 23 17:22:30 PST 2003
>Last-Modified:  Sun Feb 23 17:22:30 PST 2003
>Originator:     Per Hedeland
>Release:        FreeBSD 5.0-RELEASE i386
>Organization:
None
>Environment:
System: FreeBSD pluto.hedeland.org 5.0-RELEASE FreeBSD 5.0-RELEASE #6: Sun Feb 9 19:32:16 CET 2003 per@pluto.hedeland.org:/usr/src/sys/i386/compile/PLUTO i386


>Description:
	Several of the strings given in intro(2) a.k.a. 'man errno' do
	not agree with what is actually output by programs using
	perror() etc, making problem resolution unnecessarily difficult.
>How-To-Repeat:
	Do something that generates the error message "Device not
	configured." Try to find the corresponding errno value and
	explanation via 'man errno', and fail. Grep errlst.c while
	muttering the L-word.
>Fix:

	Apply patch below against 

        $FreeBSD: src/lib/libc/sys/intro.2,v 1.36 2002/12/12 17:25:53 ru Exp $


--- /usr/src/lib/libc/sys/intro.2.ORIG	Thu Dec 12 18:25:53 2002
+++ /usr/src/lib/libc/sys/intro.2	Mon Feb 10 01:06:23 2003
@@ -90,7 +90,7 @@
 names as given in
 .Aq Pa sys/errno.h .
 .Bl -hang -width Ds
-.It Er 0 Em "Error 0" .
+.It Er 0 Em "Undefined error: 0" .
 Not used.
 .It Er 1 EPERM Em "Operation not permitted" .
 An attempt was made to perform an operation limited to processes
@@ -102,7 +102,7 @@
 .It Er 3 ESRCH Em "No such process" .
 No process could be found corresponding to that specified by the given
 process ID.
-.It Er 4 EINTR Em "Interrupted function call" .
+.It Er 4 EINTR Em "Interrupted system call" .
 An asynchronous signal (such as
 .Dv SIGINT
 or
@@ -115,14 +115,14 @@
 Some physical input or output error occurred.
 This error will not be reported until a subsequent operation on the same file
 descriptor and may be lost (over written) by any subsequent errors.
-.It Er 6 ENXIO Em "\&No such device or address" .
+.It Er 6 ENXIO Em "Device not configured" .
 Input or output on a special file referred to a device that did not
 exist, or
 made a request beyond the limits of the device.
 This error may also occur when, for example,
 a tape drive is not online or no disk pack is
 loaded on a drive.
-.It Er 7 E2BIG Em "Arg list too long" .
+.It Er 7 E2BIG Em "Argument list too long" .
 The number of bytes used for the argument and environment
 list of the new process exceeded the current limit
 of 65536 bytes
@@ -161,9 +161,9 @@
 .It Er 14 EFAULT Em "Bad address" .
 The system detected an invalid address in attempting to
 use an argument of a call.
-.It Er 15 ENOTBLK Em "Not a block device" .
+.It Er 15 ENOTBLK Em "Block device required" .
 A block device operation was attempted on a non-block device or file.
-.It Er 16 EBUSY Em "Resource busy" .
+.It Er 16 EBUSY Em "Device busy" .
 An attempt to use a system resource which was in use at the time
 in a manner which would have conflicted with the request.
 .It Er 17 EEXIST Em "File exists" .
@@ -171,7 +171,7 @@
 for instance, as the new link name in a
 .Xr link 2
 function.
-.It Er 18 EXDEV Em "Improper link" .
+.It Er 18 EXDEV Em "Cross-device link" .
 A hard link to a file on another file system
 was attempted.
 .It Er 19 ENODEV Em "Operation not supported by device" .
@@ -218,7 +218,7 @@
 .if t 2\u\s-231\s+2\d
 .if n 2.1E9
 bytes).
-.It Er 28 ENOSPC Em "Device out of space" .
+.It Er 28 ENOSPC Em "No space left on device" .
 A
 .Xr write 2
 to an ordinary file, the creation of a
@@ -246,7 +246,7 @@
 .It Er 33 EDOM Em "Numerical argument out of domain" .
 A numerical input argument was outside the defined domain of the mathematical
 function.
-.It Er 34 ERANGE Em "Numerical result out of range" .
+.It Er 34 ERANGE Em "Result too large" .
 A numerical result of the function was too large to fit in the
 available space (perhaps exceeded precision).
 .It Er 35 EAGAIN Em "Resource temporarily unavailable" .
@@ -309,7 +309,7 @@
 .It Er 48 EADDRINUSE Em "Address already in use" .
 Only one usage of each address is normally permitted.
 .Pp
-.It Er 49 EADDRNOTAVAIL Em "Cannot assign requested address" .
+.It Er 49 EADDRNOTAVAIL Em "Can't assign requested address" .
 Normally results from an attempt to create a socket with an
 address not on this machine.
 .It Er 50 ENETDOWN Em "Network is down" .
@@ -341,7 +341,7 @@
 An request to send or receive data was disallowed because
 the socket was not connected and (when sending on a datagram socket)
 no address was supplied.
-.It Er 58 ESHUTDOWN Em "Cannot send after socket shutdown" .
+.It Er 58 ESHUTDOWN Em "Can't send after socket shutdown" .
 A request to send data was disallowed because the socket
 had already been shut down with a previous
 .Xr shutdown 2



>Release-Note:
>Audit-Trail:

From: Tom Rhodes <trhodes@FreeBSD.org>
To: FreeBSD-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/48125: [COMMENTS] to your extremely useful patch
Date: Tue, 11 Feb 2003 14:52:45 -0500

 I really like everything you've done here, thanks alot for the time
 you have spent.  However I have but one comment.  :)
 
 
 -.It Er 49 EADDRNOTAVAIL Em "Cannot assign requested address" .
 +.It Er 49 EADDRNOTAVAIL Em "Can't assign requested address" .
  Normally results from an attempt to create a socket with an
  address not on this machine.
  .It Er 50 ENETDOWN Em "Network is down" .
 @@ -341,7 +341,7 @@
  An request to send or receive data was disallowed because
  the socket was not connected and (when sending on a datagram socket)
  no address was supplied.
 -.It Er 58 ESHUTDOWN Em "Cannot send after socket shutdown" .
 +.It Er 58 ESHUTDOWN Em "Can't send after socket shutdown" .
  A request to send data was disallowed because the socket
  had already been shut down with a previous
  .Xr shutdown 2
 
 In both of these hunks we are using contractions, something we
 have tried to avoid completely in the doc project.  Personally,
 this is one time I would like the code to be customed to the
 manual page.  In other words, I would like the output errors
 to be changed to match the manual page instead of the other
 way around.
 
 I can do this sometime soon, however if you have a patch I can
 do it sooner :)
 
 --
 Tom Rhodes

From: Per Hedeland <per@hedeland.org>
To: freebsd-gnats-submit@FreeBSD.org, per@hedeland.org
Cc:  
Subject: Re: docs/48125: [PATCH] Incorrect errno strings in intro(2)
Date: Sun, 16 Feb 2003 22:25:21 +0100

 Well, I'm glad you appreciated it, but it really wasn't a major effort
 or anything - mostly just a bit of awk'ing on the respective sources.:-)
 
 However, regarding the contractions: I can see where you're coming from,
 since I gather that using them in "formal" documents is frowned upon -
 but I must really strongly disagree with your suggestion to change the
 code! The output of programs should not be changed for such "frivolous"
 reasons - e.g. there may well be scripts etc out there that, however
 unwisely, rely on the exact format of error messages to function
 correctly. Not to mention that using contractions in error messages is a
 long-standing Unix tradition, even in cases where the message doesn't
 originate in sys_errlist.
 
 I'd suggest that either you consider these strings to not be part of the
 actual "document text" (which would be correct I think), and thereby
 exempt from considerations of "good writing style" - or if that isn't
 acceptable, leave the "Cannot"s in the man page and the "Can't"s in the
 code - this discrepancy shouldn't matter *too* much to the reader, who
 is unlikely to be searching the man page for "Can't" anyway...
 
 --Per Hedeland
 
 

From: Tom Rhodes <trhodes@FreeBSD.org>
To: Per Hedeland <per@hedeland.org>
Cc: freebsd-doc@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.org,
	Greg Lehey <grog@FreeBSD.org>, Bruce Evans <bde@FreeBSD.org>
Subject: Re: docs/48125: [PATCH] Incorrect errno strings in intro(2)
Date: Sun, 16 Feb 2003 17:43:34 -0500

 On Sun, 16 Feb 2003 13:30:16 -0800 (PST)
 Per Hedeland <per@hedeland.org> wrote:
 
 >  However, regarding the contractions: I can see where you're coming
 >  from, since I gather that using them in "formal" documents is frowned
 >  upon -
 
 True,
 
 >  but I must really strongly disagree with your suggestion to change
 >  the code! The output of programs should not be changed for such
 >  "frivolous" reasons - e.g. there may well be scripts etc out there
 >  that, however unwisely, rely on the exact format of error messages to
 >  function correctly. Not to mention that using contractions in error
 >  messages is a long-standing Unix tradition, even in cases where the
 >  message doesn't originate in sys_errlist.
 
 however to my knowledge when Bell Labs originally started producing
 UNIX the code was actually changed to match the documentation in many
 instances.  People with more knowledge of UNIX history would be better
 to ask about that, though.  I just remember reading something like that,
 Bruce Evans (bde) or Greg Lehey (grog) come to mind as the correct
 people
 to ask.
 
 >  
 >  I'd suggest that either you consider these strings to not be part of
 >  the actual "document text" (which would be correct I think), and
 >  thereby exempt from considerations of "good writing style" - or if
 >  that isn't acceptable, leave the "Cannot"s in the man page and the
 >  "Can't"s in the code - this discrepancy shouldn't matter *too* much
 >  to the reader, who is unlikely to be searching the man page for
 >  "Can't" anyway...
 
 To the best of my knowledge, use of contractions is frowned upon in
 FreeBSD.  Again, this is an issue to take up with the respected parties.
 I've taken the liberty to cc: them for input.  Ideas?
 
 --
 Tom Rhodes

From: Per Hedeland <per@hedeland.org>
To: trhodes@FreeBSD.org
Cc: bde@FreeBSD.org, freebsd-doc@FreeBSD.org,
	FreeBSD-gnats-submit@FreeBSD.org, grog@FreeBSD.org
Subject: Re: docs/48125: [PATCH] Incorrect errno strings in intro(2)
Date: Mon, 17 Feb 2003 21:40:55 +0100 (CET)

 Well, I think this issue taking on rather bigger proportions than it
 really merits, but anyway...
 
 Tom Rhodes <trhodes@FreeBSD.org> wrote:
 
 >Per Hedeland <per@hedeland.org> wrote:
 
 >>  but I must really strongly disagree with your suggestion to change
 >>  the code! The output of programs should not be changed for such
 >>  "frivolous" reasons - e.g. there may well be scripts etc out there
 >>  that, however unwisely, rely on the exact format of error messages to
 >>  function correctly. Not to mention that using contractions in error
 >>  messages is a long-standing Unix tradition, even in cases where the
 >>  message doesn't originate in sys_errlist.
 >
 >however to my knowledge when Bell Labs originally started producing
 >UNIX the code was actually changed to match the documentation in many
 >instances.  People with more knowledge of UNIX history would be better
 >to ask about that, though.  I just remember reading something like that,
 >Bruce Evans (bde) or Greg Lehey (grog) come to mind as the correct
 >people
 >to ask.
 
 Whether correct or not, I don't really see the relevance of that. Of
 course I didn't suggest that code must *never* be changed to match
 documentation, only that code changes that may actually break things
 should not be done just to match someone's idea of "good writing style"
 for the man page.
 
 On the other hand, in this particular case the FreeBSD (or *BSD, I don't
 have another dialect to test) code might actually be a bit out-of-sync
 with the rest of the Unix family. A survey of two other Unices isn't
 exactly conclusive, and there's nothing to say that FreeBSD must be like
 everyone else, but anyway:
 
 Solaris 8:
 
 $ ./a.out
 bind: Cannot assign requested address
 
 RedHat 7.3:
 
 $  ./a.out
 bind: Cannot assign requested address
 
 FreeBSD 5.0-RELEASE:
 
 $ ./a.out 
 bind: Can't assign requested address
 
 The same difference exists for the other messages that are contractions
 in the FreeBSD sys_errlist[].
 
 And with that "contribution" I will respectfully leave this discussion,
 letting the committers sort out what should be changed where and why.
 
 --Per

From: Ceri Davies <ceri@FreeBSD.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:  
Subject: Re: docs/48125: [PATCH] Incorrect errno strings in intro(2)
Date: Mon, 17 Feb 2003 21:01:04 +0000

 Adding to audit trail from pending/48348:
 
 Message-Id: <20030216233702.GB37125@wantadilla.lemis.com>
 Date: Mon, 17 Feb 2003 10:07:02 +1030
 From: Greg 'groggy' Lehey <grog@FreeBSD.org>
 To: Tom Rhodes <trhodes@FreeBSD.org>
 Cc: Per Hedeland <per@hedeland.org>, freebsd-doc@FreeBSD.org,
 	FreeBSD-gnats-submit@FreeBSD.org, Bruce Evans <bde@FreeBSD.org>
 
  On Sunday, 16 February 2003 at 17:43:34 -0500, Tom Rhodes wrote:
  > On Sun, 16 Feb 2003 13:30:16 -0800 (PST)
  > Per Hedeland <per@hedeland.org> wrote:
  >
  >>  However, regarding the contractions: I can see where you're coming
  >>  from, since I gather that using them in "formal" documents is frowned
  >>  upon -
  >
  > True,
  >
  >>  but I must really strongly disagree with your suggestion to change
  >>  the code! The output of programs should not be changed for such
  >>  "frivolous" reasons - e.g. there may well be scripts etc out there
  >>  that, however unwisely, rely on the exact format of error messages to
  >>  function correctly. Not to mention that using contractions in error
  >>  messages is a long-standing Unix tradition, even in cases where the
  >>  message doesn't originate in sys_errlist.
  >
  > however to my knowledge when Bell Labs originally started producing
  > UNIX the code was actually changed to match the documentation in
  > many instances.  People with more knowledge of UNIX history would be
  > better to ask about that, though.  I just remember reading something
  > like that, Bruce Evans (bde) or Greg Lehey (grog) come to mind as
  > the correct people to ask.
  
  This seems unlikely.  The same people wrote the code and the docco;
  it's unlikely that changes in the docco would make it out of sync with
  the code base.  It's possible, of course, that they occasionally wrote
  docco changes first with the intention to change the code, and then
  did it, but I don't suppose that's what you're talking about.
  
  >>  I'd suggest that either you consider these strings to not be part of
  >>  the actual "document text" (which would be correct I think), and
  >>  thereby exempt from considerations of "good writing style" - or if
  >>  that isn't acceptable, leave the "Cannot"s in the man page and the
  >>  "Can't"s in the code - this discrepancy shouldn't matter *too* much
  >>  to the reader, who is unlikely to be searching the man page for
  >>  "Can't" anyway...
  >
  > To the best of my knowledge, use of contractions is frowned upon in
  > FreeBSD.  Again, this is an issue to take up with the respected parties.
  > I've taken the liberty to cc: them for input.  Ideas?
  
  I don't know about the project, but I frown on some contractions and
  not others.  In general, if the contraction is used in normal speech
  ("can't") I'd think it's OK.  If it isn't ("cont'd"), I'd disagree
  with its use.
  
  Greg
  --
  See complete headers for address and phone numbers
 
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Feb 18 14:55:32 PST 2003 
State-Changed-Why:  
Applied.  1 failed (already fixed) and another required some manual merging. 
The contractions were not applied. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=48125 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Sun Feb 23 17:22:08 PST 2003 
State-Changed-Why:  
Applied!  Thanks for the submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=48125 
>Unformatted:
