Re: Hello fdclose
> > > +FBSD_1.4 { > > + fdclose; > > +}; > > + > > You also need to update the lib/libc/Versions.def file. Look e.g. at > the r226217 for the proper way to introduce new version. > Updated - thank you. Cheers, Mariusz ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Tue, Mar 25, 2014 at 11:25:28PM +0100, Mariusz Zaborski wrote: > >> [snip] > >> --- //depot/user/oshogbo/capsicum/lib/libc/stdio/Symbol.map 2013-06-28 > >> 08:51:28.0 > >> +++ /home/oshogbo/p4/capsicum/lib/libc/stdio/Symbol.map 2013-06-28 > >> 08:51:28.0 > >> @@ -156,6 +156,7 @@ > >> putwc_l; > >> putwchar_l; > >> fmemopen; > >> + fdclose; > >> open_memstream; > >> open_wmemstream; > >> }; > > > > This should be in the FBSD_1.4 namespace (which does not exist yet). > > Oh - thx, so this will be good now? > > @@ -160,6 +160,10 @@ > open_wmemstream; > }; > > +FBSD_1.4 { > + fdclose; > +}; > + You also need to update the lib/libc/Versions.def file. Look e.g. at the r226217 for the proper way to introduce new version. pgp0_xHr6UbB1.pgp Description: PGP signature
Re: Hello fdclose
On 22 March 2014 08:04, Kevin Oberman wrote: > On Fri, Mar 21, 2014 at 5:51 PM, Dag-Erling Smørgrav wrote: >> >> Warner Losh writes: >> > It does serve a useful purpose, though, which is why it has endured. >> > If you were to have a man page that said 'Putc(3) returns ...' then the >> > automated tools (and web links) that find Putc.3 wouldn't be able to >> > since >> > it doesn't exist. >> >> Moreover - if FreeBSD were written in Pascal, it might not matter, but >> in C, _exit(2) and _Exit(3) are two different functions. >> >> (I'm sure there are other examples without a leading underscore) >> >> (eww, starting a sentence with a non-alphabetic character would be even >> worse...) > > > 3Com was once a very important networking company. 3M still is. > > /me duck and runs. > -- > R. Kevin Oberman, Network Engineer, Retired > E-mail: rkober...@gmail.com Hello, Thx guys for such big interested of the fdclose function :) When we decide how API will look and how the fdclose function will behave then I will correct man page. Thx, Mariusz ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
> Does this patch allow perl to stop writing to FILE._file? As pointed out > in > http://lists.freebsd.org/pipermail/freebsd-current/2013-January/039024.html > perlio.c in the perl source contains a function > PerlIOStdio_invalidate_fileno() that should modify a FILE such that > fclose() does not close the file descriptor but still frees all memory > (Perl has already called fflush()). Although using fdclose() could solve > this without touching the internals of FILE, this will make perlio.c > uglier with even more #ifdefs. Yes it should help. I start some work on it but i have some troubles with perl (I'm not perl hacker :(), so I will try to prepare some patch for it in the nearest feature. There are some other places also where we could use it. >> [snip] >> --- //depot/user/oshogbo/capsicum/lib/libc/stdio/Symbol.map 2013-06-28 >> 08:51:28.0 >> +++ /home/oshogbo/p4/capsicum/lib/libc/stdio/Symbol.map 2013-06-28 >> 08:51:28.0 >> @@ -156,6 +156,7 @@ >> putwc_l; >> putwchar_l; >> fmemopen; >> + fdclose; >> open_memstream; >> open_wmemstream; >> }; > > This should be in the FBSD_1.4 namespace (which does not exist yet). Oh - thx, so this will be good now? @@ -160,6 +160,10 @@ open_wmemstream; }; +FBSD_1.4 { + fdclose; +}; + >> [snip] >> --- //depot/user/oshogbo/capsicum/lib/libc/stdio/fclose.c 2013-06-28 >> 08:51:28.0 >> +++ /home/oshogbo/p4/capsicum/lib/libc/stdio/fclose.c 2013-06-28 >> 08:51:28.0 >> [snip] >> +int >> +fdclose(FILE *fp) >> +{ >> + int fd, r, err; >> + >> + if (fp->_flags == 0) { /* not open! */ >> + errno = EBADF; >> + return (EOF); >> + } >> + >> + r = 0; >> + FLOCKFILE(fp); >> + fd = fp->_file; >> + if (fp->_close != __sclose) { >> + r = EOF; >> + errno = EOPNOTSUPP; >> + } else if (fd < 0) { >> + r = EOF; >> + errno = EBADF; >> + } >> + if (r == EOF) { >> + err = errno; >> + (void)cleanfile(fp, true); >> + errno = err; >> + } else { >> + r = cleanfile(fp, false); >> + } >> FUNLOCKFILE(fp); >> + >> + return (r == 0 ? fd : r); > > If a file descriptor would be returned but cleanfile() returns an error > (e.g. write error on flush), the file descriptor is not returned and not > closed. > > I think that in cases where fdclose() would be used, it is essential > that the file descriptor is never closed. This means that the API needs > to be different so it can report a write error but still return a file > descriptor. One way to do this is to return the file descriptor by > reference. Another is to expect the application to call fileno() and not > return the descriptor from the new function. You have very good point. The first question is where function will return error: 1* When there is different _close function from std (it will behave like fclose with some errno) 2* When __sflush fails (and it will free structure) 3* When fd in structure is not correct (it will behave like fclose with some errno) I think those assumptions about when close fd are reasonable. When I wrote this function I discouse this with Pawel, and we decided that if _close function is different from std we should work same as fclose function plus return errno about EOPNOTSUPP. So in my opinion only second point is unwanted by us. So if __sflush fails we could not return any err (I don't thing this is wanted solution) or we could return error returned by __sflush and not free structure. In my opinion last option will be the best one. What you think Jilles? In this moment I don't like idea of changing API of this function. Cheers, Mariusz ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
Hello, I'm using as MUA the famous 'mutt' and from time to time I'm missing a feature in 'mutt': mark a thread as unwanted to present any new messages in this thread. This is one I would mark for this. Thanks matthias -- Sent from my FreeBSD netbook Matthias Apitz, , http://www.unixarea.de/ f: +49-170-4527211 UNIX since V7 on PDP-11, UNIX on mainframe since ESER 1055 (IBM /370) UNIX on x86 since SVR4.2 UnixWare 2.1.2, FreeBSD since 2.2.5 ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
The call to <> Done. Moving on! -a On 22 March 2014 06:40, George Mitchell wrote: > On 03/21/14 20:51, Dag-Erling Smørgrav wrote: >> >> Warner Losh writes: >>> >>> It does serve a useful purpose, though, which is why it has endured. >>> If you were to have a man page that said 'Putc(3) returns ...' then the >>> automated tools (and web links) that find Putc.3 wouldn't be able to >>> since >>> it doesn't exist. >> >> >> Moreover - if FreeBSD were written in Pascal, it might not matter, but >> in C, _exit(2) and _Exit(3) are two different functions. >> >> (I'm sure there are other examples without a leading underscore) >> >> (eww, starting a sentence with a non-alphabetic character would be even >> worse...) >> >> DES >> > Etc., etc., etc. Wouldn't it be more productive to spend this effort on > recasting the sentence in question so that it doesn't start with a word > that starts with a small letter? -- George > > ___ > freebsd-current@freebsd.org mailing list > http://lists.freebsd.org/mailman/listinfo/freebsd-current > To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org" ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On 03/21/14 20:51, Dag-Erling Smørgrav wrote: Warner Losh writes: It does serve a useful purpose, though, which is why it has endured. If you were to have a man page that said ‘Putc(3) returns …’ then the automated tools (and web links) that find Putc.3 wouldn’t be able to since it doesn’t exist. Moreover - if FreeBSD were written in Pascal, it might not matter, but in C, _exit(2) and _Exit(3) are two different functions. (I'm sure there are other examples without a leading underscore) (eww, starting a sentence with a non-alphabetic character would be even worse...) DES Etc., etc., etc. Wouldn't it be more productive to spend this effort on recasting the sentence in question so that it doesn't start with a word that starts with a small letter? -- George ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Fri, Mar 21, 2014 at 5:51 PM, Dag-Erling Smørgrav wrote: > Warner Losh writes: > > It does serve a useful purpose, though, which is why it has endured. > > If you were to have a man page that said ‘Putc(3) returns …’ then the > > automated tools (and web links) that find Putc.3 wouldn’t be able to > since > > it doesn’t exist. > > Moreover - if FreeBSD were written in Pascal, it might not matter, but > in C, _exit(2) and _Exit(3) are two different functions. > > (I'm sure there are other examples without a leading underscore) > > (eww, starting a sentence with a non-alphabetic character would be even > worse...) > 3Com was once a very important networking company. 3M still is. /me duck and runs. -- R. Kevin Oberman, Network Engineer, Retired E-mail: rkober...@gmail.com ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
Warner Losh writes: > It does serve a useful purpose, though, which is why it has endured. > If you were to have a man page that said ‘Putc(3) returns …’ then the > automated tools (and web links) that find Putc.3 wouldn’t be able to since > it doesn’t exist. Moreover - if FreeBSD were written in Pascal, it might not matter, but in C, _exit(2) and _Exit(3) are two different functions. (I'm sure there are other examples without a leading underscore) (eww, starting a sentence with a non-alphabetic character would be even worse...) DES -- Dag-Erling Smørgrav - d...@des.no ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
Ian Lepore writes: > Just as the age of a moronic "rule" such as this doesn't in any way > justify the idea that it could never be changed. I never claimed it did, but I can see how it would be convenient to pretend that I did so you can attack that instead of discussing the actual issue. DES -- Dag-Erling Smørgrav - d...@des.no ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Mar 21, 2014, at 11:20 AM, Ian Lepore wrote: > On Fri, 2014-03-21 at 17:54 +0100, Dag-Erling Smørgrav wrote: >> Warren Block writes: >>> Dag-Erling Smørgrav writes: I mean the FreeBSD project, and the reason is as John stated: all sentences must start with a capital letter. I've gotten so used to this over the past 15 years that I even do it in email and other non-FreeBSD written material. >>> "Because it's been that way for 15 years" is not always a >>> justification (consider BIND in base, for example :). >> >> "I don't like your answer, so I will ignore it" is not a justification >> either. It's kindergarden behavior and beneath the dignity of a FreeBSD >> committer. >> >> We have a rule that sentences must always start with a capital letter. >> The fact that this rule was instituted 15 years ago does not >> automatically invalidate it, and neither does the fact that Joe Random >> Committer disagrees with it. >> >> DES > > Just as the age of a moronic "rule" such as this doesn't in any way > justify the idea that it could never be changed. Especially when the > "rule" appears to be an undocumented prejudice. It has been the way things have been for a long time, and everybody that has been writing man pages in the project for any length of time knows it. Ruslan was especially good about fixing this issue back in the day. This rule was hashed out and there’s really no compelling reason to change it. Unlike BIND, we have had no complaints about it in the almost two decades it has been around… It does serve a useful purpose, though, which is why it has endured. If you were to have a man page that said ‘Putc(3) returns …’ then the automated tools (and web links) that find Putc.3 wouldn’t be able to since it doesn’t exist. > People love to throw around assertions about "rules" of the English > language. It doesn't have many rules (subject has to agree in number > with the verb, that's about it for unbreakable rules), but it has as > many opinions on proper style as there are readers and writers. This is the proper style for FreeBSD man page, by convention. It is so basic that it doesn’t surprise me it isn’t in the docs, but it also surprises me that it isn’t. There’s numerous instances of this rule being mentioned in commit messages: http://lists.freebsd.org/pipermail/cvs-doc/2008-February/017562.html http://osdir.com/ml/os.freebsd.devel.cvs.doc/2004-07/msg00284.html http://blog.gmane.org/gmane.os.freebsd.devel.documentation/month=20050201/page=6 or the discussions in the archives like: http://osdir.com/ml/freebsd.devel.documentation/2002-05/msg00589.html http://markmail.org/thread/jx2jr5myngp5jg5d#query:+page:1+mid:lasvnzqoojxfeoet+state:results or a few other places. These discussions span the last 15 years (the oldest one is 1999, but the convention is easily a few years older than that). Warner ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Fri, 2014-03-21 at 17:54 +0100, Dag-Erling Smørgrav wrote: > Warren Block writes: > > Dag-Erling Smørgrav writes: > > > I mean the FreeBSD project, and the reason is as John stated: all > > > sentences must start with a capital letter. I've gotten so used to > > > this over the past 15 years that I even do it in email and other > > > non-FreeBSD written material. > > "Because it's been that way for 15 years" is not always a > > justification (consider BIND in base, for example :). > > "I don't like your answer, so I will ignore it" is not a justification > either. It's kindergarden behavior and beneath the dignity of a FreeBSD > committer. > > We have a rule that sentences must always start with a capital letter. > The fact that this rule was instituted 15 years ago does not > automatically invalidate it, and neither does the fact that Joe Random > Committer disagrees with it. > > DES Just as the age of a moronic "rule" such as this doesn't in any way justify the idea that it could never be changed. Especially when the "rule" appears to be an undocumented prejudice. People love to throw around assertions about "rules" of the English language. It doesn't have many rules (subject has to agree in number with the verb, that's about it for unbreakable rules), but it has as many opinions on proper style as there are readers and writers. -- Ian ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
Warren Block writes: > Dag-Erling Smørgrav writes: > > I mean the FreeBSD project, and the reason is as John stated: all > > sentences must start with a capital letter. I've gotten so used to > > this over the past 15 years that I even do it in email and other > > non-FreeBSD written material. > "Because it's been that way for 15 years" is not always a > justification (consider BIND in base, for example :). "I don't like your answer, so I will ignore it" is not a justification either. It's kindergarden behavior and beneath the dignity of a FreeBSD committer. We have a rule that sentences must always start with a capital letter. The fact that this rule was instituted 15 years ago does not automatically invalidate it, and neither does the fact that Joe Random Committer disagrees with it. DES -- Dag-Erling Smørgrav - d...@des.no ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Fri, 21 Mar 2014, Dag-Erling Smørgrav wrote: Warren Block writes: Dag-Erling Smørgrav writes: We always use [The .Nm foo utility or The .Fn foo function] instead of just .Nm or .Fn at the start of a sentence, but never (or rarely) within a sentence. By "we", do you mean the FreeBSD project or your local organization? Is there a specific reason the redundant wording, or is it just customary? I mean the FreeBSD project, and the reason is as John stated: all sentences must start with a capital letter. I've gotten so used to this over the past 15 years that I even do it in email and other non-FreeBSD written material. DES "Because it's been that way for 15 years" is not always a justification (consider BIND in base, for example :). I'll let this drop for now, but still find it interesting that it is not mentioned in the FDP Primer, and those style guide rules date back at least 15 years. It may be that the original doc project members felt that capitalizing the first word of a sentence was so obvious that it did not need to be stated. Or possibly, that it was a rule that could be usefully broken at times. ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Mar 21, 2014, at 8:18 AM, Dag-Erling Smørgrav wrote: > Warren Block writes: >> Dag-Erling Smørgrav writes: >>> We always use [The .Nm foo utility or The .Fn foo function] instead >>> of just .Nm or .Fn at the start of a sentence, but never (or rarely) >>> within a sentence. >> By "we", do you mean the FreeBSD project or your local organization? >> Is there a specific reason the redundant wording, or is it just >> customary? > > I mean the FreeBSD project, and the reason is as John stated: all > sentences must start with a capital letter. I've gotten so used to this > over the past 15 years that I even do it in email and other non-FreeBSD > written material. Yes, it is style that was settled upon 15 years ago or so in the FreeBSD project. Even more than finding myself using this in email, etc, I find that when I see people using other conventions it just looks wrong to my eyes. Warner ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
Warren Block writes: > Dag-Erling Smørgrav writes: > > We always use [The .Nm foo utility or The .Fn foo function] instead > > of just .Nm or .Fn at the start of a sentence, but never (or rarely) > > within a sentence. > By "we", do you mean the FreeBSD project or your local organization? > Is there a specific reason the redundant wording, or is it just > customary? I mean the FreeBSD project, and the reason is as John stated: all sentences must start with a capital letter. I've gotten so used to this over the past 15 years that I even do it in email and other non-FreeBSD written material. DES -- Dag-Erling Smørgrav - d...@des.no ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Thu, 20 Mar 2014, Dag-Erling Smørgrav wrote: Warren Block writes: John Baldwin writes: Warren Block writes: .Fn fdclose is equivalent to .Fn fclose , but the file descriptor is returned rather than closed. Yes, but this has the 'no capital letter at the start of a sentence' problem. I've heard that mentioned before, but have never seen any actual rule regarding it. And we do have actual rules about avoiding redundant phrases: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style-guidelines We always use The .Nm foo utility or The .Fn foo function instead of just .Nm or .Fn at the start of a sentence, but never (or rarely) within a sentence. By "we", do you mean the FreeBSD project or your local organization? Is there a specific reason the redundant wording, or is it just customary? I suspect that usage is similar to that for an acronym, defining it on the first usage but only then. Both mdoc and DocBook markup should accomplish the same thing. ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
Warren Block writes: > John Baldwin writes: > > Warren Block writes: > > > .Fn fdclose > > > is equivalent to > > > .Fn fclose , > > > but the file descriptor is returned rather than closed. > > Yes, but this has the 'no capital letter at the start of a sentence' > > problem. > I've heard that mentioned before, but have never seen any actual rule > regarding it. And we do have actual rules about avoiding redundant > phrases: > http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style-guidelines We always use The .Nm foo utility or The .Fn foo function instead of just .Nm or .Fn at the start of a sentence, but never (or rarely) within a sentence. DES -- Dag-Erling Smørgrav - d...@des.no ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Wednesday, March 19, 2014 4:28:15 pm Warren Block wrote: > On Wed, 19 Mar 2014, John Baldwin wrote: > > > 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. > > I've heard that mentioned before, but have never seen any actual rule > regarding it. All of my rules for that come from elementary school. :) -- John Baldwin ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Tuesday, March 18, 2014 5:35:16 pm Jilles Tjoelker wrote: > On Tue, Mar 18, 2014 at 12:23:19AM +0100, Mariusz Zaborski wrote: > > 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? > > Does this patch allow perl to stop writing to FILE._file? As pointed out > in > http://lists.freebsd.org/pipermail/freebsd-current/2013-January/039024.html > perlio.c in the perl source contains a function > PerlIOStdio_invalidate_fileno() that should modify a FILE such that > fclose() does not close the file descriptor but still frees all memory > (Perl has already called fflush()). Although using fdclose() could solve > this without touching the internals of FILE, this will make perlio.c > uglier with even more #ifdefs. I hope it does. I want to have some sort of API for Perl to use so it stops (ab)using _file before I move forward with full int _file. > I think that in cases where fdclose() would be used, it is essential > that the file descriptor is never closed. This means that the API needs > to be different so it can report a write error but still return a file > descriptor. One way to do this is to return the file descriptor by > reference. Another is to expect the application to call fileno() and not > return the descriptor from the new function. I would prefer the latter of requiring the application to use fileno(). -- John Baldwin ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Wed, 19 Mar 2014, John Baldwin wrote: 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. I've heard that mentioned before, but have never seen any actual rule regarding it. And we do have actual rules about avoiding redundant phrases: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style-guidelines While normal words should be capitalized as the first word in a sentence, special words that are case-sensitive override that (IMO). Also, I do think reusing the 'underlying file descriptor' language is important in the context of the earlier description of fclose(). Sorry, a problem with my micro-optimization: .Fn fdclose is equivalent to .Fn fclose , but does not close the underlying file descriptor. ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
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 ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
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. textproc/igor can identify some problems with wording. It also checks for rudimentary mdoc(7) requirements. If desired, I'm willing to edit this man page. (I've learned far too recently that most people do not want to be consulted on wording, they just want it fixed. That's now the approach I take: make all the corrections and return it, rather than a back-and-forth with the danger of edit fatigue.) ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
On Tue, 18 Mar 2014, John Baldwin wrote: On Monday, March 17, 2014 7:23:19 pm Mariusz Zaborski wrote: ... I think the code is fine. I have a few suggestions on the manpage wording: .Sh RETURN VALUES -Upon successful completion 0 is returned. +The +.Fn fcloseall +function return no value. +.Pp +Upon successful completion +.Fn fclose +return 0. +Otherwise, +.Dv EOF +is returned and the global variable +.Va errno +is set to indicate the error. The .Rv macro should be used whenever possible. Unfortunately, it doesn't support the EOF return, but only -1, so stdio man pages can rarely use it, and this one is no exception. Using it gives standard wording that is quite different from the above: standard wording: The close() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. above wording (previous): Upon successful completion 0 is returned.Otherwise, EOF is returned and the global variable errno is set to indicate the error. above wording (new): Upon successful completion fclose() return [sic] 0. Otherwise, EOF is returned and the global variable errno is set to indicate the error. These are excessively formal in different ways: - I don't like "the foo() function". Why not just "foo()"? The standard wording uses this, and so does the new wording, but the previous wording omits the function name (that only works for man pages that only have a single function, as they should). - I don't like "the value N". Why not just "N"? The standard wording uses this, but the previous and new wordings don't. - "returns N" is better than "N is returned". Some man pages use worse wordings like "N will be returned". - "the global variable errno" is excessively detailed/verbose, without the details even being correct. Why not just "errno", with this identifier documented elsewhere? errno isn't a global variable in most implementations. It is can be, and usually is, a macro that expands to a modifiable lvalue of type int. In FreeBSD, the macro expands to a function that returns a pointer to int. - "Upon sucessful completion" is correct but verbose. The standard wording doesn't even use it. - the standard wording uses a conjunction instead of a new sentence before "otherwise" (this is better). It is missing a comma after "otherwise" (this is worse). +.Pp +The +.Fn fdclose +function return the file descriptor if successfull. Otherwise, .Dv EOF "successfull is consistently misspelled. One of English's arcane rules is that most verbs append an 's' when used with singular subjects, so "function returns" shoud be used instead of "function return", etc. I do think for this section it would be good to combine the descriptions of fclose() and fdclose() when possible, so perhaps something like: "The fcloseall() function returns no value. Upon successful completion, fclose() returns 0 and fdclose() returns the file descriptor of the underlying file. Otherwise, EOF is returned and the global variable errno is set to indicate the error. In either case no further access to the stream is possible." OK. You kept "return[s] N" and and deverbosified "the foo() function". "Upon successful completion" is needed more with several functions. "the global variable errno" remains consistently bad. There should be a comma after "In either case". This allows "in either case" to still read correctly and makes it clear it applies to both fclose() and fdclose(). Better "In every case". .Sh ERRORS +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP The +.Fa _close +method in +.Fa stream +argument to +.Fn fdclose , +was not default. +.It Bq Er EBADF The ERRORS section should be sorted. For the errors section, the first error list needs some sort of introductory text. Also, this shouldn't claim that fdclose() can return an errno value for close(2). "ERRORS The fdclose() function may will fail if: I don't like the tense given by "will" in man pages. POSIX says "shall fail" in similar contexts, and "will fail" is a mistranslation of this ("shall" is a technical term that doesn't suggest future tense). deshallify.sh does the not-incorrect translation s/shall fail/fails/ (I think this is too simple to always work). It doesn't translate anything to "will". I can't parse "may will" :-). deshallify.txt doesn't translate "may" or "should" to anything (these are also technical terms in some contexts, so they might need translation. IIRC, "may" is optional behaviour, mostly for the implementation, while "shall" is required behaviour, only for the implementation, but "should" is recommended practice, mostly for applications). Man pages are very unlikely to be as consistent as POSIX with these terms. [EOPNOTSUPP] The stream to close uses a non-default close method. [EBADF]The stream is not backed by a valid file de
Re: Hello fdclose
On Tue, Mar 18, 2014 at 12:23:19AM +0100, Mariusz Zaborski wrote: > 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? Does this patch allow perl to stop writing to FILE._file? As pointed out in http://lists.freebsd.org/pipermail/freebsd-current/2013-January/039024.html perlio.c in the perl source contains a function PerlIOStdio_invalidate_fileno() that should modify a FILE such that fclose() does not close the file descriptor but still frees all memory (Perl has already called fflush()). Although using fdclose() could solve this without touching the internals of FILE, this will make perlio.c uglier with even more #ifdefs. > [snip] > --- //depot/user/oshogbo/capsicum/lib/libc/stdio/Symbol.map 2013-06-28 > 08:51:28.0 > +++ /home/oshogbo/p4/capsicum/lib/libc/stdio/Symbol.map 2013-06-28 > 08:51:28.0 > @@ -156,6 +156,7 @@ > putwc_l; > putwchar_l; > fmemopen; > + fdclose; > open_memstream; > open_wmemstream; > }; This should be in the FBSD_1.4 namespace (which does not exist yet). > [snip] > --- //depot/user/oshogbo/capsicum/lib/libc/stdio/fclose.c 2013-06-28 > 08:51:28.0 > +++ /home/oshogbo/p4/capsicum/lib/libc/stdio/fclose.c 2013-06-28 > 08:51:28.0 > [snip] > +int > +fdclose(FILE *fp) > +{ > + int fd, r, err; > + > + if (fp->_flags == 0) { /* not open! */ > + errno = EBADF; > + return (EOF); > + } > + > + r = 0; > + FLOCKFILE(fp); > + fd = fp->_file; > + if (fp->_close != __sclose) { > + r = EOF; > + errno = EOPNOTSUPP; > + } else if (fd < 0) { > + r = EOF; > + errno = EBADF; > + } > + if (r == EOF) { > + err = errno; > + (void)cleanfile(fp, true); > + errno = err; > + } else { > + r = cleanfile(fp, false); > + } > FUNLOCKFILE(fp); > + > + return (r == 0 ? fd : r); If a file descriptor would be returned but cleanfile() returns an error (e.g. write error on flush), the file descriptor is not returned and not closed. I think that in cases where fdclose() would be used, it is essential that the file descriptor is never closed. This means that the API needs to be different so it can report a write error but still return a file descriptor. One way to do this is to return the file descriptor by reference. Another is to expect the application to call fileno() and not return the descriptor from the new function. -- Jilles Tjoelker ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"
Re: Hello fdclose
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." .Sh RETURN VALUES -Upon successful completion 0 is returned. +The +.Fn fcloseall +function return no value. +.Pp +Upon successful completion +.Fn fclose +return 0. +Otherwise, +.Dv EOF +is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +The +.Fn fdclose +function return the file descriptor if successfull. Otherwise, .Dv EOF One of English's arcane rules is that most verbs append an 's' when used with singular subjects, so "function returns" shoud be used instead of "function return", etc. I do think for this section it would be good to combine the descriptions of fclose() and fdclose() when possible, so perhaps something like: "The fcloseall() function returns no value. Upon successful completion, fclose() returns 0 and fdclose() returns the file descriptor of the underlying file. Otherwise, EOF is returned and the global variable errno is set to indicate the error. In either case no further access to the stream is possible." This allows "in either case" to still read correctly and makes it clear it applies to both fclose() and fdclose(). .Sh ERRORS +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP The +.Fa _close +method in +.Fa stream +argument to +.Fn fdclose , +was not default. +.It Bq Er EBADF +The +.Fa stream +argument to +.Fn fdclose , +does not contains valid file descriptor. +.El +.Pp +The .Fn fclose -function +and +.Fn fdclose +functions may also fail and set .Va errno For the errors section, the first error list needs some sort of introductory text. Also, this shouldn't claim that fdclose() can return an errno value for close(2). "ERRORS The fdclose() function may will fail if: [EOPNOTSUPP] The stream to close uses a non-default close method. [EBADF]The stream is not backed by a valid file descriptor. The fclose() and fdclose() functions may also fail and set errno for any of the errors specified for fflush(3). The fclose() functino may also fail and set errno for any of the errors specified for close(2)." @@ -84,7 +130,9 @@ .Sh NOTES The .Fn fclose -function +and +.Fn fdclose +functions does not handle NULL arguments; they will result in a segmentation violation. This is intentional - it makes it easier to make sure programs written "do not handle". -- John Baldwin ___ freebsd-current@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-current To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"