[PATCH] open_wmemstream(3): Describe (as part of fmemopen.3)

[PATCH] open_wmemstream(3): Describe (as part of fmemopen.3)

[Petr Baudis]

Signed-off-by: Petr Baudis <pasky-AlSwsSmVLrQ@public.gmane.org>

diff --git a/man3/fmemopen.3 b/man3/fmemopen.3
index 47187b6..add9d5f 100644
--- a/man3/fmemopen.3
+++ b/man3/fmemopen.3
@@ -2,9 +2,9 @@
 .\" and Copyright 2005 Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
 .\" Distributed under the GPL.
 .\"
-.TH FMEMOPEN 3 2008-10-12 "GNU" "Linux Programmer's Manual"
+.TH FMEMOPEN 3 2008-12-04 "GNU" "Linux Programmer's Manual"
 .SH NAME
-fmemopen, open_memstream \-  open memory as stream
+fmemopen, open_memstream, open_wmemstream \-  open memory as stream
 .SH SYNOPSIS
 .B #define _GNU_SOURCE
 .br
@@ -14,6 +14,10 @@ fmemopen, open_memstream \-  open memory as stream
 .BI "const char *" mode ");"
 .sp
 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
+.sp
+.B #include <wchar.h>
+.br
+.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
 .SH DESCRIPTION
 The
 .BR fmemopen ()
@@ -138,11 +142,16 @@ or
 Moving the file position past the end
 of the data already written fills the intervening space with
 zeros.
+
+The
+.BR open_wmemstream ()
+is similar but operates on wide characters instead of bytes.
 .SH "RETURN VALUE"
 Upon successful completion
-.BR fmemopen ()
-and
+.BR fmemopen (),
 .BR open_memstream ()
+and
+.BR open_wmemstream ()
 return a
 .I FILE
 pointer.
diff --git a/man3/open_wmemstream.3 b/man3/open_wmemstream.3
new file mode 100644
index 0000000..afcad2f
--- /dev/null
+++ b/man3/open_wmemstream.3
@@ -0,0 +1 @@
+.so man3/fmemopen.3
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open_wmemstream(3): Describe (as part of fmemopen.3)

[Michael Kerrisk]

Hi Petr,

Thanks for another good patch.  One thing (since you may be submitting
future patches, I hope): the subject line would be better as something
like:

[PATCH] fmemopen.3: Add description of open_wmemstream(3)

Other comments below.

On Thu, Dec 4, 2008 at 6:23 PM, Petr Baudis <pasky-AlSwsSmVLrQ@public.gmane.org> wrote:
> Signed-off-by: Petr Baudis <pasky-AlSwsSmVLrQ@public.gmane.org>
>
> diff --git a/man3/fmemopen.3 b/man3/fmemopen.3
> index 47187b6..add9d5f 100644
> --- a/man3/fmemopen.3
> +++ b/man3/fmemopen.3
> @@ -2,9 +2,9 @@
>  .\" and Copyright 2005 Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>  .\" Distributed under the GPL.

This time I added an in-source changelog entry listing you!

>  .\"
> -.TH FMEMOPEN 3 2008-10-12 "GNU" "Linux Programmer's Manual"
> +.TH FMEMOPEN 3 2008-12-04 "GNU" "Linux Programmer's Manual"
>  .SH NAME
> -fmemopen, open_memstream \-  open memory as stream
> +fmemopen, open_memstream, open_wmemstream \-  open memory as stream
>  .SH SYNOPSIS
>  .B #define _GNU_SOURCE
>  .br
> @@ -14,6 +14,10 @@ fmemopen, open_memstream \-  open memory as stream
>  .BI "const char *" mode ");"
>  .sp
>  .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
> +.sp

I imagine you were aware that _GNU_SOURCE is required.  Convention
here is that since we are listing new header files, then we should
again list the required FTMs, even if they are the same as for a
previous function.  So I added

+.B #define _GNU_SOURCE

here.

> +.B #include <wchar.h>
> +.br
> +.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
>  .SH DESCRIPTION
>  The
>  .BR fmemopen ()
> @@ -138,11 +142,16 @@ or
>  Moving the file position past the end
>  of the data already written fills the intervening space with
>  zeros.
> +
> +The
> +.BR open_wmemstream ()
> +is similar but operates on wide characters instead of bytes.
>  .SH "RETURN VALUE"
>  Upon successful completion
> -.BR fmemopen ()
> -and
> +.BR fmemopen (),
>  .BR open_memstream ()
> +and
> +.BR open_wmemstream ()
>  return a
>  .I FILE
>  pointer.

One thing that also is good to include is version information.
Unfortunately the page was lacking a VERSIONS section, when it really
should have had one.  I added the following:

diff --git a/man3/fmemopen.3 b/man3/fmemopen.3
index 2b87b69..0d540b5 100644
--- a/man3/fmemopen.3
+++ b/man3/fmemopen.3
@@ -160,6 +160,13 @@ pointer.
 Otherwise, NULL is returned and the global variable
 .I errno
 is set to indicate the error.
+.SH VERSIONS
+.BR fmemopen ()
+is available since glibc 2.2.
+.BR open_memstream ()
+is available since glibc 2.0.
+.BR open_wmemstream ()
+is available since glibc 2.4.
 .SH "CONFORMING TO"
 These functions are GNU extensions.
 .\" Jan 06: But they appear to be going up for standardization by

Look right to you?

> diff --git a/man3/open_wmemstream.3 b/man3/open_wmemstream.3
> new file mode 100644
> index 0000000..afcad2f
> --- /dev/null
> +++ b/man3/open_wmemstream.3
> @@ -0,0 +1 @@
> +.so man3/fmemopen.3

It's rare that I get a patch that remembers to do pieces like this.  Thanks!

These changes are applied for 3.15.  Thanks!

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open_wmemstream(3): Describe (as part of fmemopen.3)

[Petr Baudis]

  Hi,

  thanks for all the comments.

On Fri, Dec 05, 2008 at 12:53:26PM -0500, Michael Kerrisk wrote:
> One thing that also is good to include is version information.
> Unfortunately the page was lacking a VERSIONS section, when it really
> should have had one.  I added the following:
> 
> diff --git a/man3/fmemopen.3 b/man3/fmemopen.3
> index 2b87b69..0d540b5 100644
> --- a/man3/fmemopen.3
> +++ b/man3/fmemopen.3
> @@ -160,6 +160,13 @@ pointer.
>  Otherwise, NULL is returned and the global variable
>  .I errno
>  is set to indicate the error.
> +.SH VERSIONS
> +.BR fmemopen ()
> +is available since glibc 2.2.
> +.BR open_memstream ()
> +is available since glibc 2.0.
> +.BR open_wmemstream ()
> +is available since glibc 2.4.
>  .SH "CONFORMING TO"
>  These functions are GNU extensions.
>  .\" Jan 06: But they appear to be going up for standardization by
> 
> Look right to you?

open_wmemstream() yes. fmemopen() is much much older (bear in mind that
there was old GNU stdio library before GNU libio, and it contained
fmemopen() too - I have no idea which libc version "Thu Aug 8 00:39:56
1991 +0000" is in, though) and same for open_memstream (Sun Jul 28
00:22:19 1991 +0000).

-- 
				Petr "Pasky" Baudis
People who take cold baths never have rheumatism, but they have
cold baths.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open_wmemstream(3): Describe (as part of fmemopen.3)

[Michael Kerrisk]

On Sat, Dec 6, 2008 at 4:54 AM, Petr Baudis <pasky-AlSwsSmVLrQ@public.gmane.org> wrote:
>  Hi,
>
>  thanks for all the comments.
>
> On Fri, Dec 05, 2008 at 12:53:26PM -0500, Michael Kerrisk wrote:
>> One thing that also is good to include is version information.
>> Unfortunately the page was lacking a VERSIONS section, when it really
>> should have had one.  I added the following:
>>
>> diff --git a/man3/fmemopen.3 b/man3/fmemopen.3
>> index 2b87b69..0d540b5 100644
>> --- a/man3/fmemopen.3
>> +++ b/man3/fmemopen.3
>> @@ -160,6 +160,13 @@ pointer.
>>  Otherwise, NULL is returned and the global variable
>>  .I errno
>>  is set to indicate the error.
>> +.SH VERSIONS
>> +.BR fmemopen ()
>> +is available since glibc 2.2.
>> +.BR open_memstream ()
>> +is available since glibc 2.0.
>> +.BR open_wmemstream ()
>> +is available since glibc 2.4.
>>  .SH "CONFORMING TO"
>>  These functions are GNU extensions.
>>  .\" Jan 06: But they appear to be going up for standardization by
>>
>> Look right to you?
>
> open_wmemstream() yes. fmemopen() is much much older (bear in mind that
> there was old GNU stdio library before GNU libio, and it contained
> fmemopen() too - I have no idea which libc version "Thu Aug 8 00:39:56
> 1991 +0000" is in, though) and same for open_memstream (Sun Jul 28
> 00:22:19 1991 +0000).

Thanks for catching that.  I made the text

.BR fmemopen ()
and
.BR open_memstream ()
were already available in glibc 1.0.x.
.BR open_wmemstream ()
is available since glibc 2.4.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html