linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 1/2] system_data_types.7: Add 'off_t'
@ 2020-10-05 22:12 Alejandro Colomar
  2020-10-05 22:12 ` [PATCH 2/2] off_t.3: New link to system_data_types(7) Alejandro Colomar
  2020-10-07  6:53 ` [PATCH 1/2] system_data_types.7: Add 'off_t' Michael Kerrisk (man-pages)
  0 siblings, 2 replies; 8+ messages in thread
From: Alejandro Colomar @ 2020-10-05 22:12 UTC (permalink / raw)
  To: mtk.manpages; +Cc: Alejandro Colomar, linux-man, libc-alpha, linux-kernel

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 50 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index b8cbc8ffe..916efef08 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -629,6 +629,56 @@ C99 and later; POSIX.1-2001 and later.
 See also:
 .BR lldiv (3)
 .RE
+.\"------------------------------------- off_t ------------------------/
+.TP
+.I off_t
+.RS
+Include:
+.IR <sys/types.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <fcntl.h> ,
+.IR <stdio.h> ,
+.IR <sys/mman.h> ,
+.IR <sys/stat.h.h> ,
+or
+.IR <unistd.h> .
+.PP
+Used for file sizes.
+According to POSIX,
+this shall be a signed integer type.
+.PP
+Versions:
+.I <aio.h>
+and
+.I <stdio.h>
+define
+.I off_t
+since POSIX.1-2008.
+.PP
+Conforming to:
+POSIX.1-2001 and later.
+.PP
+See also:
+.BR fallocate (2),
+.BR lseek (2),
+.BR mmap (2),
+.BR mmap2 (2),
+.BR posix_fadvise (2),
+.BR pread (2),
+.BR preadv (2),
+.BR truncate (2),
+.BR fseeko (3),
+.BR getdirentries (3),
+.BR lockf (3),
+.BR posix_fallocate (3)
+.\".PP		TODO: loff_t, off64_t
+.\"See also the
+.\".I loff_t
+.\"and
+.\".I off64_t
+.\"types in this page.
+.RE
 .\"------------------------------------- pid_t ------------------------/
 .TP
 .I pid_t
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* [PATCH 2/2] off_t.3: New link to system_data_types(7)
  2020-10-05 22:12 [PATCH 1/2] system_data_types.7: Add 'off_t' Alejandro Colomar
@ 2020-10-05 22:12 ` Alejandro Colomar
  2020-10-07  6:53   ` Michael Kerrisk (man-pages)
  2020-10-07  6:53 ` [PATCH 1/2] system_data_types.7: Add 'off_t' Michael Kerrisk (man-pages)
  1 sibling, 1 reply; 8+ messages in thread
From: Alejandro Colomar @ 2020-10-05 22:12 UTC (permalink / raw)
  To: mtk.manpages; +Cc: Alejandro Colomar, linux-man, libc-alpha, linux-kernel

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/off_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/off_t.3

diff --git a/man3/off_t.3 b/man3/off_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/off_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* Re: [PATCH 1/2] system_data_types.7: Add 'off_t'
  2020-10-05 22:12 [PATCH 1/2] system_data_types.7: Add 'off_t' Alejandro Colomar
  2020-10-05 22:12 ` [PATCH 2/2] off_t.3: New link to system_data_types(7) Alejandro Colomar
@ 2020-10-07  6:53 ` Michael Kerrisk (man-pages)
  2020-10-27 10:23   ` Alejandro Colomar
  1 sibling, 1 reply; 8+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-07  6:53 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha, linux-kernel

On 10/6/20 12:12 AM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Hi Alex,

Thanks, patch applied. And I trimmed the "See also" a little.
I'd hold off on documenting loff_t and off64_t for the 
moment. As you note in another mail, the *lseek* man page
situation is a bit of a mess. I'm not yet sure what to do.

Thanks,

Michael

> ---
>  man7/system_data_types.7 | 50 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index b8cbc8ffe..916efef08 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -629,6 +629,56 @@ C99 and later; POSIX.1-2001 and later.
>  See also:
>  .BR lldiv (3)
>  .RE
> +.\"------------------------------------- off_t ------------------------/
> +.TP
> +.I off_t
> +.RS
> +Include:
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <aio.h> ,
> +.IR <fcntl.h> ,
> +.IR <stdio.h> ,
> +.IR <sys/mman.h> ,
> +.IR <sys/stat.h.h> ,
> +or
> +.IR <unistd.h> .
> +.PP
> +Used for file sizes.
> +According to POSIX,
> +this shall be a signed integer type.
> +.PP
> +Versions:
> +.I <aio.h>
> +and
> +.I <stdio.h>
> +define
> +.I off_t
> +since POSIX.1-2008.
> +.PP
> +Conforming to:
> +POSIX.1-2001 and later.
> +.PP
> +See also:
> +.BR fallocate (2),
> +.BR lseek (2),
> +.BR mmap (2),
> +.BR mmap2 (2),
> +.BR posix_fadvise (2),
> +.BR pread (2),
> +.BR preadv (2),
> +.BR truncate (2),
> +.BR fseeko (3),
> +.BR getdirentries (3),
> +.BR lockf (3),
> +.BR posix_fallocate (3)
> +.\".PP		TODO: loff_t, off64_t
> +.\"See also the
> +.\".I loff_t
> +.\"and
> +.\".I off64_t
> +.\"types in this page.
> +.RE
>  .\"------------------------------------- pid_t ------------------------/
>  .TP
>  .I pid_t
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH 2/2] off_t.3: New link to system_data_types(7)
  2020-10-05 22:12 ` [PATCH 2/2] off_t.3: New link to system_data_types(7) Alejandro Colomar
@ 2020-10-07  6:53   ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 8+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-07  6:53 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha, linux-kernel

On 10/6/20 12:12 AM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Thanks, Alex. Patch applied.

Cheers,

Michael

> ---
>  man3/off_t.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/off_t.3
> 
> diff --git a/man3/off_t.3 b/man3/off_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/off_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH 1/2] system_data_types.7: Add 'off_t'
  2020-10-07  6:53 ` [PATCH 1/2] system_data_types.7: Add 'off_t' Michael Kerrisk (man-pages)
@ 2020-10-27 10:23   ` Alejandro Colomar
  2020-10-27 13:47     ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 8+ messages in thread
From: Alejandro Colomar @ 2020-10-27 10:23 UTC (permalink / raw)
  To: Michael Kerrisk (man-pages); +Cc: linux-man, libc-alpha, linux-kernel

Hi Michael,

On 2020-10-07 08:53, Michael Kerrisk (man-pages) wrote:
> On 10/6/20 12:12 AM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> 
> Hi Alex,
> 
> Thanks, patch applied. And I trimmed the "See also" a little.
> I'd hold off on documenting loff_t and off64_t for the
> moment. As you note in another mail, the *lseek* man page
> situation is a bit of a mess. I'm not yet sure what to do.


I saw a TODO in the page about loff_t.
Just wanted to ping you in case you forgot about it (I did).

Thanks,

Alex

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH 1/2] system_data_types.7: Add 'off_t'
  2020-10-27 10:23   ` Alejandro Colomar
@ 2020-10-27 13:47     ` Michael Kerrisk (man-pages)
  2020-10-27 15:25       ` Alejandro Colomar
  0 siblings, 1 reply; 8+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-27 13:47 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha, linux-kernel

On 10/27/20 11:23 AM, Alejandro Colomar wrote:
> Hi Michael,
> 
> On 2020-10-07 08:53, Michael Kerrisk (man-pages) wrote:
>> On 10/6/20 12:12 AM, Alejandro Colomar wrote:
>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>>
>> Hi Alex,
>>
>> Thanks, patch applied. And I trimmed the "See also" a little.
>> I'd hold off on documenting loff_t and off64_t for the
>> moment. As you note in another mail, the *lseek* man page
>> situation is a bit of a mess. I'm not yet sure what to do.
> 
> 
> I saw a TODO in the page about loff_t.
> Just wanted to ping you in case you forgot about it (I did).

I didn't forget it exactly. I just don't know that I have the
inclination to do anything about the messy *llseek* pages.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH 1/2] system_data_types.7: Add 'off_t'
  2020-10-27 13:47     ` Michael Kerrisk (man-pages)
@ 2020-10-27 15:25       ` Alejandro Colomar
  2020-10-27 16:22         ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 8+ messages in thread
From: Alejandro Colomar @ 2020-10-27 15:25 UTC (permalink / raw)
  To: Michael Kerrisk (man-pages); +Cc: linux-man, libc-alpha, linux-kernel



On 2020-10-27 14:47, Michael Kerrisk (man-pages) wrote:
> On 10/27/20 11:23 AM, Alejandro Colomar wrote:
>> Hi Michael,
>>
>> On 2020-10-07 08:53, Michael Kerrisk (man-pages) wrote:
>>> On 10/6/20 12:12 AM, Alejandro Colomar wrote:
>>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>>>
>>> Hi Alex,
>>>
>>> Thanks, patch applied. And I trimmed the "See also" a little.
>>> I'd hold off on documenting loff_t and off64_t for the
>>> moment. As you note in another mail, the *lseek* man page
>>> situation is a bit of a mess. I'm not yet sure what to do.
>>
>>
>> I saw a TODO in the page about loff_t.
>> Just wanted to ping you in case you forgot about it (I did).
> 
> I didn't forget it exactly. I just don't know that I have the
> inclination to do anything about the messy *llseek* pages.
> 
> Thanks,
> 
> Michael
> 
> 


Hi Michael,

I've been reading them to add loff_t and off64_t to sys_data_types.
Now that I've read them (not too deep),
I think that lseek64(3) is good enough,
and maybe we should look for small details
missing there but present on the others,
and merge those to lseek64.3.
And then keep links in the other pages pointing to lseek64.3.

Any thoughts?

Cheers,

A

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH 1/2] system_data_types.7: Add 'off_t'
  2020-10-27 15:25       ` Alejandro Colomar
@ 2020-10-27 16:22         ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 8+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-27 16:22 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: linux-man, libc-alpha, lkml

Hi Alex,

On Tue, 27 Oct 2020 at 16:25, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
>
>
> On 2020-10-27 14:47, Michael Kerrisk (man-pages) wrote:
> > On 10/27/20 11:23 AM, Alejandro Colomar wrote:
> >> Hi Michael,
> >>
> >> On 2020-10-07 08:53, Michael Kerrisk (man-pages) wrote:
> >>> On 10/6/20 12:12 AM, Alejandro Colomar wrote:
> >>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> >>>
> >>> Hi Alex,
> >>>
> >>> Thanks, patch applied. And I trimmed the "See also" a little.
> >>> I'd hold off on documenting loff_t and off64_t for the
> >>> moment. As you note in another mail, the *lseek* man page
> >>> situation is a bit of a mess. I'm not yet sure what to do.
> >>
> >>
> >> I saw a TODO in the page about loff_t.
> >> Just wanted to ping you in case you forgot about it (I did).
> >
> > I didn't forget it exactly. I just don't know that I have the
> > inclination to do anything about the messy *llseek* pages.
> >
> > Thanks,
> >
> > Michael
> >
> >
>
>
> Hi Michael,
>
> I've been reading them to add loff_t and off64_t to sys_data_types.
> Now that I've read them (not too deep),
> I think that lseek64(3) is good enough,
> and maybe we should look for small details
> missing there but present on the others,
> and merge those to lseek64.3.
> And then keep links in the other pages pointing to lseek64.3.
>
> Any thoughts?

Those pages have a long history, and I confess to not understanding
all of the details of the history. Looking more closely at the pages,
I think they are good enough. Let's leave them alone. (I did apply one
patch just now.)

Thinking about it further, I don't think it's necessary to document
loff_t in system_data_types(7). No APIs in the current glibc headers
even use loff_t, as far as I can see. I'm not sure that 'off64_t'
really needs documenting there either.

Thanks,

Michael





--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2020-10-27 16:23 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-05 22:12 [PATCH 1/2] system_data_types.7: Add 'off_t' Alejandro Colomar
2020-10-05 22:12 ` [PATCH 2/2] off_t.3: New link to system_data_types(7) Alejandro Colomar
2020-10-07  6:53   ` Michael Kerrisk (man-pages)
2020-10-07  6:53 ` [PATCH 1/2] system_data_types.7: Add 'off_t' Michael Kerrisk (man-pages)
2020-10-27 10:23   ` Alejandro Colomar
2020-10-27 13:47     ` Michael Kerrisk (man-pages)
2020-10-27 15:25       ` Alejandro Colomar
2020-10-27 16:22         ` Michael Kerrisk (man-pages)

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).