Date: Sat, 19 Dec 2020 04:41:33 -0700 From: Kevin Bowling <kevin.bowling@kev009.com> To: Ian Lepore <ian@freebsd.org> Cc: Jessica Clarke <jrtc27@freebsd.org>, Konstantin Belousov <kostikbel@gmail.com>, Mateusz Piotrowski <0mp@freebsd.org>, src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r368714 - head/lib/libc/string Message-ID: <CAK7dMtBP4L42-o01ohLoPdsRFV6yAiLjKREtDo_KL1ACWvA9qA@mail.gmail.com> In-Reply-To: <452cbb1060b7134315999c2323ed431714dc03fe.camel@freebsd.org> References: <202012171241.0BHCfl1r008452@repo.freebsd.org> <X9tU0kTm9V6KoCRr@kib.kiev.ua> <686CF2E6-1D3C-4A83-A323-02CD9F536675@freebsd.org> <X9uFtba%2BjzVroNPV@kib.kiev.ua> <452cbb1060b7134315999c2323ed431714dc03fe.camel@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Dec 17, 2020 at 9:33 AM Ian Lepore <ian@freebsd.org> wrote: > On Thu, 2020-12-17 at 18:22 +0200, Konstantin Belousov wrote: > > On Thu, Dec 17, 2020 at 01:01:01PM +0000, Jessica Clarke wrote: > > > On 17 Dec 2020, at 12:53, Konstantin Belousov <kostikbel@gmail.com> > > > wrote: > > > > > > > > On Thu, Dec 17, 2020 at 12:41:47PM +0000, Mateusz Piotrowski > > > > wrote: > > > > > Author: 0mp (doc,ports committer) > > > > > Date: Thu Dec 17 12:41:47 2020 > > > > > New Revision: 368714 > > > > > URL: https://svnweb.freebsd.org/changeset/base/368714 > > > > > > > > > > Log: > > > > > strerror.3: Add an example for perror() > > > > > > > > > > This is a nice and quick reference. > > > > > > > > > > Reviewed by: jilles, yuripv > > > > > MFC after: 2 weeks > > > > > Differential Revision: https://reviews.freebsd.org/D27623 > > > > > > > > > > Modified: > > > > > head/lib/libc/string/strerror.3 > > > > > > > > > > Modified: head/lib/libc/string/strerror.3 > > > > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > > > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > > > > --- head/lib/libc/string/strerror.3 Thu Dec 17 03:42:54 > > > > > 2020 (r368713) > > > > > +++ head/lib/libc/string/strerror.3 Thu Dec 17 12:41:47 > > > > > 2020 (r368714) > > > > > @@ -32,7 +32,7 @@ > > > > > .\" @(#)strerror.3 8.1 (Berkeley) 6/9/93 > > > > > .\" $FreeBSD$ > > > > > .\" > > > > > -.Dd December 7, 2020 > > > > > +.Dd December 17, 2020 > > > > > .Dt STRERROR 3 > > > > > .Os > > > > > .Sh NAME > > > > > @@ -170,6 +170,31 @@ The use of these variables is deprecated; > > > > > or > > > > > .Fn strerror_r > > > > > should be used instead. > > > > > +.Sh EXAMPLES > > > > > +The following example shows how to use > > > > > +.Fn perror > > > > > +to report an error. > > > > > +.Bd -literal -offset 2n > > > > > +#include <fcntl.h> > > > > > +#include <stdio.h> > > > > > +#include <stdlib.h> > > > > > + > > > > > +int > > > > > +main(void) > > > > > +{ > > > > > + int fd; > > > > > + > > > > > + if ((fd =3D open("/nonexistent", O_RDONLY)) =3D=3D -1) { > > > > > + perror("open()"); > > > > > + exit(1); > > > > > + } > > > > > + printf("File descriptor: %d\en", fd); > > > > > > > > This lines is indented with spaces, while other lines have tabs. > > > > > > > > > + return (0); > > > > > > > > return (0) is redundand. > > > > > > It's not required as per the standard, but omitting it is needlessly > > > obfuscating it and bad practice. C lets you do a whole load of things > > > that are a bad idea, and whilst this one is harmless, it is nonethele= ss > > > confusing to anyone who is not intimately acquainted quirks like this > > > special case in the standard. > > > > Why it is bad practice ? > > > > C is a small language, and while knowing some quirks (like this one) > > seems to be optional, others are not. And worse, that other quirks are > > essential for writing correct code at all. Consequence is that ignoring > > details indicates insufficient knowledge of the fundamentals and lowers > > the trust in the provided suggestion. > > I completely disagree. Writing example code where you fail to return a > value and just fall out the bottom of some function that declares it > returns an int is just Bad Code. Using some obscure quirk of the > language as justification for that bad code doesn't help the situation > at all. > > How obscure is this quirk? I've been writing C code since 1983, > including having released a freeware compiler (pre-gcc days) and > working on a commercial C compiler. I used to moderate the c_language > conference on BIX (back when that was a thing). I make my living > writing C and C++ code every day. And yet, I had completely forgotten > about this quirk. > > Example code shouldn't be used to establish how much more clever you > are than the reader, it should be as easy to understand as possible. > > -- Ian In Kib=E2=80=99s defense I think this is commonly mentioned in C99 books (a= t least that=E2=80=99s where I learned of it) so it depends on when and where someo= ne learned. There are merits approaches of being explicit or brief. I have no preference directly but we should probably try to be uniform in our examples with whatever is most common in the docs already. >
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAK7dMtBP4L42-o01ohLoPdsRFV6yAiLjKREtDo_KL1ACWvA9qA>