[PATCH 0/6] Add loff_t & off64_t, and update off_t

[PATCH 0/6] Add loff_t & off64_t, and update off_t

[Alejandro Colomar]

Hi M,

I added some details to off_t,
and added loff_t and off64_t to the page.

Maybe you would like to improve some wording on these patches.
There are a few lines that don't convince me fully...

I might start working on fixing the messy *lseek* pages.

Cheers,

A


Alejandro Colomar (6):
  system_data_types.7: off_t: SEE ALSO: Uncomment loff_t, off64_t
  system_data_types.7: off_t: Add note about _FILE_OFFSET_BITS
  system_data_types.7: Add 'loff_t'
  loff_t.3: New link to system_data_types(7)
  system_data_types.7: Add 'off64_t'
  off64_t.3: New link to system_data_types(7)

 man3/loff_t.3            |  1 +
 man3/off64_t.3           |  1 +
 man7/system_data_types.7 | 76 ++++++++++++++++++++++++++++++++++++----
 3 files changed, 71 insertions(+), 7 deletions(-)
 create mode 100644 man3/loff_t.3
 create mode 100644 man3/off64_t.3

-- 
2.28.0

[PATCH 1/6] system_data_types.7: off_t: SEE ALSO: Uncomment loff_t, off64_t

[Alejandro Colomar]

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index e93495eea..c02782ed8 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -769,12 +769,12 @@ POSIX.1-2001 and later.
 .\" .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.
+.PP
+See also the
+.I loff_t
+and
+.I off64_t
+types in this page.
 .RE
 .\"------------------------------------- pid_t ------------------------/
 .TP
-- 
2.28.0

[PATCH 2/6] system_data_types.7: off_t: Add note about _FILE_OFFSET_BITS

[Alejandro Colomar]

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index c02782ed8..e846de68b 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -756,6 +756,11 @@ since POSIX.1-2008.
 .IR "Conforming to" :
 POSIX.1-2001 and later.
 .PP
+.IR Notes :
+On some architectures,
+the width of this type can be controlled with the feature test macro
+.BR _FILE_OFFSET_BITS .
+.PP
 .IR "See also" :
 .\" .BR fallocate (2),
 .BR lseek (2),
@@ -768,7 +773,8 @@ POSIX.1-2001 and later.
 .BR fseeko (3),
 .\" .BR getdirentries (3),
 .BR lockf (3),
-.BR posix_fallocate (3)
+.BR posix_fallocate (3),
+.BR feature_test_macros (7)
 .PP
 See also the
 .I loff_t
-- 
2.28.0

[PATCH 3/6] system_data_types.7: Add 'loff_t'

[Alejandro Colomar]

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index e846de68b..313cf059e 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -726,6 +726,31 @@ C99 and later; POSIX.1-2001 and later.
 .IR "See also" :
 .BR lldiv (3)
 .RE
+.\"------------------------------------- loff_t -----------------------/
+.TP
+.I loff_t
+.RS
+.IR Include :
+.IR <sys/types.h> .
+.PP
+Used for file sizes.
+It is a 64-bit signed integer type.
+.PP
+.IR "Conforming to" :
+Present in glibc.
+It is not standardized by the C language standard nor POSIX.
+.PP
+.IR "See also" :
+.BR copy_file_range (2),
+.BR llseek (2),
+.BR splice (2)
+.PP
+See also the
+.I off64_t
+and
+.I off_t
+types in this page.
+.RE
 .\"------------------------------------- off_t ------------------------/
 .TP
 .I off_t
-- 
2.28.0

[PATCH 4/6] loff_t.3: New link to system_data_types(7)

[Alejandro Colomar]

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

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

[PATCH 5/6] system_data_types.7: Add 'off64_t'

[Alejandro Colomar]

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

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 313cf059e..0558060d3 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -751,6 +751,37 @@ and
 .I off_t
 types in this page.
 .RE
+.\"------------------------------------- off64_t ----------------------/
+.TP
+.I off64_t
+.RS
+.IR Include :
+.IR <sys/types.h> .
+.PP
+Used for file sizes.
+It is a 64-bit signed integer type.
+.PP
+.IR "Conforming to" :
+Present in glibc.
+It is not standardized by the C language standard nor POSIX.
+.PP
+.IR Notes :
+The feature test macro
+.B _LARGEFILE64_SOURCE
+has to be defined for this type to be available.
+.PP
+.IR "See also" :
+.BR readahead (2),
+.BR sync_file_range (2),
+.BR lseek64 (3),
+.BR feature_test_macros (7)
+.PP
+See also the
+.I loff_t
+and
+.I off_t
+types in this page.
+.RE
 .\"------------------------------------- off_t ------------------------/
 .TP
 .I off_t
-- 
2.28.0

[PATCH 6/6] off64_t.3: New link to system_data_types(7)

[Alejandro Colomar]

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

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

Re: [PATCH 0/6] Add loff_t & off64_t, and update off_t

[Michael Kerrisk (man-pages)]

Hi Alex,

On 10/27/20 5:21 PM, Alejandro Colomar wrote:
> Hi M,
> 
> I added some details to off_t,
> and added loff_t and off64_t to the page.
> 
> Maybe you would like to improve some wording on these patches.
> There are a few lines that don't convince me fully...
> 
> I might start working on fixing the messy *lseek* pages.

See my other mail. On reflection, I think that those pages are
in a "good enough" state.

And, you raced off a bit too quick for me. I definitely
think loff_t should not be added. And I'm pretty doubtful
about adding off64_t as well.

I've applied patch 2 in this series.

Thanks,

Michael


> Alejandro Colomar (6):
>   system_data_types.7: off_t: SEE ALSO: Uncomment loff_t, off64_t
>   system_data_types.7: off_t: Add note about _FILE_OFFSET_BITS
>   system_data_types.7: Add 'loff_t'
>   loff_t.3: New link to system_data_types(7)
>   system_data_types.7: Add 'off64_t'
>   off64_t.3: New link to system_data_types(7)
> 
>  man3/loff_t.3            |  1 +
>  man3/off64_t.3           |  1 +
>  man7/system_data_types.7 | 76 ++++++++++++++++++++++++++++++++++++----
>  3 files changed, 71 insertions(+), 7 deletions(-)
>  create mode 100644 man3/loff_t.3
>  create mode 100644 man3/off64_t.3
> 


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

Re: [PATCH 2/6] system_data_types.7: off_t: Add note about _FILE_OFFSET_BITS

[Michael Kerrisk (man-pages)]

Applied!

On 10/27/20 5:21 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index c02782ed8..e846de68b 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -756,6 +756,11 @@ since POSIX.1-2008.
>  .IR "Conforming to" :
>  POSIX.1-2001 and later.
>  .PP
> +.IR Notes :
> +On some architectures,
> +the width of this type can be controlled with the feature test macro
> +.BR _FILE_OFFSET_BITS .
> +.PP
>  .IR "See also" :
>  .\" .BR fallocate (2),
>  .BR lseek (2),
> @@ -768,7 +773,8 @@ POSIX.1-2001 and later.
>  .BR fseeko (3),
>  .\" .BR getdirentries (3),
>  .BR lockf (3),
> -.BR posix_fallocate (3)
> +.BR posix_fallocate (3),
> +.BR feature_test_macros (7)
>  .PP
>  See also the
>  .I loff_t
> 


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

Re: [PATCH 5/6] system_data_types.7: Add 'off64_t'

[Michael Kerrisk (man-pages)]

On 10/27/20 5:21 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 31 +++++++++++++++++++++++++++++++
>  1 file changed, 31 insertions(+)

I think we shouldn't document this.
See https://www.opengroup.org/platform/lfs.html

This type, and the _LARGEFILE64_SOURCE macro date
to a time of transition in the 1990s. It's largely
irrelevant now, i think.

Thanks,

Michael

> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 313cf059e..0558060d3 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -751,6 +751,37 @@ and
>  .I off_t
>  types in this page.
>  .RE
> +.\"------------------------------------- off64_t ----------------------/
> +.TP
> +.I off64_t
> +.RS
> +.IR Include :
> +.IR <sys/types.h> .
> +.PP
> +Used for file sizes.
> +It is a 64-bit signed integer type.
> +.PP
> +.IR "Conforming to" :
> +Present in glibc.
> +It is not standardized by the C language standard nor POSIX.
> +.PP
> +.IR Notes :
> +The feature test macro
> +.B _LARGEFILE64_SOURCE
> +has to be defined for this type to be available.
> +.PP
> +.IR "See also" :
> +.BR readahead (2),
> +.BR sync_file_range (2),
> +.BR lseek64 (3),
> +.BR feature_test_macros (7)
> +.PP
> +See also the
> +.I loff_t
> +and
> +.I off_t
> +types in this page.
> +.RE
>  .\"------------------------------------- off_t ------------------------/
>  .TP
>  .I off_t
> 


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