[PATCH] tmpfs(5): document current mount options

[PATCH] tmpfs(5): document current mount options

[Mike Frysinger]

Some of this content is moved from the mount(8) man page.
Style was based on proc(5) sections.

Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
---
 man5/tmpfs.5 | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 73 insertions(+), 4 deletions(-)

diff --git a/man5/tmpfs.5 b/man5/tmpfs.5
index 5bdc8939c7f7..85f7ab5f26d1 100644
--- a/man5/tmpfs.5
+++ b/man5/tmpfs.5
@@ -51,10 +51,6 @@ filesystem has the following properties:
 The filesystem can employ swap space when physical memory pressure
 demands it.
 .IP *
-The
-.I size
-option can be used to specify an upper limit on the size of the filesystem.
-(The default size is half of the available RAM size.)
 The filesystem consumes only as much physical memory and swap space
 as is required to store the current contents of the filesystem.
 .IP *
@@ -66,6 +62,79 @@ the filesystem size can be changed
 If a
 .B tmpfs
 filesystem is unmounted, its contents are discarded (lost).
+.\" See mm/shmem.c:shmem_parse_options for options it supports.
+.SS Mount options
+The
+.B tmpfs
+filesystem supports the following mount options:
+.TP
+.BR size "=\fIbytes\fP"
+Specify an upper limit on the size of the filesystem.
+The size is given in bytes, and rounded up to entire pages.
+
+The size may have a
+.BR k ,
+.BR m ,
+or
+.B g
+suffix for Ki, Mi, Gi (binary kilo (kibi), binary mega (mebi) and binary giga
+(gibi)).
+
+The size may also have a % suffix to limit this instance to a percentage of
+physical RAM.
+
+The default, when neither size nor nr_blocks is specified, is size=50%.
+.TP
+.BR nr_blocks "=\fIblocks\fP"
+The same as
+.BR size ,
+but in blocks of PAGE_CACHE_SIZE.
+
+Blocks may be specified with
+.BR k ,
+.BR m ,
+or
+.B g
+suffixes like
+.BR size ,
+but not a % suffix.
+.TP
+.BR nr_inodes "=\fIinodes\fP"
+The maximum number of inodes for this instance.
+The default is half of the number of your physical RAM pages, or (on a
+machine with highmem) the number of lowmem RAM pages, whichever is smaller.
+
+Inodes may be specified with
+.BR k ,
+.BR m ,
+or
+.B g
+suffixes like
+.BR size ,
+but not a % suffix.
+.TP
+.BR mode "=\fImode\fP"
+Set initial permissions of the root directory.
+.TP
+.BR gid "=\fIgid\fP (since Linux 2.5.7)"
+.\" Technically this is also in some version of Linux 2.4.
+.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096
+Set the initial group ID of the root directory.
+.TP
+.BR uid "=\fIuid\fP (since Linux 2.5.7)"
+.\" Technically this is also in some version of Linux 2.4.
+.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096
+Set the initial user ID of the root directory.
+.TP
+.BR huge "=\fI[never|always|within_size|advise|deny|force]\fR (since Linux 4.7.0)"
+.\" commit 5a6e75f8110c97e2a5488894d4e922187e6cb343
+Set the huge table memory allocation policy for all files in this instance (if
+CONFIG_TRANSPARENT_HUGE_PAGECACHE is enabled).
+.TP
+.BR mpol "=\fI[default|prefer:Node|bind:NodeList|interleave|interleave:NodeList]\fR (since Linux 2.6.15)"
+.\" commit 7339ff8302fd70aabf5f1ae26e0c4905fa74a495
+Set the NUMA memory allocation policy for all files in this instance (if
+CONFIG_NUMA is enabled).
 .SH VERSIONS
 The
 .B tmpfs
-- 
2.15.1

--
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] tmpfs(5): document current mount options

[Michael Kerrisk (man-pages)]

Hello Mike,

On 01/27/2018 10:59 AM, Mike Frysinger wrote:
> Some of this content is moved from the mount(8) man page.
> Style was based on proc(5) sections.

Thanks. I've applied this. I also added some further details for the
'mpol' and 'huge' options, largely drawn from kernel Documentation
files. Could you take a quick look at that new content?

Is there any other text for mount(8) that should be imported to
tmpfs(5)?

Cheers,

Michael
 
> Signed-off-by: Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>
> ---
>  man5/tmpfs.5 | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 73 insertions(+), 4 deletions(-)
> 
> diff --git a/man5/tmpfs.5 b/man5/tmpfs.5
> index 5bdc8939c7f7..85f7ab5f26d1 100644
> --- a/man5/tmpfs.5
> +++ b/man5/tmpfs.5
> @@ -51,10 +51,6 @@ filesystem has the following properties:
>  The filesystem can employ swap space when physical memory pressure
>  demands it.
>  .IP *
> -The
> -.I size
> -option can be used to specify an upper limit on the size of the filesystem.
> -(The default size is half of the available RAM size.)
>  The filesystem consumes only as much physical memory and swap space
>  as is required to store the current contents of the filesystem.
>  .IP *
> @@ -66,6 +62,79 @@ the filesystem size can be changed
>  If a
>  .B tmpfs
>  filesystem is unmounted, its contents are discarded (lost).
> +.\" See mm/shmem.c:shmem_parse_options for options it supports.
> +.SS Mount options
> +The
> +.B tmpfs
> +filesystem supports the following mount options:
> +.TP
> +.BR size "=\fIbytes\fP"
> +Specify an upper limit on the size of the filesystem.
> +The size is given in bytes, and rounded up to entire pages.
> +
> +The size may have a
> +.BR k ,
> +.BR m ,
> +or
> +.B g
> +suffix for Ki, Mi, Gi (binary kilo (kibi), binary mega (mebi) and binary giga
> +(gibi)).
> +
> +The size may also have a % suffix to limit this instance to a percentage of
> +physical RAM.
> +
> +The default, when neither size nor nr_blocks is specified, is size=50%.
> +.TP
> +.BR nr_blocks "=\fIblocks\fP"
> +The same as
> +.BR size ,
> +but in blocks of PAGE_CACHE_SIZE.
> +
> +Blocks may be specified with
> +.BR k ,
> +.BR m ,
> +or
> +.B g
> +suffixes like
> +.BR size ,
> +but not a % suffix.
> +.TP
> +.BR nr_inodes "=\fIinodes\fP"
> +The maximum number of inodes for this instance.
> +The default is half of the number of your physical RAM pages, or (on a
> +machine with highmem) the number of lowmem RAM pages, whichever is smaller.
> +
> +Inodes may be specified with
> +.BR k ,
> +.BR m ,
> +or
> +.B g
> +suffixes like
> +.BR size ,
> +but not a % suffix.
> +.TP
> +.BR mode "=\fImode\fP"
> +Set initial permissions of the root directory.
> +.TP
> +.BR gid "=\fIgid\fP (since Linux 2.5.7)"
> +.\" Technically this is also in some version of Linux 2.4.
> +.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096
> +Set the initial group ID of the root directory.
> +.TP
> +.BR uid "=\fIuid\fP (since Linux 2.5.7)"
> +.\" Technically this is also in some version of Linux 2.4.
> +.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096
> +Set the initial user ID of the root directory.
> +.TP
> +.BR huge "=\fI[never|always|within_size|advise|deny|force]\fR (since Linux 4.7.0)"
> +.\" commit 5a6e75f8110c97e2a5488894d4e922187e6cb343
> +Set the huge table memory allocation policy for all files in this instance (if
> +CONFIG_TRANSPARENT_HUGE_PAGECACHE is enabled).
> +.TP
> +.BR mpol "=\fI[default|prefer:Node|bind:NodeList|interleave|interleave:NodeList]\fR (since Linux 2.6.15)"
> +.\" commit 7339ff8302fd70aabf5f1ae26e0c4905fa74a495
> +Set the NUMA memory allocation policy for all files in this instance (if
> +CONFIG_NUMA is enabled).
>  .SH VERSIONS
>  The
>  .B tmpfs
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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] tmpfs(5): document current mount options

[Karel Zak]

On Sun, Feb 04, 2018 at 10:03:28AM +0100, Michael Kerrisk (man-pages) wrote:
> On 01/27/2018 10:59 AM, Mike Frysinger wrote:
> > Some of this content is moved from the mount(8) man page.
> > Style was based on proc(5) sections.
> 
> Thanks. I've applied this. I also added some further details for the
> 'mpol' and 'huge' options, largely drawn from kernel Documentation
> files. Could you take a quick look at that new content?
> 
> Is there any other text for mount(8) that should be imported to
> tmpfs(5)?

It would be nice to completely remove filesystem specific stuff from
mount(8). It's already done for filesystems with active community
(like extN, XFS, etc), but the rest... ;-)

And another idea... what about to add a generic filesystem(5) (or
section 7) man page to explain why we have filesystems, relation with
mkfs programs, block devices, mount(8) ?

    Karel

-- 
 Karel Zak  <kzak-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
 http://karelzak.blogspot.com
--
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] tmpfs(5): document current mount options

[Michael Kerrisk (man-pages)]

Hello Karel,

On 02/05/2018 10:43 AM, Karel Zak wrote:
> On Sun, Feb 04, 2018 at 10:03:28AM +0100, Michael Kerrisk (man-pages) wrote:
>> On 01/27/2018 10:59 AM, Mike Frysinger wrote:
>>> Some of this content is moved from the mount(8) man page.
>>> Style was based on proc(5) sections.
>>
>> Thanks. I've applied this. I also added some further details for the
>> 'mpol' and 'huge' options, largely drawn from kernel Documentation
>> files. Could you take a quick look at that new content?
>>
>> Is there any other text for mount(8) that should be imported to
>> tmpfs(5)?
> 
> It would be nice to completely remove filesystem specific stuff from
> mount(8). It's already done for filesystems with active community
> (like extN, XFS, etc), but the rest... ;-)
> 
> And another idea... what about to add a generic filesystem(5) (or
> section 7) man page to explain why we have filesystems, relation with
> mkfs programs, block devices, mount(8) ?

Well there is already this:
http://man7.org/linux/man-pages/man5/filesystems.5.html

Obviously, more pieces could be added to it though.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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] tmpfs(5): document current mount options

[Karel Zak]

On Fri, Feb 09, 2018 at 07:13:49AM +0100, Michael Kerrisk (man-pages) wrote:
> Hello Karel,
> 
> On 02/05/2018 10:43 AM, Karel Zak wrote:
> > On Sun, Feb 04, 2018 at 10:03:28AM +0100, Michael Kerrisk (man-pages) wrote:
> >> On 01/27/2018 10:59 AM, Mike Frysinger wrote:
> >>> Some of this content is moved from the mount(8) man page.
> >>> Style was based on proc(5) sections.
> >>
> >> Thanks. I've applied this. I also added some further details for the
> >> 'mpol' and 'huge' options, largely drawn from kernel Documentation
> >> files. Could you take a quick look at that new content?
> >>
> >> Is there any other text for mount(8) that should be imported to
> >> tmpfs(5)?
> > 
> > It would be nice to completely remove filesystem specific stuff from
> > mount(8). It's already done for filesystems with active community
> > (like extN, XFS, etc), but the rest... ;-)
> > 
> > And another idea... what about to add a generic filesystem(5) (or
> > section 7) man page to explain why we have filesystems, relation with
> > mkfs programs, block devices, mount(8) ?
> 
> Well there is already this:
> http://man7.org/linux/man-pages/man5/filesystems.5.html

Ah sorry, I see it on upgraded system now (f27).

    Karel


-- 
 Karel Zak  <kzak-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
 http://karelzak.blogspot.com
--
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] tmpfs(5): document current mount options

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 806 bytes --]

On 04 Feb 2018 10:03, Michael Kerrisk (man-pages) wrote:
> On 01/27/2018 10:59 AM, Mike Frysinger wrote:
> > Some of this content is moved from the mount(8) man page.
> > Style was based on proc(5) sections.
> 
> Thanks. I've applied this.

you meant commit 462a385e9a239ac58e0db188d1d7ed94f36c2d6f ?  was the
author change a typo ?  am i more than person and didn't realize ?

> I also added some further details for the
> 'mpol' and 'huge' options, largely drawn from kernel Documentation
> files. Could you take a quick look at that new content?

seems fine

> Is there any other text for mount(8) that should be imported to
> tmpfs(5)?

i slurped all the tmpfs specific stuff out here.  there's room for
moving more stuff out, but into new pages.  that'll take more effort.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] tmpfs(5): document current mount options

[Michael Kerrisk (man-pages)]

Hello Mike,

On 02/05/2018 05:18 PM, Mike Frysinger wrote:
> On 04 Feb 2018 10:03, Michael Kerrisk (man-pages) wrote:
>> On 01/27/2018 10:59 AM, Mike Frysinger wrote:
>>> Some of this content is moved from the mount(8) man page.
>>> Style was based on proc(5) sections.
>>
>> Thanks. I've applied this.
> 
> you meant commit 462a385e9a239ac58e0db188d1d7ed94f36c2d6f ?  was the
> author change a typo ?  am i more than person and didn't realize ?

Yes, I messed up while amending a commit :-(. I'll fix that for the
manually produced changelog.

>> I also added some further details for the
>> 'mpol' and 'huge' options, largely drawn from kernel Documentation
>> files. Could you take a quick look at that new content?
> 
> seems fine

Thanks for checking.
 
>> Is there any other text for mount(8) that should be imported to
>> tmpfs(5)?
> 
> i slurped all the tmpfs specific stuff out here.  there's room for
> moving more stuff out, but into new pages.  that'll take more effort.

So, I see there is this text in mount(8):

              Note that trying to mount a tmpfs with an mpol option  will
              fail  if the running kernel does not support NUMA; and will
              fail if its nodelist specifies a node which is not  online.
              If your system relies on that tmpfs being mounted, but from
              time to time runs a kernel built  without  NUMA  capability
              (perhaps  a  safe  recovery  kernel),  or  with fewer nodes
              online, then it is advisable to omit the mpol  option  from
              automatic  mount  options.  It can be added later, when the
              tmpfs is  already  mounted  on  MountPoint,  by  'mount  -o
              remount,mpol=Policy:NodeList MountPoint'.

Will that stay there, or should it move to tmpfs(5)?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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