From jeremyp@gsmx07.alcatel.com.au Thu Jul 22 19:08:22 1999
Return-Path: <jeremyp@gsmx07.alcatel.com.au>
Received: from alcanet.com.au (border.alcanet.com.au [203.62.196.10])
	by hub.freebsd.org (Postfix) with ESMTP id 27D4B1572B
	for <FreeBSD-gnats-submit@FreeBSD.ORG>; Thu, 22 Jul 1999 19:08:17 -0700 (PDT)
	(envelope-from jeremyp@gsmx07.alcatel.com.au)
Received: by border.alcanet.com.au id <40354>; Fri, 23 Jul 1999 11:49:39 +1000
Message-Id: <99Jul23.114939est.40354@border.alcanet.com.au>
Date: Fri, 23 Jul 1999 12:08:07 +1000
From: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
Reply-To: peter.jeremy@alcatel.com.au
To: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Expand /etc/ttys manpage
X-Send-Pr-Version: 3.2

>Number:         12767
>Category:       bin
>Synopsis:       Expand /etc/ttys manpage
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    sheldonh
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 22 19:10:01 PDT 1999
>Closed-Date:    Mon Dec 6 23:58:15 PST 1999
>Last-Modified:  Mon Dec  6 23:59:15 PST 1999
>Originator:     Peter Jeremy
>Release:        FreeBSD 4.0-CURRENT i386
>Organization:
Alcatel Australia Limited
>Environment:

	cvs-cur 5500

>Description:

	There are shortcomings in ttys(5) when compared to the way
	/etc/ttys is parsed by /sbin/init.  The following patch
	describes the way /sbin/init behaves.  I believe this
	description is more appropriate here since init(8) refers
	to ttys(5), and any other program wanting to parse /etc/ttys
	should do so in the same manner as init.

>How-To-Repeat:

	Code inspection.

>Fix:
	
Index: libexec/getty/ttys.5
===================================================================
RCS file: /home/CVSROOT/./src/libexec/getty/ttys.5,v
retrieving revision 1.9
diff -u -r1.9 ttys.5
--- ttys.5	1997/11/21 07:43:53	1.9
+++ ttys.5	1999/07/23 01:56:37
@@ -125,6 +125,14 @@
 "none".
 For backwards compatibility, the ``group='' should appear last on the
 line, immediately before the optional comment.
+.Pp
+Both the second field and any command specified with ``window=''
+will be split into words and executed using
+.Xr execve 2 .
+Words are separated by tabs and/or spaces.
+Arguments comprised of more than one word should be enclosed in single
+quotes ("'").
+Note that no shell-style globbing or other variable substitution occurs.
 .Sh EXAMPLES
 .Bd -literal
 # root login on console at 1200 baud


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-bugs->sheldonh 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Fri Jul 23 14:49:46 PDT 1999 
Responsible-Changed-Why:  
I'll take this one. Gimme a day or two. :-) 
State-Changed-From-To: open->feedback 
State-Changed-By: sheldonh 
State-Changed-When: Sat Jul 24 04:17:12 PDT 1999 
State-Changed-Why:  
Peter, where is the function getttyent() defined? I'm trying to verify 
the change you're requesting and can't find the function that does the 
work anywhere. :-) 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: peter.jeremy@alcatel.com.au
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage 
Date: Thu, 29 Jul 1999 18:56:28 +0200

 Hi Peter,
 
 I've had a closer look at the manpage as it stands. While your patch
 accurately describes the execution of commands, this is already
 described in paragraphs 3 and 6 of the manpage.
 
 Permission to close PR, or would you like a second opinion? :-)
 
 Ciao,
 Sheldon.
 

From: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
To: sheldonh@uunet.co.za
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage
Date: Fri, 30 Jul 1999 10:39:53 +1000

 Hi Sheldon,
 
 You wrote:
 > While your patch
 >accurately describes the execution of commands, this is already
 >described in paragraphs 3 and 6 of the manpage.
 
 I beg to differ.  I don't believe the issues I'm raising are described
 in the man page.  The points I am trying to document are:
 
 1) Within a single field (which comprises multiple words enclosed in
    double quotes), command arguments can contain multiple words by
    enclosing the argument in single quotes.
 
    The paragraph beginning "The second field" states that the field
    "can contain multiple words if quoted", and the paragraph starting
    "As flag values" states "quoted command string".  In context, I
    read the word `quoted' to be a reference to the sentence "Fields
    comprised of more than one word should be enclosed in double quotes
    (``"'')".  I don't read this as any reference to the way that words
    within a single quoted field are parsed before being passed to
    exec().
 
 2) There's no command line expansion or substitution.
 
    Reasoned reflection would suggest that this is the behaviour, but
    explicitly documenting it can only improve clarity (IMHO).
 
 3) The name specified in the first field doesn't have to refer to
    a real tty (or even an entry in /dev).  (This is in an addendum
    I posted to gnats shortly after I posted the original PR - copy
    below).
 
    Whilst the 3rd paragraph does state that init can start any
    command, the 2nd paragraph (beginning "The first field") explicitly
    states that this field refers to a terminal special file in /dev.
    This wording implies (to me, anyway), that the field _must_ refer
    to a terminal special file in /dev - this makes it unclear what to
    put here when the entry is starting a daemon that isn't related to
    a terminal at all.
 
 As an example (maybe I should have included one to make it clearer),
 the line:
 
 xyzzy "/sbin/foo 'this is an argument' arg2 $HOME *" none on
 
 will result in an exec() call equivalent to the following C code:
 
 execl("/sbin/foo", "/sbin/foo", "this is an argument", "arg2",
    "$HOME", "*", "/dev/xyzzy", NULL);
 
 (unless open(2)ing /dev/xyzzy returns ENXIO).
 
 I have no objection to you changing the wording, but I believe that
 explicitly documenting the points I raised above is worthwhile.
 
 >Permission to close PR, or would you like a second opinion? :-)
 If the above arguments don't sway you, I'd like a second opinion.
 
 Addendum patch to ttys.5:
 @@ -59,6 +59,11 @@
  The first field is the
  name of the terminal special file as it is found in
  .Pa /dev .
 +If there is no matching entry in
 +.Pa /dev ,
 +the command will be started anyway - this can be used to keep critical
 +daemons running in a similar manner to the System 5
 +.Pa /etc/inittab .
  .Pp
  The second field of the file is the command to execute for the line,
  usually
 
 Peter
 
State-Changed-From-To: feedback->open 
State-Changed-By: sheldonh 
State-Changed-When: Thu Jul 29 17:53:17 PDT 1999 
State-Changed-Why:  
I feel that Peter's suggestion would only contribute unwanted baggage 
to the manpage, except perhaps for his addendum. I'm leaving it open 
for a second opinion. 
:-) 


Responsible-Changed-From-To: sheldonh->freebsd-doc 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Thu Jul 29 17:53:17 PDT 1999 
Responsible-Changed-Why:  
Handing back to the peanut gallery. 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage 
Date: Fri, 30 Jul 1999 02:53:10 +0200

 On Fri, 30 Jul 1999 10:39:53 +1000, Peter Jeremy wrote:
 
 > 1) Within a single field (which comprises multiple words enclosed in
 >    double quotes), command arguments can contain multiple words by
 >    enclosing the argument in single quotes.
 
 This is a pretty standard UNIX thing, yeah.
 
 >    I don't read this as any reference to the way that words
 >    within a single quoted field are parsed before being passed to
 >    exec().
 
 You're right, the manpage doesn't explicitly spell out how the command
 is executed. Imagine, though, how annoying it would be if every manpage
 that uses a user-specified command for execution spelled out how the
 exec() family works.
 
 I'm happy with believing that "foo bar" means run program foo with
 argument bar.
 
 > 2) There's no command line expansion or substitution.
 >    Reasoned reflection would suggest that this is the behaviour, but
 >    explicitly documenting it can only improve clarity (IMHO).
 
 The documentation doesn't say that the command is passed to a shell, so
 the lack of expansion and substitution should be self-evident.
 
 >    This wording implies (to me, anyway), that the field _must_ refer
 >    to a terminal special file in /dev - this makes it unclear what to
 >    put here when the entry is starting a daemon that isn't related to
 >    a terminal at all.
 
 I wouldn't want to encourage people to launch daemons which aren't
 associated with a terminal from /etc/ttys -- I'd prefer them to launch
 their daemons from ${LOCABASE}/etc/rc.d, rc.local etc.
 
 > >Permission to close PR, or would you like a second opinion? :-)
 > If the above arguments don't sway you, I'd like a second opinion.
 
 Sure thing. You've dealt with me before, so you know I'm not one to piss
 on your ideas without giving someone else the opportunity to do the
 same. :-)
 
 I'll leave the PR open for independant review as I do with others where
 the originator disagrees with me. If someone else likes your idea, it
 won't be the first time that the originator was right and I was wrong.
 ;-)
 
 Later,
 Sheldon.
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: bin/12767: Expand /etc/ttys manpage 
Date: Fri, 30 Jul 1999 11:47:24 +0200

 On Fri, 30 Jul 1999 11:41:48 +1000, Peter Jeremy wrote:
 
 > Actually, I'd assume that (in the absence of evidence to the contrary),
 > where an arbitrary command string is allowed, that string was passed
 > to system(3) (or something functionally similar) for execution.
 
 > I currently have a situation where I'd prefer to launch something from
 > init so it'll automatically get restarted if it dies.  This isn't as
 > easy from rc.* (I'd need to wrap it in another process that just
 > re-exec'd it if it died - init already does this and comes with
 > assorted sanity checks).
 
 Hmmm. I'm convinced on both counts.
 
 I'm still not happy with the fact that your diff leads the manpage to
 repeat itself.
 
 Here's a deal: if I can come up with a diff that I prefer over yours by
 next Tuesday, I'll send it. Otherwise, we'll assume I can't do any
 better than you can and use yours. ;-)
 
 And yes, if I come up with something, I'll pass it by you for approval.
 
 Ciao,
 Sheldon.
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage 
Date: Tue, 03 Aug 1999 23:47:02 +0200

 On Fri, 30 Jul 1999 10:39:53 +1000, Peter Jeremy wrote:
 
 > I beg to differ.  I don't believe the issues I'm raising are described
 > in the man page.  The points I am trying to document are:
 
 Hi Peter,
 
 I've just read the init(8) and ttys(5) manpages in their entirety and
 can't shake the feeling that this should either be documented in both.
 
 I'm still puzzling over how to describe effectively in both manpages
 what you want explained.
 
 Ciao,
 Sheldon.
 

From: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
To: sheldonh@uunet.co.za
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage
Date: Thu, 5 Aug 1999 06:39:40 +1000

 Hi Sheldon,
 
 >I'm still puzzling over how to describe effectively in both manpages
 >what you want explained.
 
 How about the following:
 Index: init.8
 ===================================================================
 RCS file: /home/CVSROOT/./src/sbin/init/init.8,v
 retrieving revision 1.17
 diff -u -r1.17 init.8
 --- init.8	1999/07/05 18:12:13	1.17
 +++ init.8	1999/08/04 20:36:01
 @@ -153,7 +153,9 @@
  processes for the terminal ports found in the file
  .Xr ttys 5 .
  .Nm Init
 -reads this file, and executes the command found in the second field.
 +reads this file, and executes the command found in the second field,
 +unless the tty specified in the first field is not configured.
 +The first field is supplied as the final argument to the command.
  This command is usually
  .Xr getty 8 ;
  .Nm getty
 @@ -183,6 +185,14 @@
  .Nm getty
  for the line.
  .Pp
 +.Nm Init
 +can also be used to keep arbitrary daemons running - automatically
 +restarting them if they die.
 +In this case, the first field in the
 +.Xr ttys 5
 +file can specify any arbitrary string (though it will be passed to
 +the daemon on its command line).
 +.Pp
  Line status (on, off, secure, getty, or window information)
  may be changed in the
  .Xr ttys 5
 @@ -206,10 +216,8 @@
  .Xr ttys 5
  file and are now on,
  .Nm
 -executes a new
 -.Nm getty
 -to enable a new login.
 -If the getty or window field for a line is changed,
 +executes the command specified in the second field.
 +If the command or window field for a line is changed,
  the change takes effect at the end of the current
  login session (e.g., the next time 
  .Nm
 @@ -239,8 +247,7 @@
  will time out after 30 seconds and print a warning message.
  .Pp
  .Nm Init
 -will cease creating new
 -.Nm getty Ns 's
 +will cease creating new processes
  and allow the system to slowly die away, if it is sent a terminal stop
  .Pq Dv TSTP
  signal, i.e.
 
 Peter
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage 
Date: Fri, 06 Aug 1999 15:20:40 +0200

 On Thu, 05 Aug 1999 06:39:40 +1000, Peter Jeremy wrote:
 
 > @@ -153,7 +153,9 @@
 >  processes for the terminal ports found in the file
 >  .Xr ttys 5 .
 >  .Nm Init
 > -reads this file, and executes the command found in the second field.
 > +reads this file, and executes the command found in the second field,
 > +unless the tty specified in the first field is not configured.
 > +The first field is supplied as the final argument to the command.
 >  This command is usually
 >  .Xr getty 8 ;
 >  .Nm getty
 > @@ -183,6 +185,14 @@
 
 So you're dropping the idea of explicitly explaining that the command is
 broken into execve(2)?
 
 Ciao,
 Sheldon.
 

From: Steve Price <sprice@hiwaay.net>
To: freebsd-gnats-submit@freebsd.org
Cc:  
Subject: Re: bin/12767: Expand /etc/ttys manpage (fwd)
Date: Sun, 29 Aug 1999 10:03:42 -0500 (CDT)

 ---------- Forwarded message ----------
 Date: Fri, 23 Jul 1999 14:30:38 +1000
 From: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
 To: gnats@FreeBSD.ORG
 Subject: Re: bin/12767: Expand /etc/ttys manpage
 
 Whilst I'm on the topic, having finished my study of init's behaviour,
 I'd also like to see something like the following (this'll save the
 next poor sod having to RTSL to confirm this behaviour):
 
 Index: libexec/getty/ttys.5
 ===================================================================
 RCS file: /home/CVSROOT/./src/libexec/getty/ttys.5,v
 retrieving revision 1.9
 diff -u -r1.9 ttys.5
 --- ttys.5	1997/11/21 07:43:53	1.9
 +++ ttys.5	1999/07/23 04:26:46
 @@ -59,6 +59,11 @@
  The first field is the
  name of the terminal special file as it is found in
  .Pa /dev .
 +If there is no matching entry in
 +.Pa /dev ,
 +the command will be started anyway - this can be used to keep critical
 +daemons running in a similar manner to the System 5
 +.Pa /etc/inittab .
  .Pp
  The second field of the file is the command to execute for the line,
  usually
 
 Peter
 
 

From: Peter Jeremy <jeremyp@gsmx07.alcatel.com.au>
To: sheldonh@FreeBSD.ORG
Cc: gnats@FreeBSD.ORG
Subject: Re: bin/12767: Expand /etc/ttys manpage
Date: Mon, 27 Sep 1999 09:43:52 +1000

 Hi Sheldon,
 
 After contemplating both ttys(5) and init(8), my latest suggestion is
 the following:
 
 Index: src/libexec/getty/ttys.5
 ===================================================================
 RCS file: /home/CVSROOT/src/libexec/getty/ttys.5,v
 retrieving revision 1.10
 diff -u -r1.10 ttys.5
 --- ttys.5	1999/08/28 00:09:37	1.10
 +++ ttys.5	1999/09/26 23:42:57
 @@ -56,9 +56,11 @@
  are delimited by hash marks (``#'') and new lines.
  Any unspecified fields will default to null.
  .Pp
 -The first field is the
 +The first field is normally the
  name of the terminal special file as it is found in
  .Pa /dev .
 +It can be, however, any arbitrary string when the associated command is not
 +related to a tty.
  .Pp
  The second field of the file is the command to execute for the line,
  usually
 @@ -125,6 +127,14 @@
  "none".
  For backwards compatibility, the ``group='' should appear last on the
  line, immediately before the optional comment.
 +.Pp
 +Both the second field and any command specified with ``window=''
 +will be split into words and executed using
 +.Xr execve 2 .
 +Words are separated by tabs and/or spaces.
 +Arguments comprised of more than one word should be enclosed in single
 +quotes ("'").
 +Note that no shell-style globbing or other variable substitution occurs.
  .Sh EXAMPLES
  .Bd -literal
  # root login on console at 1200 baud
 Index: src/sbin/init/init.8
 ===================================================================
 RCS file: /home/CVSROOT/src/sbin/init/init.8,v
 retrieving revision 1.19
 diff -u -r1.19 init.8
 --- init.8	1999/09/06 08:41:32	1.19
 +++ init.8	1999/09/26 23:42:57
 @@ -152,7 +152,11 @@
  processes for the terminal ports found in the file
  .Xr ttys 5 .
  .Nm Init
 -reads this file, and executes the command found in the second field.
 +reads this file, and executes the command found in the second field,
 +unless the first field refers to a device in
 +.Pa /dev
 +which is not configured.
 +The first field is supplied as the final argument to the command.
  This command is usually
  .Xr getty 8 ;
  .Nm getty
 @@ -182,6 +186,17 @@
  .Nm getty
  for the line.
  .Pp
 +.Nm Init
 +can also be used to keep arbitrary daemons running - automatically
 +restarting them if they die.
 +In this case, the first field in the
 +.Xr ttys 5
 +file can specify any arbitrary string (though it will be passed to
 +the daemon on its command line).
 +This is similar to the facilities offered in the
 +.At V
 +.Pa /etc/inittab .
 +.Pp
  Line status (on, off, secure, getty, or window information)
  may be changed in the
  .Xr ttys 5
 @@ -205,10 +220,8 @@
  .Xr ttys 5
  file and are now on,
  .Nm
 -executes a new
 -.Nm getty
 -to enable a new login.
 -If the getty or window field for a line is changed,
 +executes the command specified in the second field.
 +If the command or window field for a line is changed,
  the change takes effect at the end of the current
  login session (e.g., the next time 
  .Nm
 @@ -238,8 +251,7 @@
  will time out after 30 seconds and print a warning message.
  .Pp
  .Nm Init
 -will cease creating new
 -.Nm getty Ns 's
 +will cease creating new processes
  and allow the system to slowly die away, if it is sent a terminal stop
  .Pq Dv TSTP
  signal, i.e.
 
 
 Peter
 
Responsible-Changed-From-To: freebsd-doc->sheldonh 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Fri Dec 3 06:30:06 PST 1999 
Responsible-Changed-Why:  
I'll take this one, just waiting for Peter's approval of a few 
changes I made to his patch. 
State-Changed-From-To: open->suspended 
State-Changed-By: sheldonh 
State-Changed-When: Mon Dec 6 23:52:20 PST 1999 
State-Changed-Why:  
A mutually acceptable patch committed in: 
rev 1.11	src/getty/ttys.5 
rev 1.20	src/sbin/init/init.8 
MFC to follow. 
State-Changed-From-To: suspended->closed 
State-Changed-By: sheldonh 
State-Changed-When: Mon Dec 6 23:58:15 PST 1999 
State-Changed-Why:  
Committed to RELENG_3 as: 
rev 1.13.2.6	src/sbin/init/init.8 
rev 1.9.2.2	src/libexec/getty/ttys.5 
>Unformatted:
