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