readonly.1p (4603B)
- '\" et
- .TH READONLY "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
- readonly
- \(em set the readonly attribute for variables
- .SH SYNOPSIS
- .LP
- .nf
- readonly name\fB[\fR=\fIword\fB]\fR...
- .P
- readonly\fR -p
- .fi
- .SH DESCRIPTION
- The variables whose
- .IR name s
- are specified shall be given the
- .IR readonly
- attribute. The values of variables with the
- .IR readonly
- attribute cannot be changed by subsequent assignment, nor can those
- variables be unset by the
- .IR unset
- utility. If the name of a variable is followed by =\c
- .IR word ,
- then the value of that variable shall be set to
- .IR word .
- .P
- The
- .IR readonly
- special built-in shall support the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- When
- .BR \-p
- is specified,
- .IR readonly
- writes to the standard output the names and values of all read-only
- variables, in the following format:
- .sp
- .RS 4
- .nf
- "readonly %s=%s\en", <\fIname\fR>, <\fIvalue\fR>
- .fi
- .P
- .RE
- .P
- if
- .IR name
- is set, and
- .sp
- .RS 4
- .nf
- "readonly %s\en", <\fIname\fR>
- .fi
- .P
- .RE
- .P
- if
- .IR name
- is unset.
- .P
- The shell shall format the output, including the proper use of quoting,
- so that it is suitable for reinput to the shell as commands that
- achieve the same value and
- .IR readonly
- attribute-setting results in a shell execution environment in which:
- .IP " 1." 4
- Variables with values at the time they were output do not have the
- .IR readonly
- attribute set.
- .IP " 2." 4
- Variables that were unset at the time they were output do not have a
- value at the time at which the saved output is reinput to the shell.
- .P
- When no arguments are given, the results are unspecified.
- .SH OPTIONS
- See the DESCRIPTION.
- .SH OPERANDS
- See the DESCRIPTION.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- None.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- See the DESCRIPTION.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- .IP "\00" 6
- All
- .IR name
- operands were successfully marked readonly.
- .IP >0 6
- At least one
- .IR name
- could not be marked readonly, or the
- .BR \-p
- option was specified and an error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- None.
- .SH EXAMPLES
- .LP
- .nf
- readonly HOME PWD
- .fi
- .SH "RATIONALE"
- Some historical shells preserve the
- .IR readonly
- attribute across separate invocations. This volume of POSIX.1\(hy2017 allows this behavior,
- but does not require it.
- .P
- The
- .BR \-p
- option allows portable access to the values that can be saved and then
- later restored using, for example, a
- .IR dot
- script. Also see the RATIONALE for
- .IR "\fIexport\fR\^"
- for a description of the no-argument and
- .BR \-p
- output cases and a related example.
- .P
- Read-only functions were considered, but they were omitted as not being
- historical practice or particularly useful. Furthermore, functions must
- not be read-only across invocations to preclude ``spoofing''
- (spoofing is the term for the practice of creating a program that acts
- like a well-known utility with the intent of subverting the real intent
- of the user) of administrative or security-relevant (or
- security-conscious) shell scripts.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.14" ", " "Special Built-In Utilities"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .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 .