break.1p (5628B)
- '\" et
- .TH BREAK "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
- break
- \(em exit from for, while, or until loop
- .SH SYNOPSIS
- .LP
- .nf
- break \fB[\fIn\fB]\fR
- .fi
- .SH DESCRIPTION
- If
- .IR n
- is specified, the
- .IR break
- utility shall exit from the
- .IR n th
- enclosing
- .BR for ,
- .BR while ,
- or
- .BR until
- loop. If
- .IR n
- is not specified,
- .IR break
- shall behave as if
- .IR n
- was specified as 1. Execution shall continue with the command
- immediately following the exited loop. The value of
- .IR n
- is a positive decimal integer. If
- .IR n
- is greater than the number of enclosing loops, the outermost enclosing
- loop shall be exited. If there is no enclosing loop, the behavior is
- unspecified.
- .P
- A loop shall enclose a
- .IR break
- or
- .IR continue
- command if the loop lexically encloses the command. A loop lexically
- encloses a
- .IR break
- or
- .IR continue
- command if the command is:
- .IP " *" 4
- Executing in the same execution environment (see
- .IR "Section 2.12" ", " "Shell Execution Environment")
- as the compound-list of the loop's do-group (see
- .IR "Section 2.10.2" ", " "Shell Grammar Rules"),
- and
- .IP " *" 4
- Contained in a compound-list associated with the loop (either in the
- compound-list of the loop's do-group or, if the loop is a
- .BR while
- or
- .BR until
- loop, in the compound-list following the
- .BR while
- or
- .BR until
- reserved word), and
- .IP " *" 4
- Not in the body of a function whose function definition command (see
- .IR "Section 2.9.5" ", " "Function Definition Command")
- is contained in a compound-list associated with the loop.
- .P
- If
- .IR n
- is greater than the number of lexically enclosing loops and there is a
- non-lexically enclosing loop in progress in the same execution
- environment as the
- .IR break
- or
- .IR continue
- command, it is unspecified whether that loop encloses the command.
- .SH OPTIONS
- None.
- .SH OPERANDS
- See the DESCRIPTION.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- None.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- Not used.
- .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
- Successful completion.
- .IP >0 6
- The
- .IR n
- value was not an unsigned decimal integer greater than or equal to 1.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- None.
- .SH EXAMPLES
- .LP
- .nf
- for i in *
- do
- if test -d "$i"
- then break
- fi
- done
- .fi
- .P
- The results of running the following example are unspecified: there
- are two loops in progress when the
- .IR break
- command is executed, and they are in the same execution environment,
- but neither loop is lexically enclosing the
- .IR break
- command. (There are no loops lexically enclosing the
- .IR continue
- commands, either.)
- .LP
- .nf
- foo() {
- for j in 1 2; do
- echo \(aqbreak 2\(aq >/tmp/do_break
- echo " sourcing /tmp/do_break ($j)..."
- # the behavior of the break from running the following command
- # results in unspecified behavior:
- . /tmp/do_break
- .P
- do_continue() { continue 2; }
- echo " running do_continue ($j)..."
- # the behavior of the continue in the following function call
- # results in unspecified behavior (if execution reaches this
- # point):
- do_continue
- .P
- trap \(aqcontinue 2\(aq USR1
- echo " sending SIGUSR1 to self ($j)..."
- # the behavior of the continue in the trap invoked from the
- # following signal results in unspecified behavior (if
- # execution reaches this point):
- kill -s USR1 $$
- sleep 1
- done
- }
- for i in 1 2; do
- echo "running foo ($i)..."
- foo
- done
- .fi
- .SH "RATIONALE"
- In early proposals, consideration was given to expanding the syntax of
- .IR break
- and
- .IR continue
- to refer to a label associated with the appropriate loop as a
- preferable alternative to the
- .IR n
- method. However, this volume of POSIX.1\(hy2017 does reserve the name space of command names
- ending with a
- <colon>.
- It is anticipated that a future implementation could take advantage of
- this and provide something like:
- .sp
- .RS 4
- .nf
- outofloop: for i in a b c d e
- do
- for j in 0 1 2 3 4 5 6 7 8 9
- do
- if test -r "${i}${j}"
- then break outofloop
- fi
- done
- done
- .fi
- .P
- .RE
- .P
- and that this might be standardized after implementation experience is
- achieved.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.14" ", " "Special Built-In Utilities"
- .\"
- .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 .