apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "William A. Rowe, Jr." <wr...@covalent.net>
Subject Re: which is *arg1 in docs first or second?
Date Tue, 22 Jan 2002 15:39:03 GMT
From: "William A. Rowe, Jr." <wrowe@covalent.net>
Sent: Tuesday, January 22, 2002 7:49 AM


> I've been looking at this since David wrote the change.  The user has no
> choice is passing an apr_file_t for new_file (really dup_file).  So as best
> as I can figure, this should [must?] be an apr_file_t*, not a **.

I was writing, of course, about apr_file_dup2(), which replaces that
convoluted documentation by splitting the behavior of dup() and dup2().

AFAIU, dup() will not require the apr_file_t **new to be initialized to
NULL - that is replaced by dup2() with the semantics I described above.

So with David's dup2() introduction complete across platforms (IIRC)...


> I'll change the API if I receive no objections by late this evening.

And fix the docs appropriately.

Bill



> From: "Stas Bekman" <stas@stason.org>
> Sent: Tuesday, January 22, 2002 2:58 AM
> 
> 
> > The apr apr_file_io.h header file uses arg1 to reference to an argument 
> > of the function. It's very confusing, since it's not clear whether it 
> > refers to the the first argument (human count) or the second (counting 
> > from 0 in C). e.g.:
> > 
> > apr_file_io.h:
> > 
> > /**
> >   * duplicate the specified file descriptor.
> >   * @param new_file The structure to duplicate into.
> >   * @param old_file The file to duplicate.
> >   * @param p The pool to use for the new file.
> >   * @remark *arg1 must point to a valid apr_file_t, or point to NULL
> >             ^^^^^
> >   */
> > APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
> >                                        apr_file_t *old_file,
> >                                        apr_pool_t *p);
> > 
> > and in two more places in this file, other .h files seem not to have a 
> > ref to arg1.
> > 
> > I think it's better to use the named argument in this case, e.g.
> > 
> >   * @remark *new_file must point to a valid apr_file_t...
> 
> 
> 
> 


Mime
View raw message