path: root/usr/src/man/man1/newgrp.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\"
.TH NEWGRP 1 "Nov 2, 2007"
.SH NAME
newgrp \- log in to a new group
.SH SYNOPSIS
.SS "Command"
.LP
.nf
\fB/usr/bin/newgrp\fR [\fB-|\fR \fB-l\fR] [\fIgroup\fR]
.fi

.SS "sh Built-in"
.LP
.nf
\fBnewgrp\fR [\fIargument\fR]
.fi

.SS "ksh Built-in"
.LP
.nf
\fB*newgrp\fR [\fIargument\fR]
.fi

.SS "ksh93 Built-in"
.LP
.nf
\fB+newgrp\fR [\fIargument\fR]
.fi

.SH DESCRIPTION
.SS "Command"
.sp
.LP
The \fBnewgrp\fR command logs a user into a new group by changing a user's real
and effective group ID. The user remains logged in and the current directory is
unchanged. The execution of \fBnewgrp\fR always replaces the current shell with
a new shell, even if the command terminates with an error (unknown group).
.sp
.LP
Any variable that is not exported is reset to null or its default value.
Exported variables retain their values. System variables (such as \fBPS1\fR,
\fBPS2\fR, \fBPATH\fR, \fBMAIL\fR, and \fBHOME\fR), are reset to default values
unless they have been exported by the system or the user. For example, when a
user has a primary prompt string (\fBPS1\fR) other than \fB$\fR (default) and
has not exported \fBPS1\fR, the user's \fBPS1\fR is set to the default prompt
string \fB$\fR, even if \fBnewgrp\fR terminates with an error. Note that the
shell command \fBexport\fR (see \fBsh\fR(1) and \fBset\fR(1)) is the method to
export variables so that they retain their assigned value when invoking new
shells.
.sp
.LP
With no operands and options, \fBnewgrp\fR changes the user's group IDs (real
and effective) back to the group specified in the user's password file entry.
This is a way to exit the effect of an earlier \fBnewgrp\fR command.
.sp
.LP
A password is demanded if the group has a password and the user is not listed
in \fB/etc/group\fR as being a member of that group. The only way to create a
password for a group is to use \fBpasswd\fR(1), then cut and paste the password
from \fB/etc/shadow\fR to \fB/etc/group\fR. Group passwords are antiquated and
not often used.
.SS "sh Built-in"
.sp
.LP
Equivalent to \fBexec\fR \fBnewgrp\fR \fIargument\fR where \fIargument\fR
represents the options and/or operand of the \fBnewgrp\fR command.
.SS "ksh Built-in"
.sp
.LP
Equivalent to \fBexec\fR to\fB/bin/newgrp\fR \fIargument\fR where
\fIargument\fR represents the options and/or operand of the \fBnewgrp\fR
command.
.sp
.LP
On this man page, \fBksh\fR(1) commands that are preceded by one or two \fB*\fR
(asterisks) are treated specially in the following ways:
.RS +4
.TP
1.
Variable assignment lists preceding the command remain in effect when the
command completes.
.RE
.RS +4
.TP
2.
I/O redirections are processed after variable assignments.
.RE
.RS +4
.TP
3.
Errors cause a script that contains them to abort.
.RE
.RS +4
.TP
4.
Words, following a command preceded by \fB**\fR that are in the format of a
variable assignment, are expanded with the same rules as a variable assignment.
This means that tilde substitution is performed after the \fB=\fR sign and word
splitting and file name generation are not performed.
.RE
.SS "ksh93 Built-in"
.sp
.LP
Equivalent to \fBexec\fR to\fB/bin/newgrp\fR \fIargument\fR where
\fIargument\fR represents the options and/or operand of the \fBnewgrp\fR
command.
.sp
.LP
On this man page, \fBksh93\fR(1) commands that are preceded by one or two
\fB+\fR (plus signs) are treated specially in the following ways:
.RS +4
.TP
1.
Variable assignment lists preceding the command remain in effect when the
command completes.
.RE
.RS +4
.TP
2.
I/O redirections are processed after variable assignments.
.RE
.RS +4
.TP
3.
Errors cause a script that contains them to abort.
.RE
.RS +4
.TP
4.
They are not valid function names.
.RE
.RS +4
.TP
5.
Words, following a command preceded by \fB++\fR that are in the format of a
variable assignment, are expanded with the same rules as a variable assignment.
This means that tilde substitution is performed after the \fB=\fR sign and
field splitting and file name generation are not performed.
.RE
.SH OPTIONS
.sp
.LP
The following option is supported:
.sp
.ne 2
.na
\fB\fB-l\fR | \fB\(mi\fR\fR
.ad
.RS 13n
Change the environment to what would be expected if the user actually logged in
again as a member of the new group.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIgroup\fR\fR
.ad
.RS 12n
A group name from the group database or a non-negative numeric group ID.
Specifies the group ID to which the real and effective group IDs is set. If
\fIgroup\fR is a non-negative numeric string and exists in the group database
as a group name (see \fBgetgrnam\fR(3C)), the numeric group ID associated with
that group name is used as the group ID.
.RE

.sp
.ne 2
.na
\fB\fIargument\fR\fR
.ad
.RS 12n
\fBsh\fR and \fBksh\fR only. Options and/or operand of the \fBnewgrp\fR
command.
.RE

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBnewgrp\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
If \fBnewgrp\fR succeeds in creating a new shell execution environment, whether
or not the group identification was changed successfully, the exit status is
the exit status of the shell. Otherwise, the following exit value is returned:
.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/group\fR\fR
.ad
.RS 15n
System group file
.RE

.sp
.ne 2
.na
\fB\fB/etc/passwd\fR\fR
.ad
.RS 15n
System password file
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SS "/usr/bin/newgrp, ksh, sh"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SS "ksh93"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Uncommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBlogin\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBset\fR(1), \fBsh\fR(1),
\fBIntro\fR(3), \fBgetgrnam\fR(3C), \fBgroup\fR(4), \fBpasswd\fR(4),
\fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)