devpts man page update

Michael,

Following is some text that would need to be added to devpts section of mount(8) man page (its not a formal patch, just the text to be added). I am looking for logistics and a general review of the text to be added.

The relevant kernel patches are currently in ttydev/linux-next trees. I can send the formal man page patch after those patches go into mainline.

Also, is it ok to refer to 'Documentation' directory in the man page - there are several semantics outlined in Documentation/filesystem/devpts.txt
(http://www.linux.org.uk/~alan/ttydev/pty-multiple-doc), that may be of use only to users of containers.

Thanks,

Suka

---

@@ -1,3 +1,4 @@
+
 Mount options for devpts
 	The  devpts  file system is a pseudo file system, traditionally mounted
 	on /dev/pts.  In order to acquire a pseudo terminal,  a  process  opens

@@ -17,3 +18,48 @@
 		default is 0600.  A value of mode=620 and gid=5 makes  "mesg  y"
 		the default on newly created PTYs.
 
+	newinstance
+
+		Create a private instance of devpts filesystem, such that
+		indices of ptys allocated in this new instance of the
+		filesystem are independent of indices created in other
+		instances of devpts.
+
+		If this option is not specified for a mount of devpts, 
+		("legacy mode"), that instance of devpts shares the pty
+		indices with the initial/default mount of devpts. i.e.
+		all mounts of devpts without this 'newinstance' option
+		share the same set of pty indices. Each mount of devpts
+		with newinstance option has a private set of pty indices.
+
+		This option is mainly used to support containers in the
+		linux kernel. It is implemented in linux kernel versions
+		starting with 2.6.XX.  Further, this mount option is valid
+		only if CONFIG_DEVPTS_MULTIPLE_INSTANCES is enabled in the
+		kernel configuration.
+
+		To use this option effectively, '/dev/ptmx' must be a
+		symlink to 'pts/ptmx'. See Documentation/filesystems/
+		devpts.txt for details.
+
+	ptmxmode=value
+ 
+		Set the mode for the new 'ptmx' device node in the devpts
+		filesystem. Default mode is 0000 for compatibility with
+		legacy mode of devpts.
+
+		This option is only implemented in linux kernel versions
+		starting with 2.6.XX. Further this option is valid only if 
+		CONFIG_DEVPTS_MULTIPLE_INSTANCES is enabled in the kernel
+		configuration.
+
+		With support for multiple instances of devpts (see
+		'newinstance' option above), each instance has a private
+		'ptmx' node in the root of the devpts filesystem (typically
+		'/dev/pts/ptmx').
+
+		For compatibility with older versions of the kernel, the
+		default mode ot the new 'ptmx' node is 0000. 'ptmxmode'
+		option specifies a more useful mode for the 'ptmx' node
+		and is highly recommended when the 'newinstance' option
+		is specified.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Suka,

The mount(8) page is not part of the man-pages set. Take a look here:
http://www.kernel.org/doc/man-pages/man_pages_other.html

Though mount(8) is not on my set, I wonder if there is any text that should perhaps be added to pts(4) or pty(7).

http://www.kernel.org/doc/man-pages/online/pages/man4/pts.4.html
http://www.kernel.org/doc/man-pages/online/pages/man7/pty.7.html

Take a look at those and let me know.

Certainly as far as I'm concerned doing this is okay in the pages in man-pages -- you just need to say "the kernel source file Documentation/..."

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Filesystem-specific options should never have been part of mount(8) IMNSHO. Rather, they should be documented in the respective (4) pages with pointers from mount(8)...

-hpa

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Michael Kerrisk [mtk.manpages-gM/[email protected]] wrote:

| Suka,
| 
| On Wed, Nov 26, 2008 at 1:17 PM, Sukadev Bhattiprolu
| <[email protected]> wrote:
| > Michael,
| >
| > Following is some text that would need to be added to devpts section of
| > mount(8) man page (its not a formal patch, just the text to be added).
| > I am looking for logistics and a general review of the text to be added.
| 
| The mount(8) page is not part of the man-pages set.  Take a look here:
| http://www.kernel.org/doc/man-pages/man_pages_other.html

Aah, so maybe different patches for different distros. I will try to send them out at least to Redhat/Suse/Ubuntu. But cannot help asking (curiousity/ignorance :-), why are there separate 'trees' for different man pages even for features included in kernel ?

| 
| > The relevant kernel patches are currently in ttydev/linux-next trees.
| > I can send the formal man page patch after those patches go into mainline.
| 
| Though mount(8) is not on my set, I wonder if there is any text that
| should perhaps be added to pts(4) or pty(7).
| 
| http://www.kernel.org/doc/man-pages/online/pages/man4/pts.4.html
| http://www.kernel.org/doc/man-pages/online/pages/man7/pty.7.html

I think no updates are needed for pty(7). I was thinking of adding a pointer in pts(4) to mount(8), but do the sets of man pages also have separate release-cycles ? If so, should I stage the patches such that kernel patches go in first, mount(8) updates next and pts(4) updates last ?

| 
| Take a look at those and let me know.
| 
| > Also, is it ok to refer to 'Documentation' directory in the man page  -
| > there are several semantics outlined in Documentation/filesystem/devpts.txt
| > (http://www.linux.org.uk/~alan/ttydev/pty-multiple-doc), that may be of
| > use only to users of containers.
| 
| Certainly as far as I'm concerned doing this is okay in the pages in
| man-pages -- you just need to say "the kernel source file
| Documentation/..."

Ok.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Suka,

No, no... The point is that mount(8) is part of a different project:
util-linux(-ng). Your patches potentially need to go to the maintainer of *that* project.

The fact that the util-linux(-ng) maintainer includes some kernel details in the mount(8) man page is not something that I control. It may or may not be a good idea.

Most certainly. The point is: all Linux man pages do *not* come from the same source. The package I maintain consists mainly of pages in Sections 2, 3, 4, 5, and 7.

Well, You'd need to talk with the util-linux-ng people, but I think in the end the order doesn't matter too much. It's typically only a few months later that man-pages will end in a distro release anyway..

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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Add Cc: util-linux-ng

IMNSHO, it's distincly not a good idea. For one thing, the mount(8) man page is a mess. Any options that aren't generic across filesystems should be moved out of mount(8) into the filesystem man pages in section 4.

The fact that the options are in the mount(8) man page is largely a historical artifact dating back to the early 1990's when Linux only had a handful of filesystems.

The way to do that pretty much ends up with:

1. Agree that this is the way to do it.
2. Add the options to section 4.
3. Clean up mount(8).

... in that order.

-hpa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

If there's consensus (including from the mount(8) man page maintainer), I have no objection to this, and I can see some sense in it. The mount options are, after all, kernel interfaces. Perhaps this whole situation arose because once upon a time, the maintainer of the mount(8) page and the maintainer of man-pages were the same person, Andries, and perhaps he too has an opinion. (Andries, here's a pointer to the thread so far:
http://article.gmane.org/gmane.linux.man/557/ )

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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Michael,

At some point in time I cleaned up the messy and incomplete mount docs and wrote the nicely structured and complete mount(8). Of course as time passes completeness can be lost, and the page can become unwieldy because of excessive length. The page I am looking at has roughly 1500 lines, of which roughly 1000 are about filesystem-specific mount options. Maybe a bit long, but since this length is caused by a list that is alphabetically sorted and has entries that tend to be only a few dozen lines long, I do not mind this length so much.

Perhaps Peter complains about something else when he sees a mess?

The goal of a man page author must be convenience of the user. The information must be clear, precise, concise, easy to find.

I don't know how modern distributions usually present these man pages. Myself, I read them in the old-fashioned way on an xterm, where no hyperlinks are available. In such a setting a single page is clearly more convenient, but there will come a point where it is simply too long.

These filesystem man pages in section 4 do not exist yet, as far as I can see. What would the names be? Would splitting things up make it easier for the user to find her info?

Andries

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

No, but I really don't think it's appropriate to just tag on and on to a single man page. I know that I find it incredibly painful to wade through the long list of options, most of which don't apply to me.

Lists within lists don't visually scan well.

Some auxilliary filesystems already have section 4, I believe. The other option, of course, is to move that data to mount.<filesystem>(8).

-hpa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Send a patch or bug report, that's the way how you can "control" :-)

We're already talking about it at linux-fsdevel and util-linux-ng mailing list:

    http://marc.info/?l=linux-fsdevel&m=122767297002093&w=3

Yes, I haven't time to cleanup util-linux-ng docs (yet). The idea to create man page (in section 4) for every filesystem is my wish. So.. I look forward to see some patches in this area.

4. found a way how maintain and keep the man pages up to date.

Karel

 Karel Zak  <[email protected]>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

As far as 4. is concerned -- I personally think that keeping man pages that directly describe kernel interfaces (e.g. section 2, and parts of 4, 5, and 7) in the kernel git tree is the most logical option.

-hpa
--
To unsubscribe from this list: send the line "unsubscribe util-linux-ng" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

That's exactly my opinion ... somewhere in Documentation/ and maintained *together* with fs-depend code.

Karel

 Karel Zak  <[email protected]>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

-hpa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

By the way, lest someone gets the wrong idea... I think mtk has done a fantastic job with the man pages recently, and I certainly don't want to replace him. I think he should push into the kernel tree via git like all the other maintainers (for the relevant portions, obviously -- section 3, for example, doesn't make sense in the kernel tree.)

-hpa
--
To unsubscribe from this list: send the line "unsubscribe util-linux-ng" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html