| blob | d9c43034882aefc74c31e4724a2066d60940d32c |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
46 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
47 .\"
48 .TH NEWGRP 1 "Nov 2, 2007"
49 .SH NAME
50 newgrp \- log in to a new group
51 .SH SYNOPSIS
52 .SS "Command"
53 .LP
54 .nf
55 \fB/usr/bin/newgrp\fR [\fB-|\fR \fB-l\fR] [\fIgroup\fR]
56 .fi
58 .SS "sh Built-in"
59 .LP
60 .nf
61 \fBnewgrp\fR [\fIargument\fR]
62 .fi
64 .SS "ksh Built-in"
65 .LP
66 .nf
67 \fB*newgrp\fR [\fIargument\fR]
68 .fi
70 .SS "ksh93 Built-in"
71 .LP
72 .nf
73 \fB+newgrp\fR [\fIargument\fR]
74 .fi
76 .SH DESCRIPTION
77 .SS "Command"
78 .sp
79 .LP
80 The \fBnewgrp\fR command logs a user into a new group by changing a user's real
81 and effective group ID. The user remains logged in and the current directory is
82 unchanged. The execution of \fBnewgrp\fR always replaces the current shell with
83 a new shell, even if the command terminates with an error (unknown group).
84 .sp
85 .LP
86 Any variable that is not exported is reset to null or its default value.
87 Exported variables retain their values. System variables (such as \fBPS1\fR,
88 \fBPS2\fR, \fBPATH\fR, \fBMAIL\fR, and \fBHOME\fR), are reset to default values
89 unless they have been exported by the system or the user. For example, when a
90 user has a primary prompt string (\fBPS1\fR) other than \fB$\fR (default) and
91 has not exported \fBPS1\fR, the user's \fBPS1\fR is set to the default prompt
92 string \fB$\fR, even if \fBnewgrp\fR terminates with an error. Note that the
93 shell command \fBexport\fR (see \fBsh\fR(1) and \fBset\fR(1)) is the method to
94 export variables so that they retain their assigned value when invoking new
95 shells.
96 .sp
97 .LP
98 With no operands and options, \fBnewgrp\fR changes the user's group IDs (real
99 and effective) back to the group specified in the user's password file entry.
100 This is a way to exit the effect of an earlier \fBnewgrp\fR command.
101 .sp
102 .LP
103 A password is demanded if the group has a password and the user is not listed
104 in \fB/etc/group\fR as being a member of that group. The only way to create a
105 password for a group is to use \fBpasswd\fR(1), then cut and paste the password
106 from \fB/etc/shadow\fR to \fB/etc/group\fR. Group passwords are antiquated and
107 not often used.
108 .SS "sh Built-in"
109 .sp
110 .LP
111 Equivalent to \fBexec\fR \fBnewgrp\fR \fIargument\fR where \fIargument\fR
112 represents the options and/or operand of the \fBnewgrp\fR command.
113 .SS "ksh Built-in"
114 .sp
115 .LP
116 Equivalent to \fBexec\fR to\fB/bin/newgrp\fR \fIargument\fR where
117 \fIargument\fR represents the options and/or operand of the \fBnewgrp\fR
118 command.
119 .sp
120 .LP
121 On this man page, \fBksh\fR(1) commands that are preceded by one or two \fB*\fR
122 (asterisks) are treated specially in the following ways:
123 .RS +4
124 .TP
125 1.
126 Variable assignment lists preceding the command remain in effect when the
127 command completes.
128 .RE
129 .RS +4
130 .TP
131 2.
132 I/O redirections are processed after variable assignments.
133 .RE
134 .RS +4
135 .TP
136 3.
137 Errors cause a script that contains them to abort.
138 .RE
139 .RS +4
140 .TP
141 4.
142 Words, following a command preceded by \fB**\fR that are in the format of a
143 variable assignment, are expanded with the same rules as a variable assignment.
144 This means that tilde substitution is performed after the \fB=\fR sign and word
145 splitting and file name generation are not performed.
146 .RE
147 .SS "ksh93 Built-in"
148 .sp
149 .LP
150 Equivalent to \fBexec\fR to\fB/bin/newgrp\fR \fIargument\fR where
151 \fIargument\fR represents the options and/or operand of the \fBnewgrp\fR
152 command.
153 .sp
154 .LP
155 On this man page, \fBksh93\fR(1) commands that are preceded by one or two
156 \fB+\fR (plus signs) are treated specially in the following ways:
157 .RS +4
158 .TP
159 1.
160 Variable assignment lists preceding the command remain in effect when the
161 command completes.
162 .RE
163 .RS +4
164 .TP
165 2.
166 I/O redirections are processed after variable assignments.
167 .RE
168 .RS +4
169 .TP
170 3.
171 Errors cause a script that contains them to abort.
172 .RE
173 .RS +4
174 .TP
175 4.
176 They are not valid function names.
177 .RE
178 .RS +4
179 .TP
180 5.
181 Words, following a command preceded by \fB++\fR that are in the format of a
182 variable assignment, are expanded with the same rules as a variable assignment.
183 This means that tilde substitution is performed after the \fB=\fR sign and
184 field splitting and file name generation are not performed.
185 .RE
186 .SH OPTIONS
187 .sp
188 .LP
189 The following option is supported:
190 .sp
191 .ne 2
192 .na
193 \fB\fB-l\fR | \fB\(mi\fR\fR
194 .ad
195 .RS 13n
196 Change the environment to what would be expected if the user actually logged in
197 again as a member of the new group.
198 .RE
200 .SH OPERANDS
201 .sp
202 .LP
203 The following operands are supported:
204 .sp
205 .ne 2
206 .na
207 \fB\fIgroup\fR\fR
208 .ad
209 .RS 12n
210 A group name from the group database or a non-negative numeric group ID.
211 Specifies the group ID to which the real and effective group IDs is set. If
212 \fIgroup\fR is a non-negative numeric string and exists in the group database
213 as a group name (see \fBgetgrnam\fR(3C)), the numeric group ID associated with
214 that group name is used as the group ID.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fIargument\fR\fR
221 .ad
222 .RS 12n
223 \fBsh\fR and \fBksh\fR only. Options and/or operand of the \fBnewgrp\fR
224 command.
225 .RE
227 .SH ENVIRONMENT VARIABLES
228 .sp
229 .LP
230 See \fBenviron\fR(5) for descriptions of the following environment variables
231 that affect the execution of \fBnewgrp\fR: \fBLANG\fR, \fBLC_ALL\fR,
232 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
233 .SH EXIT STATUS
234 .sp
235 .LP
236 If \fBnewgrp\fR succeeds in creating a new shell execution environment, whether
237 or not the group identification was changed successfully, the exit status is
238 the exit status of the shell. Otherwise, the following exit value is returned:
239 .sp
240 .ne 2
241 .na
242 \fB\fB>0\fR\fR
243 .ad
244 .RS 6n
245 An error occurred.
246 .RE
248 .SH FILES
249 .sp
250 .ne 2
251 .na
252 \fB\fB/etc/group\fR\fR
253 .ad
254 .RS 15n
255 System group file
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fB/etc/passwd\fR\fR
262 .ad
263 .RS 15n
264 System password file
265 .RE
267 .SH ATTRIBUTES
268 .sp
269 .LP
270 See \fBattributes\fR(5) for descriptions of the following attributes:
271 .SS "/usr/bin/newgrp, ksh, sh"
272 .sp
274 .sp
275 .TS
276 box;
277 c | c
278 l | l .
279 ATTRIBUTE TYPE ATTRIBUTE VALUE
280 _
281 Interface Stability Committed
282 _
283 Standard See \fBstandards\fR(5).
284 .TE
286 .SS "ksh93"
287 .sp
289 .sp
290 .TS
291 box;
292 c | c
293 l | l .
294 ATTRIBUTE TYPE ATTRIBUTE VALUE
295 _
296 Interface Stability Uncommitted
297 .TE
299 .SH SEE ALSO
300 .sp
301 .LP
302 \fBlogin\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBset\fR(1), \fBsh\fR(1),
303 \fBIntro\fR(3), \fBgetgrnam\fR(3C), \fBgroup\fR(4), \fBpasswd\fR(4),
304 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)