<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="setuidgid">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>setuidgid</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">nosh</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv><refname>setuidgid</refname><refpurpose>set process UID and GID(s) then chain</refpurpose></refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>setuidgid</command>
<arg choice='opt'>--primary-group <replaceable>group</replaceable></arg>
<arg choice='opt'>--supplementary</arg>
<arg choice='req'><replaceable>account</replaceable></arg>
<arg choice='req'><replaceable>next-prog</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>
<command>setuidgid</command> is a chain-loading utility that sets the process real+effective UID and real+effective GID to the values for <replaceable>account</replaceable> in the system account database and then chain loads to <replaceable>next-prog</replaceable> with the <citerefentry><refentrytitle>execvp</refentrytitle><manvolnum>3</manvolnum></citerefentry> function.
</para>

<para>
<replaceable>next-prog</replaceable> may contain its own command line options, which <command>setuidgid</command> will ignore.
</para>

<para>
If the <arg choice='plain'>--primary-group</arg> option is used, setuidgid will use <replaceable>group</replaceable> instead of the primary GID of <replaceable>account</replaceable> as the GID to set.
</para>

<para>
If the <arg choice='plain'>--supplementary</arg> option is used, setuidgid will also set the supplementary GIDs for the groups to which account belongs, as listed in the groups database.
Without that option, it only sets the GID that is listed for <replaceable>account</replaceable> in the password database, ignoring the group database, and clears the list of supplementary groups entirely.
</para>

<para>
In either case, the command will fail if the process is not running under the aegis of the superuser.
Non-superusers are not permitted to alter the supplementary groups list.
</para>

<para>
If it cannot find an account named <replaceable>account</replaceable> in the database, or fails setting the groups or user ID, it does not chain and exits with status code 111.
</para>

</refsection><refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
