fdclose

[oshogbo]

Summary

After a quite long time I would like finally finish this function. :)
The change to the perl will be very simple (I believe there is no way to mix src and ports repositories in phabricator):

--- perl-5.20.2/perlio.c
+++ perl-5.20.2/perlio.c
@@ -3122,12 +3122,7 @@
     f->_file = -1;
     return 1;
 #  elif defined(__FreeBSD__)
-    /* There may be a better way on FreeBSD:
-        - we could insert a dummy func in the _close function entry
-	f->_close = (int (*)(void *)) dummy_close;
-     */
-    f->_file = -1;
-    return 1;
+    return fdclose(f, NULL) == 0 ? 1 : 0;
 #  elif defined(__OpenBSD__)
     /* There may be a better way on OpenBSD:
         - we could insert a dummy func in the _close function entry

[jilles]

The code looks good to me.

lib/libc/stdio/fclose.3

72

Calling the argument fdp instead of fd may make this clearer.

Try:

If
.Fa fd
is not
.Dv NULL ,
the file descriptor will be written to it.

73

The words "non-standard close method" may be unclear. Perhaps say "If the stream does not have an associated file descriptor", possibly with examples like fmemopen(), funopen() and open_memstream().

These words also occur under ERRORS below.

If the stream is not open, the behaviour is not defined and need not be described in the man page.

106–107

This change seems unnecessary. It is still the case that there are two situations: success and error.

123

errno should keep its .Va markup

152

This should be .Sh HISTORY.

[oshogbo]

Update man page as jilles suggest.

[wblock]

lib/libc/stdio/fclose.3

78

Needs a comma after "descriptor".

81

"Such stream" should be "Such a stream", but it's a little confusing, maybe "This type of stream", or maybe it does not even need to be said. "functions like" is confusing, probably should be "such as". Finally, switch to active rather than passive voice by changing "could" to "can" or "is":

Streams are created with functions such as
or
This type of stream is created with functions such as
or even
This type of stream is created with

95

Several things:

1. Not necessary to use "the blah function". After the first time, just say the name of the function: "blah returns..." (no leading "The").
2. "returns no value" is somewhat ambiguous, could be misread to mean it returns null. "does not return a value" might be more clear.

So:

.Fn fcloseall
does not return a value.

110

"Shall" implies a recommendation. Probably better as "will".

136

(Missing an "it" after "makes").
Use a full stop rather than an emdash:

This is intentional.
It makes it easier to make sure programs written under

[jhb]

The code changes look fine to me (I'll defer to others on the manpage bits).

[oshogbo]

Update man page as wblock suggest. Thanks!

[oshogbo]

@wblock

"Shall" implies a recommendation. Probably better as "will".

I see this is a problematic one.
In first version i had "will" but Bruce suggest me that I should changed it.

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).

[oshogbo]

Missed one suggested by @wblock.

[wblock]

lib/libc/stdio/fclose.3

38

No comma after "descriptor" here. (This might be due to phabricator "helping" by mixing up diffs. I'll try to include some context to make this easier.)

38 the file descriptor will be written to it.

41

Typo: s/arguemnt/argument/

42

Needs a comma after this "descriptor", where the pause is located:

42 If the stream does not have an associated file descriptor,

99

Start the new sentence on a new line:

99  This is intentional.

100 It makes it easier to make sure programs written under

[wblock]

In D2697#51201, @oshogbo wrote:

@wblock

"Shall" implies a recommendation. Probably better as "will".

I see this is a problematic one.
In first version i had "will" but Bruce suggest me that I should changed it.

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).

All right, let's eliminate the stilted language altogether:

Original:

The
​.Fn fdclose
​function shall fail if:

New:

.Fn fdclose
fails if:

[oshogbo]

wblock suggestions.

I also add missing .El.

[oshogbo]

Compromise about shall and will :)

[wblock]

lib/libc/stdio/fclose.3

41

Oops, I missed the other typo:
s/diffrent/different/

[oshogbo]

s/diffrent/different/

[wblock]

Man page looks good. Please test with igor -R fclose.3 | less -RS and mandoc -Tlint fclose.3 before commit.