diff mbox series

[1/2] system_data_types.7: Add 'off_t'

Message ID 20201005221247.13065-1-colomar.6.4.3@gmail.com
State New
Headers show
Series [1/2] system_data_types.7: Add 'off_t' | expand

Commit Message

Alejandro Colomar Oct. 5, 2020, 10:12 p.m. UTC
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 50 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

Comments

Michael Kerrisk \(man-pages\) Oct. 7, 2020, 6:53 a.m. UTC | #1
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
>
Alejandro Colomar Oct. 27, 2020, 10:23 a.m. UTC | #2
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
Michael Kerrisk \(man-pages\) Oct. 27, 2020, 1:47 p.m. UTC | #3
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
Alejandro Colomar Oct. 27, 2020, 3:25 p.m. UTC | #4
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
diff mbox series

Patch

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