From owner-freebsd-current@FreeBSD.ORG  Wed Mar 19 19:49:09 2014
Return-Path: <owner-freebsd-current@FreeBSD.ORG>
Delivered-To: freebsd-current@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115])
 (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by hub.freebsd.org (Postfix) with ESMTPS id 7734CE0A;
 Wed, 19 Mar 2014 19:49:09 +0000 (UTC)
Received: from bigwig.baldwin.cx (bigwig.baldwin.cx [IPv6:2001:470:1f11:75::1])
 (using TLSv1 with cipher ADH-CAMELLIA256-SHA (256/256 bits))
 (No client certificate requested)
 by mx1.freebsd.org (Postfix) with ESMTPS id 4DE563F7;
 Wed, 19 Mar 2014 19:49:09 +0000 (UTC)
Received: from jhbbsd.localnet (unknown [209.249.190.124])
 by bigwig.baldwin.cx (Postfix) with ESMTPSA id 57EC5B96E;
 Wed, 19 Mar 2014 15:49:08 -0400 (EDT)
From: John Baldwin <jhb@freebsd.org>
To: Warren Block <wblock@wonkity.com>
Subject: Re: Hello fdclose
Date: Wed, 19 Mar 2014 15:23:33 -0400
User-Agent: KMail/1.13.5 (FreeBSD/8.4-CBSD-20130906; KDE/4.5.5; amd64; ; )
References: <CAGOYWV80vTTQbvSjvNa6XBzBiKy+jnGantkUH_RO=8prxoHmyQ@mail.gmail.com>
 <201403181404.52197.jhb@freebsd.org>
 <alpine.BSF.2.00.1403182230140.45496@wonkity.com>
In-Reply-To: <alpine.BSF.2.00.1403182230140.45496@wonkity.com>
MIME-Version: 1.0
Content-Type: Text/Plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Message-Id: <201403191523.33275.jhb@freebsd.org>
X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7
 (bigwig.baldwin.cx); Wed, 19 Mar 2014 15:49:08 -0400 (EDT)
Cc: jilles@freebsd.org, freebsd-arch@freebsd.org, freebsd-current@freebsd.org,
 Mariusz Zaborski <oshogbo@freebsd.org>
X-BeenThere: freebsd-current@freebsd.org
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: Discussions about the use of FreeBSD-current
 <freebsd-current.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-current>, 
 <mailto:freebsd-current-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-current/>
List-Post: <mailto:freebsd-current@freebsd.org>
List-Help: <mailto:freebsd-current-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-current>,
 <mailto:freebsd-current-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Wed, 19 Mar 2014 19:49:09 -0000

On Wednesday, March 19, 2014 12:38:57 am Warren Block wrote:
> On Tue, 18 Mar 2014, John Baldwin wrote:
> 
> > On Monday, March 17, 2014 7:23:19 pm Mariusz Zaborski wrote:
> >> Hi,
> >>
> >> After our previous discuss  [1] I prepare fdclosedir(3) function which
> >> was committed by Pawel (cc'ed) in commit r254499.
> >>
> >> A while ago I also prepare the fdclose function. Unfortunately, this
> >> new function is a little bit more tricky then previous one. Can I ask
> >> you for a review of this patch?
> >
> > I think the code is fine.  I have a few suggestions on the manpage wording:
> >
> > The
> > +.Fn fdclose
> > +function is equivalent to the
> > +.Fn fclose
> > +function except that this function returns file descriptor instead of
> > +closing it.
> > +.Pp
> > +The
> >
> > I would move fdclose() to its own paragraph and reword this sentence as:
> >
> >  "The fdclose() function is equivalent to fclose() except that it does
> >   not close the underlying file descriptor."
> 
> .Fn fdclose
> is equivalent to
> .Fn fclose ,
> but the file descriptor is returned rather than closed.
> 
> Likewise in other sections, the markup is supposed to do the job of 
> pointing out that something is a function.

Yes, but this has the 'no capital letter at the start of a sentence' problem.

Also, I do think reusing the 'underlying file descriptor' language is important
in the context of the earlier description of fclose().

-- 
John Baldwin