RFC: New section for the Unix Basics chapter.

[Tom Rhodes]

Hey,

In this email I have a patch to add information on symbolic permissions
to the Unix Basics chapter of our handbook.  Now I'm a little wierd on
the table output and I know that it could use a few more <literal>
tags, but I wanted to get a general idea before I put more work into
it.

Comments, suggestions, death threats welcome.  Thanks!

--
Tom Rhodes


--- chapter.sgml	Thu Jun 19 14:39:43 2003
+++ chapter.sgml.new	Thu Jun 19 14:07:59 2003
@@ -59,7 +59,7 @@
 
   <sect1 id="permissions">
     <title>Permissions</title>
-    <indexterm><primary>Unix</primary></indexterm>
+    <indexterm><primary>permissions</primary><secondary>octal</secondary></indexterm>
 
     <para>FreeBSD, being a direct descendant of BSD Unix, is based on
       several key Unix concepts.  The first, and
@@ -198,6 +198,135 @@
       directories.  If you want more information on file permissions and
       how to set them, be sure to look at the &man.chmod.1; manual
       page.</para>
+
+    <sect2>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <title>Symbolic Permissions</title>
+      <indexterm><primary>permissions</primary><secondary>symbolic</secondary></indexterm>
+
+      <para>Symbolic permissions, sometimes refereed to as symbolic expressions,
+	uses characters in place of octal values to assign permissions to files
+	or directories.  Symbolic expressions use the syntax of (who) (action)
+	(permissions), where the following values are available:</para>
+
+      <informaltable>
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Option</entry>
+	      <entry>Letter</entry>
+	      <entry>Represents</entry>
+	    </row>
+	  </thead>
+
+	<tbody>
+	  <row>
+	    <entry>(who)</entry>
+	    <entry>u</entry>
+	    <entry>File Owner</entry>
+	  </row>
+
+	  <row>
+	    <entry>(who)</entry>
+	    <entry>g</entry>
+	    <entry>Group owner</entry>
+	  </row>
+
+	  <row>
+	    <entry>(who)</entry>
+	    <entry>o</entry>
+	    <entry>Other</entry>
+	  </row>
+
+	  <row>
+	    <entry>(who)</entry>
+	    <entry>a</entry>
+	    <entry>All</entry>
+	  </row>
+
+	  <row>
+	    <entry>(action)</entry>
+	    <entry>+</entry>
+	    <entry>Adding permissions</entry>
+	  </row>
+
+	  <row>
+	    <entry>(action)</entry>
+	    <entry>-</entry>
+	    <entry>Removing permissions</entry>
+	  </row>
+
+	  <row>
+	    <entry>(action)</entry>
+	    <entry>=</entry>
+	    <entry>Explicitly set permissions</entry>
+	  </row>
+
+	  <row>
+	    <entry>(permissions)</entry>
+	    <entry>r</entry>
+	    <entry>Read</entry>
+	  </row>
+
+	  <row>
+	    <entry>(permissions)</entry>
+	    <entry>w</entry>
+	    <entry>Write</entry>
+	  </row>
+
+	  <row>
+	    <entry>(permissions)</entry>
+	    <entry>x</entry>
+	    <entry>Execute</entry>
+	  </row>
+
+	  <row>
+	    <entry>(permissions)</entry>
+	    <entry>t</entry>
+	    <entry>Sticky bit</entry>
+	  </row>
+
+	  <row>
+	    <entry>(permissions)</entry>
+	    <entry>s</entry>
+	    <entry>SUID or SGID</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+
+    <para>These values are used with the <command>chmod</command> command
+      just like before, but with letters.  For an example, you could use
+      the following command to block other users from accessing the files
+      in your home directory:</para>
+
+    <screen>&prompt.user;<userinput>chmod go= *</userinput></screen>
+
+    <para>A comma separated list can be provided when more than one set
+      of changes to a file must be made.  For example the following command
+      will remove the groups and <quote>world</quote> write permission
+      on <replaceable>FILE</replaceable>, then it adds the execute
+      permissions for everyone:</para>
+
+    <screen>&prompt.user;<userinput>chmod go-w,a+x <replaceable>FILE</replaceable></userinput></screen>
+
+
+    <para>Most users will do not notice this, but it should be pointed out
+      that using the octal method will only set or assign permissions to
+      a file; it does not add or delete them.  This means that the octal
+      method does not have an equivalent option to the following command:</para>
+
+    <screen>&prompt.root; <userinput>chmod u+rw <replaceable>FILE</replaceable></userinput></screen>
+
+    <para>The closest octal value would be <literal>0600</literal> and it would not
+      be the same.</para>
+    </sect2>
   </sect1>
   
   <sect1 id="dirstructure">