Cygwin: newgrp: first full version

- add '-' option
- make group argument optional
- drop ability to take a numerical group argument
- simplify usage output to bare minimum
- Add manpage and documentation

Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

1 files changed, 50 insertions, 0 deletions

diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml
index 895988037..927dc7c6b 100644
--- a/winsup/doc/utils.xml
+++ b/winsup/doc/utils.xml
@@ -1939,6 +1939,56 @@ D: on /d type fat (binary,user,noumount)
     </refsect1>
   </refentry>
 
+  <refentry id="newgrp">
+    <refmeta>
+      <refentrytitle>newgrp</refentrytitle>
+      <manvolnum>1</manvolnum>
+      <refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
+    </refmeta>
+
+    <refnamediv>
+      <refname>newgrp</refname>
+      <refpurpose>change primary group for a command</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+      <cmdsynopsis>
+	<command>newgrp</command>
+	<arg choice="opt">-</arg>
+	<arg choice="opt"><replaceable>group</replaceable></arg>
+	<arg><replaceable>command</replaceable>
+	<arg rep="repeat"><replaceable>args</replaceable></arg>
+	</arg>
+      </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1 id="newgrp-desc">
+      <title>Description</title>
+      <para><command>newgrp</command> changes the primary group for a
+        command.</para>
+
+      <para>If the '-' flag is given as first argument, the user's environment
+        will be reinitialized as though the user had logged in, otherwise the
+	current environment, including current working directory, remains
+	unchanged.</para>
+
+      <para><command>newgrp</command> changes the current primary group to the
+        named group, or to the default group listed in /etc/passwd if no group
+	name is given.</para>
+
+      <para>By default, the user's standard shell is started, called as login
+        shell if the '-' flag has been specified.  If a group has been given
+	as argument, a command and its arguments can be specified on the
+	command line.</para>
+
+      <para>Please note that setting the primary group to any arbitrary group
+        is no privileged operation on Windows.  However, if this group is not
+	in your current user token, or if the group is in your user token but
+	marked as <literal>deny-only</literal>, no additional permissions can
+	be obtained by setting this group as primary group.</para>
+    </refsect1>
+  </refentry>
+
   <refentry id="passwd">
     <refmeta>
       <refentrytitle>passwd</refentrytitle>