newgrp.1p (10351B)
- '\" et
- .TH NEWGRP "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- newgrp
- \(em change to a new group
- .SH SYNOPSIS
- .LP
- .nf
- newgrp \fB[\fR-l\fB] [\fIgroup\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR newgrp
- utility shall create a new shell execution environment with a new real
- and effective group identification. Of the attributes listed in
- .IR "Section 2.12" ", " "Shell Execution Environment",
- 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
- .IR set
- options may be lost). All other aspects of the process environment
- that are preserved by the
- .IR exec
- family of functions defined in the System Interfaces volume of POSIX.1\(hy2017 shall also be preserved by
- .IR newgrp ;
- whether other aspects are preserved is unspecified.
- .P
- 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.
- .P
- The
- .IR newgrp
- utility shall affect the supplemental groups for the process as
- follows:
- .IP " *" 4
- 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 4
- .IP -- 4
- If the new effective group ID is also in the supplementary group list,
- .IR newgrp
- shall change the effective group ID.
- .IP -- 4
- If the new effective group ID is not in the supplementary group list,
- .IR newgrp
- shall add the new effective group ID to the list, if there is room to
- add it.
- .RE
- .IP " *" 4
- 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 4
- .IP -- 4
- If the new effective group ID is in the supplementary group list,
- .IR newgrp
- shall delete it.
- .IP -- 4
- If the old effective group ID is not in the supplementary list,
- .IR newgrp
- shall add it if there is room.
- .RE
- .TP 10
- .BR Note:
- The System Interfaces volume of POSIX.1\(hy2017 does not specify whether the effective group ID of a process
- is included in its supplementary group list.
- .P
- .P
- With no operands,
- .IR newgrp
- 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.
- .P
- If the first argument is
- .BR '\-' ,
- the results are unspecified.
- .P
- 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
- .IR newgrp
- to write a diagnostic message and suppress the changing of the group
- identification.
- .SH OPTIONS
- The
- .IR newgrp
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines",
- except for the unspecified usage of
- .BR '\-' .
- .P
- The following option shall be supported:
- .IP "\fB\-l\fP" 10
- (The letter ell.) Change the environment to what would be expected if
- the user actually logged in again.
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fIgroup\fR" 10
- 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
- .IR group
- is a non-negative numeric string and exists in the group database as a
- group name (see
- \fIgetgrnam\fR()),
- the numeric group ID associated with that group name shall be used as
- the group ID.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- The file
- .BR /dev/tty
- shall be used to read a single line of text for password checking, when
- one is required.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR newgrp :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- Not used.
- .SH STDERR
- 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"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- If
- .IR newgrp
- 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:
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- The invoking shell may terminate.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- 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.
- .P
- A common implementation of
- .IR newgrp
- is that the current shell uses
- .IR exec
- to overlay itself with
- .IR newgrp ,
- which in turn overlays itself with a new shell after changing group.
- On some implementations, however, this may not occur and
- .IR newgrp
- may be invoked as a subprocess.
- .P
- The
- .IR newgrp
- command is intended only for use from an interactive terminal. It does
- not offer a useful interface for the support of applications.
- .P
- The exit status of
- .IR newgrp
- is generally inapplicable. If
- .IR newgrp
- 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,
- .IR newgrp
- displays diagnostic messages to indicate problems. But usage such as:
- .sp
- .RS 4
- .nf
- newgrp foo
- echo $?
- .fi
- .P
- .RE
- .P
- is not useful because the new shell might not have access to any status
- .IR newgrp
- 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
- .IR newgrp
- with the
- .IR id
- command provides a portable means of determining whether the group
- change was successful or not.
- .SH EXAMPLES
- None.
- .SH RATIONALE
- Most historical implementations use one of the
- .IR exec
- functions to implement the behavior of
- .IR newgrp .
- Errors detected before the
- .IR exec
- leave the environment unchanged, while errors detected after the
- .IR exec
- leave the user in a changed environment. While it would be useful to
- have
- .IR newgrp
- issue a diagnostic message to tell the user that the environment
- changed, it would be inappropriate to require this change to some
- historical implementations.
- .P
- The password mechanism is allowed in the group database, but how this
- would be implemented is not specified.
- .P
- The
- .IR newgrp
- utility was retained in this volume of POSIX.1\(hy2017, even given the existence of the multiple
- group permissions feature in the System Interfaces volume of POSIX.1\(hy2017, 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 POSIX.1\(hy2017; on other implementations, the group ownership
- of a newly created file is determined by the effective group ID. On
- implementations of the latter type,
- .IR newgrp
- allows files to be created with a specific group ownership. Finally,
- many implementations use the real group ID in accounting, and on such
- systems,
- .IR newgrp
- allows the accounting identity of the user to be changed.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Chapter 2" ", " "Shell Command Language",
- .IR "\fIsh\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fIexec\fR\^",
- .IR "\fIgetgrnam\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .