From owner-svn-src-head@freebsd.org Sat Dec 19 11:41:47 2020 Return-Path: Delivered-To: svn-src-head@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 1C0CB4C4992 for ; Sat, 19 Dec 2020 11:41:47 +0000 (UTC) (envelope-from kevin.bowling@kev009.com) Received: from mail-yb1-xb2d.google.com (mail-yb1-xb2d.google.com [IPv6:2607:f8b0:4864:20::b2d]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4CykNB1v65z3LBW for ; Sat, 19 Dec 2020 11:41:46 +0000 (UTC) (envelope-from kevin.bowling@kev009.com) Received: by mail-yb1-xb2d.google.com with SMTP id d37so4449098ybi.4 for ; Sat, 19 Dec 2020 03:41:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kev009.com; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=su//Dz7rEUfHZtJJgVsJFd2fS+ZhGMjqLtFXMqyc+Xo=; b=DDdqvV44tEc7Ag9sdft7ecVtIkKv7bcthNscwTBir8a+vwTBHsNxhm7Bj2CLE5XcOb BYn1NgDOZDMfxd/9M84FIXmZ86s2tYq5ZZRybbkHuAQd/OXhqBYDfBhdTWKjQfULLoYJ SECnWhw+nFY7BoZQvPRqZonLk6tWiF/AsYr44= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=su//Dz7rEUfHZtJJgVsJFd2fS+ZhGMjqLtFXMqyc+Xo=; b=O9e2Aaxb3FMHnGFUzVGXZ7nZLmjmMGdU0UIUO7Z5hhTqSKBLHZrTV7bjyuhNljZUPT LgBka1xSr8er0JFTSaK2lE4f67WgfEnMZcPtAJ57MEMgBpD8Dh8qFUakW1vHQCS9Bxh0 3O1BLnb3MYeTKPxUghMNLfSZIcOp5cf85Kz6AkyaVgy9VIUDDMQRlg4XtTgAlXuNzmFu LgX+qKWYjXOIbzaoMWtNS2P/mHWDJNFFhX5P88RSaPRSrI4Xwtxqgb6/yh/bac13l5mU +XB/kSTD/rtuOYz3Rm4tceb2d5VIHU124vJ6l4KYIFC1GO3UqKR9TvhcVDVEJM/2g45g bhmQ== X-Gm-Message-State: AOAM530nvPpk6ct9FFjVLkJRwiHIa6S4/5wVKpbTFkbgVmRMuUMHeHVM aSORVRU1jEwd5U9hJKa7jdRKFfhU0rOO9Tv7K2fTyA== X-Google-Smtp-Source: ABdhPJzHqveKD/9z1q6pahxvA12Cxg0FWZ65ZaQV1LmdT4VPJQHPkCFhIWtxKpRxFYH3lczzsl2gDIvdsM220gKrhDQ= X-Received: by 2002:a25:ac1f:: with SMTP id w31mr11774601ybi.87.1608378104602; Sat, 19 Dec 2020 03:41:44 -0800 (PST) MIME-Version: 1.0 References: <202012171241.0BHCfl1r008452@repo.freebsd.org> <686CF2E6-1D3C-4A83-A323-02CD9F536675@freebsd.org> <452cbb1060b7134315999c2323ed431714dc03fe.camel@freebsd.org> In-Reply-To: <452cbb1060b7134315999c2323ed431714dc03fe.camel@freebsd.org> From: Kevin Bowling Date: Sat, 19 Dec 2020 04:41:33 -0700 Message-ID: Subject: Re: svn commit: r368714 - head/lib/libc/string To: Ian Lepore Cc: Jessica Clarke , Konstantin Belousov , Mateusz Piotrowski <0mp@freebsd.org>, src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-Rspamd-Queue-Id: 4CykNB1v65z3LBW X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=none (invalid DKIM record) header.d=kev009.com header.s=google header.b=DDdqvV44; dmarc=none; spf=pass (mx1.freebsd.org: domain of kevin.bowling@kev009.com designates 2607:f8b0:4864:20::b2d as permitted sender) smtp.mailfrom=kevin.bowling@kev009.com X-Spamd-Result: default: False [-3.30 / 15.00]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; FROM_HAS_DN(0.00)[]; TO_DN_SOME(0.00)[]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4000::/36:c]; NEURAL_HAM_LONG(-1.00)[-1.000]; MIME_GOOD(-0.10)[multipart/alternative,text/plain]; PREVIOUSLY_DELIVERED(0.00)[svn-src-head@freebsd.org]; DMARC_NA(0.00)[kev009.com]; SPAMHAUS_ZRD(0.00)[2607:f8b0:4864:20::b2d:from:127.0.2.255]; TO_MATCH_ENVRCPT_SOME(0.00)[]; DKIM_TRACE(0.00)[kev009.com:~]; NEURAL_HAM_SHORT(-1.00)[-1.000]; RCPT_COUNT_SEVEN(0.00)[7]; RCVD_IN_DNSWL_NONE(0.00)[2607:f8b0:4864:20::b2d:from]; R_DKIM_PERMFAIL(0.00)[kev009.com:s=google]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+,1:+,2:~]; RBL_DBL_DONT_QUERY_IPS(0.00)[2607:f8b0:4864:20::b2d:from]; RCVD_COUNT_TWO(0.00)[2]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; MAILMAN_DEST(0.00)[svn-src-head]; FREEMAIL_CC(0.00)[freebsd.org,gmail.com] Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Content-Filtered-By: Mailman/MimeDel 2.1.34 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 19 Dec 2020 11:41:47 -0000 On Thu, Dec 17, 2020 at 9:33 AM Ian Lepore 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 > > > 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 > > > > > +#include > > > > > +#include > > > > > + > > > > > +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. >