|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH NEWGRP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
newgrp
|
|
Packit |
7cfc04 |
\(em change to a new group
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
newgrp \fB[\fR\(mil\fB] [\fIgroup\fB]\fR
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
utility shall create a new shell execution environment with a new real
|
|
Packit |
7cfc04 |
and effective group identification. Of the attributes listed in
|
|
Packit |
7cfc04 |
.IR "Section 2.12" ", " "Shell Execution Environment",
|
|
Packit |
7cfc04 |
the new shell execution environment shall retain the working directory,
|
|
Packit |
7cfc04 |
file creation mask, and exported variables from the previous
|
|
Packit |
7cfc04 |
environment (that is, open files, traps, unexported variables, alias
|
|
Packit |
7cfc04 |
definitions, shell functions, and
|
|
Packit |
7cfc04 |
.IR set
|
|
Packit |
7cfc04 |
options may be lost). All other aspects of the process environment
|
|
Packit |
7cfc04 |
that are preserved by the
|
|
Packit |
7cfc04 |
.IR exec
|
|
Packit |
7cfc04 |
family of functions defined in the System Interfaces volume of POSIX.1\(hy2008 shall also be preserved by
|
|
Packit |
7cfc04 |
.IR newgrp ;
|
|
Packit |
7cfc04 |
whether other aspects are preserved is unspecified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
A failure to assign the new group identifications (for example, for
|
|
Packit |
7cfc04 |
security or password-related reasons) shall not prevent the new shell
|
|
Packit |
7cfc04 |
execution environment from being created.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
utility shall affect the supplemental groups for the process as
|
|
Packit |
7cfc04 |
follows:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
On systems where the effective group ID is normally in the
|
|
Packit |
7cfc04 |
supplementary group list (or whenever the old effective group ID
|
|
Packit |
7cfc04 |
actually is in the supplementary group list):
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
If the new effective group ID is also in the supplementary group list,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
shall change the effective group ID.
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
If the new effective group ID is not in the supplementary group list,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
shall add the new effective group ID to the list, if there is room to
|
|
Packit |
7cfc04 |
add it.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
On systems where the effective group ID is not normally in the
|
|
Packit |
7cfc04 |
supplementary group list (or whenever the old effective group ID is not
|
|
Packit |
7cfc04 |
in the supplementary group list):
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
If the new effective group ID is in the supplementary group list,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
shall delete it.
|
|
Packit |
7cfc04 |
.IP -- 4
|
|
Packit |
7cfc04 |
If the old effective group ID is not in the supplementary list,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
shall add it if there is room.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.TP 10
|
|
Packit |
7cfc04 |
.BR Note:
|
|
Packit |
7cfc04 |
The System Interfaces volume of POSIX.1\(hy2008 does not specify whether the effective group ID of a process
|
|
Packit |
7cfc04 |
is included in its supplementary group list.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
With no operands,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
shall change the effective group back to the groups identified in the
|
|
Packit |
7cfc04 |
user's user entry, and shall set the list of supplementary groups to
|
|
Packit |
7cfc04 |
that set in the user's group database entries.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the first argument is
|
|
Packit |
7cfc04 |
.BR '\(mi' ,
|
|
Packit |
7cfc04 |
the results are unspecified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If a password is required for the specified group, and the user is not
|
|
Packit |
7cfc04 |
listed as a member of that group in the group database, the user shall
|
|
Packit |
7cfc04 |
be prompted to enter the correct password for that group. If the user
|
|
Packit |
7cfc04 |
is listed as a member of that group, no password shall be requested.
|
|
Packit |
7cfc04 |
If no password is required for the specified group, it is
|
|
Packit |
7cfc04 |
implementation-defined whether users not listed as members of that
|
|
Packit |
7cfc04 |
group can change to that group. Whether or not a password is required,
|
|
Packit |
7cfc04 |
implementation-defined system accounting or security mechanisms may
|
|
Packit |
7cfc04 |
impose additional authorization restrictions that may cause
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
to write a diagnostic message and suppress the changing of the group
|
|
Packit |
7cfc04 |
identification.
|
|
Packit |
7cfc04 |
.SH OPTIONS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
utility shall conform to the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
|
|
Packit |
7cfc04 |
except for the unspecified usage of
|
|
Packit |
7cfc04 |
.BR '\(mi' .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The following option shall be supported:
|
|
Packit |
7cfc04 |
.IP "\fB\(mil\fP" 10
|
|
Packit |
7cfc04 |
(The letter ell.) Change the environment to what would be expected if
|
|
Packit |
7cfc04 |
the user actually logged in again.
|
|
Packit |
7cfc04 |
.SH OPERANDS
|
|
Packit |
7cfc04 |
The following operand shall be supported:
|
|
Packit |
7cfc04 |
.IP "\fIgroup\fR" 10
|
|
Packit |
7cfc04 |
A group name from the group database or a non-negative numeric group
|
|
Packit |
7cfc04 |
ID. Specifies the group ID to which the real and effective group IDs
|
|
Packit |
7cfc04 |
shall be set. If
|
|
Packit |
7cfc04 |
.IR group
|
|
Packit |
7cfc04 |
is a non-negative numeric string and exists in the group database as a
|
|
Packit |
7cfc04 |
group name (see
|
|
Packit |
7cfc04 |
\fIgetgrnam\fR()),
|
|
Packit |
7cfc04 |
the numeric group ID associated with that group name shall be used as
|
|
Packit |
7cfc04 |
the group ID.
|
|
Packit |
7cfc04 |
.SH STDIN
|
|
Packit |
7cfc04 |
Not used.
|
|
Packit |
7cfc04 |
.SH "INPUT FILES"
|
|
Packit |
7cfc04 |
The file
|
|
Packit |
7cfc04 |
.BR /dev/tty
|
|
Packit |
7cfc04 |
shall be used to read a single line of text for password checking, when
|
|
Packit |
7cfc04 |
one is required.
|
|
Packit |
7cfc04 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
7cfc04 |
The following environment variables shall affect the execution of
|
|
Packit |
7cfc04 |
.IR newgrp :
|
|
Packit |
7cfc04 |
.IP "\fILANG\fP" 10
|
|
Packit |
7cfc04 |
Provide a default value for the internationalization variables that are
|
|
Packit |
7cfc04 |
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 8.2" ", " "Internationalization Variables"
|
|
Packit |
7cfc04 |
for the precedence of internationalization variables used to determine
|
|
Packit |
7cfc04 |
the values of locale categories.)
|
|
Packit |
7cfc04 |
.IP "\fILC_ALL\fP" 10
|
|
Packit |
7cfc04 |
If set to a non-empty string value, override the values of all the
|
|
Packit |
7cfc04 |
other internationalization variables.
|
|
Packit |
7cfc04 |
.IP "\fILC_CTYPE\fP" 10
|
|
Packit |
7cfc04 |
Determine the locale for the interpretation of sequences of bytes of
|
|
Packit |
7cfc04 |
text data as characters (for example, single-byte as opposed to
|
|
Packit |
7cfc04 |
multi-byte characters in arguments).
|
|
Packit |
7cfc04 |
.IP "\fILC_MESSAGES\fP" 10
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
Determine the locale that should be used to affect the format and
|
|
Packit |
7cfc04 |
contents of diagnostic messages written to standard error.
|
|
Packit |
7cfc04 |
.IP "\fINLSPATH\fP" 10
|
|
Packit |
7cfc04 |
Determine the location of message catalogs for the processing of
|
|
Packit |
7cfc04 |
.IR LC_MESSAGES .
|
|
Packit |
7cfc04 |
.SH "ASYNCHRONOUS EVENTS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.SH STDOUT
|
|
Packit |
7cfc04 |
Not used.
|
|
Packit |
7cfc04 |
.SH STDERR
|
|
Packit |
7cfc04 |
The standard error shall be used for diagnostic messages and a prompt
|
|
Packit |
7cfc04 |
string for a password, if one is required. Diagnostic messages may be
|
|
Packit |
7cfc04 |
written in cases where the exit status is not available. See the EXIT
|
|
Packit |
7cfc04 |
STATUS section.
|
|
Packit |
7cfc04 |
.SH "OUTPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXTENDED DESCRIPTION"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXIT STATUS"
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
succeeds in creating a new shell execution environment, whether or not
|
|
Packit |
7cfc04 |
the group identification was changed successfully, the exit status
|
|
Packit |
7cfc04 |
shall be the exit status of the shell. Otherwise, the following exit
|
|
Packit |
7cfc04 |
value shall be returned:
|
|
Packit |
7cfc04 |
.IP >0 6
|
|
Packit |
7cfc04 |
An error occurred.
|
|
Packit |
7cfc04 |
.SH "CONSEQUENCES OF ERRORS"
|
|
Packit |
7cfc04 |
The invoking shell may terminate.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
There is no convenient way to enter a password into the group
|
|
Packit |
7cfc04 |
database. Use of group passwords is not encouraged, because by their
|
|
Packit |
7cfc04 |
very nature they encourage poor security practices. Group passwords
|
|
Packit |
7cfc04 |
may disappear in the future.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
A common implementation of
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
is that the current shell uses
|
|
Packit |
7cfc04 |
.IR exec
|
|
Packit |
7cfc04 |
to overlay itself with
|
|
Packit |
7cfc04 |
.IR newgrp ,
|
|
Packit |
7cfc04 |
which in turn overlays itself with a new shell after changing group.
|
|
Packit |
7cfc04 |
On some implementations, however, this may not occur and
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
may be invoked as a subprocess.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
command is intended only for use from an interactive terminal. It does
|
|
Packit |
7cfc04 |
not offer a useful interface for the support of applications.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The exit status of
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
is generally inapplicable. If
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
is used in a script, in most cases it successfully invokes a new shell
|
|
Packit |
7cfc04 |
and the rest of the original shell script is bypassed when the new
|
|
Packit |
7cfc04 |
shell exits. Used interactively,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
displays diagnostic messages to indicate problems. But usage such as:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
newgrp foo
|
|
Packit |
7cfc04 |
echo $?
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
is not useful because the new shell might not have access to any status
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
may have generated (and most historical systems do not provide this
|
|
Packit |
7cfc04 |
status). A zero status echoed here does not necessarily indicate that
|
|
Packit |
7cfc04 |
the user has changed to the new group successfully. Following
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
with the
|
|
Packit |
7cfc04 |
.IR id
|
|
Packit |
7cfc04 |
command provides a portable means of determining whether the group
|
|
Packit |
7cfc04 |
change was successful or not.
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
Most historical implementations use one of the
|
|
Packit |
7cfc04 |
.IR exec
|
|
Packit |
7cfc04 |
functions to implement the behavior of
|
|
Packit |
7cfc04 |
.IR newgrp .
|
|
Packit |
7cfc04 |
Errors detected before the
|
|
Packit |
7cfc04 |
.IR exec
|
|
Packit |
7cfc04 |
leave the environment unchanged, while errors detected after the
|
|
Packit |
7cfc04 |
.IR exec
|
|
Packit |
7cfc04 |
leave the user in a changed environment. While it would be useful to
|
|
Packit |
7cfc04 |
have
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
issue a diagnostic message to tell the user that the environment
|
|
Packit |
7cfc04 |
changed, it would be inappropriate to require this change to some
|
|
Packit |
7cfc04 |
historical implementations.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The password mechanism is allowed in the group database, but how this
|
|
Packit |
7cfc04 |
would be implemented is not specified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
utility was retained in this volume of POSIX.1\(hy2008, even given the existence of the multiple
|
|
Packit |
7cfc04 |
group permissions feature in the System Interfaces volume of POSIX.1\(hy2008, for several reasons. First, in
|
|
Packit |
7cfc04 |
some implementations, the group ownership of a newly created file is
|
|
Packit |
7cfc04 |
determined by the group of the directory in which the file is created,
|
|
Packit |
7cfc04 |
as allowed by the System Interfaces volume of POSIX.1\(hy2008; on other implementations, the group ownership
|
|
Packit |
7cfc04 |
of a newly created file is determined by the effective group ID. On
|
|
Packit |
7cfc04 |
implementations of the latter type,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
allows files to be created with a specific group ownership. Finally,
|
|
Packit |
7cfc04 |
many implementations use the real group ID in accounting, and on such
|
|
Packit |
7cfc04 |
systems,
|
|
Packit |
7cfc04 |
.IR newgrp
|
|
Packit |
7cfc04 |
allows the accounting identity of the user to be changed.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "Chapter 2" ", " "Shell Command Language",
|
|
Packit |
7cfc04 |
.IR "\fIsh\fR\^"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 8" ", " "Environment Variables",
|
|
Packit |
7cfc04 |
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The System Interfaces volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fIexec\fR\^",
|
|
Packit |
7cfc04 |
.IR "\fIgetgrnam\fR\^(\|)"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|