{
    "content": [
        {
            "type": "text",
            "text": "# env (info)\n\n## Sections\n\n- **File: coreutils.info,  Node: env invocation,  Next: nice invocation,  Prev: chroot invocation,  Up: Modified command invocation** (1 subsections)\n- **Use caution when reducing 'PATH'; behavior is not portable when 'PATH'**\n- **The '-S'/'--split-string' options enable using multiple arguments on the**\n- **Testing and troubleshooting**\n- **To test 'env -S' on the command line, use single quotes for the '-S'**\n- **Splitting arguments by whitespace**\n- **Running 'env -Sstring' splits the STRING into arguments based on**\n- **Escape sequences**\n- **Comments**\n- **Environment variable expansion**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "env",
        "section": "",
        "mode": "info",
        "summary": null,
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "File: coreutils.info,  Node: env invocation,  Next: nice invocation,  Prev: chroot invocation,  Up: Modified command invocation",
                "lines": 1,
                "subsections": [
                    {
                        "name": "23.2 'env': Run a command in a modified environment",
                        "lines": 29
                    }
                ]
            },
            {
                "name": "Use caution when reducing 'PATH'; behavior is not portable when 'PATH'",
                "lines": 164,
                "subsections": []
            },
            {
                "name": "The '-S'/'--split-string' options enable using multiple arguments on the",
                "lines": 56,
                "subsections": []
            },
            {
                "name": "Testing and troubleshooting",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "To test 'env -S' on the command line, use single quotes for the '-S'",
                "lines": 45,
                "subsections": []
            },
            {
                "name": "Splitting arguments by whitespace",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "Running 'env -Sstring' splits the STRING into arguments based on",
                "lines": 20,
                "subsections": []
            },
            {
                "name": "Escape sequences",
                "lines": 48,
                "subsections": []
            },
            {
                "name": "Comments",
                "lines": 33,
                "subsections": []
            },
            {
                "name": "Environment variable expansion",
                "lines": 53,
                "subsections": []
            }
        ],
        "sections": {
            "File: coreutils.info,  Node: env invocation,  Next: nice invocation,  Prev: chroot invocation,  Up: Modified command invocation": {
                "content": "",
                "subsections": [
                    {
                        "name": "23.2 'env': Run a command in a modified environment",
                        "content": "'env' runs a command with a modified environment.  Synopses:\n\nenv [OPTION]... [NAME=VALUE]... [COMMAND [ARGS]...]\nenv -[v]S'[OPTION]... [NAME=VALUE]... [COMMAND [ARGS]...]'\nenv\n\n'env' is commonly used on first line of scripts (shebang line):\n#!/usr/bin/env COMMAND\n#!/usr/bin/env -[v]S[OPTION]... [NAME=VALUE]... COMMAND [ARGS]...\n\nOperands of the form 'VARIABLE=VALUE' set the environment variable\nVARIABLE to value VALUE.  VALUE may be empty ('VARIABLE=').  Setting a\nvariable to an empty value is different from unsetting it.  These\noperands are evaluated left-to-right, so if two operands mention the\nsame variable the earlier is ignored.\n\nEnvironment variable names can be empty, and can contain any\ncharacters other than '=' and ASCII NUL. However, it is wise to limit\nyourself to names that consist solely of underscores, digits, and ASCII\nletters, and that begin with a non-digit, as applications like the shell\ndo not work well with other names.\n\nThe first operand that does not contain the character '=' specifies\nthe program to invoke; it is searched for according to the 'PATH'\nenvironment variable.  Any remaining arguments are passed as arguments\nto that program.  The program should not be a special built-in utility\n(*note Special built-in utilities::).\n\nModifications to 'PATH' take effect prior to searching for COMMAND."
                    }
                ]
            },
            "Use caution when reducing 'PATH'; behavior is not portable when 'PATH'": {
                "content": "is undefined or omits key directories such as '/bin'.\n\nIn the rare case that a utility contains a '=' in the name, the only\nway to disambiguate it from a variable assignment is to use an\nintermediate command for COMMAND, and pass the problematic program name\nvia ARGS.  For example, if './prog=' is an executable in the current\n'PATH':\n\nenv prog= true # runs 'true', with prog= in environment\nenv ./prog= true # runs 'true', with ./prog= in environment\nenv -- prog= true # runs 'true', with prog= in environment\nenv sh -c '\\prog= true' # runs 'prog=' with argument 'true'\nenv sh -c 'exec \"$@\"' sh prog= true # also runs 'prog='\n\nIf no command name is specified following the environment\nspecifications, the resulting environment is printed.  This is like\nspecifying the 'printenv' program.\n\nFor some examples, suppose the environment passed to 'env' contains\n'LOGNAME=rms', 'EDITOR=emacs', and 'PATH=.:/gnubin:/hacks':\n\n* Output the current environment.\n$ env | LCALL=C sort\nEDITOR=emacs\nLOGNAME=rms\nPATH=.:/gnubin:/hacks\n\n* Run 'foo' with a reduced environment, preserving only the original\n'PATH' to avoid problems in locating 'foo'.\nenv - PATH=\"$PATH\" foo\n\n* Run 'foo' with the environment containing 'LOGNAME=rms',\n'EDITOR=emacs', and 'PATH=.:/gnubin:/hacks', and guarantees that\n'foo' was found in the file system rather than as a shell built-in.\nenv foo\n\n* Run 'nemacs' with the environment containing 'LOGNAME=foo',\n'EDITOR=emacs', 'PATH=.:/gnubin:/hacks', and 'DISPLAY=gnu:0'.\nenv DISPLAY=gnu:0 LOGNAME=foo nemacs\n\n* Attempt to run the program '/energy/--' (as that is the only\npossible path search result); if the command exists, the\nenvironment will contain 'LOGNAME=rms' and 'PATH=/energy', and the\narguments will be 'e=mc2', 'bar', and 'baz'.\nenv -u EDITOR PATH=/energy -- e=mc2 bar baz\n\n\nThe program accepts the following options.  Also see *note Common\noptions::.  Options must precede operands.\n\n'-0'\n'--null'\nOutput a zero byte (ASCII NUL) at the end of each line, rather than\na newline.  This option enables other programs to parse the output\neven when that output would contain data with embedded newlines.\n\n'-u NAME'\n'--unset=NAME'\nRemove variable NAME from the environment, if it was in the\nenvironment.\n\n'-'\n'-i'\n'--ignore-environment'\nStart with an empty environment, ignoring the inherited\nenvironment.\n\n'-C DIR'\n'--chdir=DIR'\nChange the working directory to DIR before invoking COMMAND.  This\ndiffers from the shell built-in 'cd' in that it starts COMMAND as a\nsubprocess rather than altering the shell's own working directory;\nthis allows it to be chained with other commands that run commands\nin a different context.  For example:\n\n# Run 'true' with /chroot as its root directory and /srv as its working\n# directory.\nchroot /chroot env --chdir=/srv true\n# Run 'true' with /build as its working directory, FOO=bar in its\n# environment, and a time limit of five seconds.\nenv --chdir=/build FOO=bar timeout 5 true\n\n'--default-signal[=SIG]'\nUnblock and reset signal SIG to its default signal handler.\nWithout SIG all known signals are unblocked and reset to their\ndefaults.  Multiple signals can be comma-separated.  The following\ncommand runs 'seq' with SIGINT and SIGPIPE set to their default\n(which is to terminate the program):\n\nenv --default-signal=PIPE,INT seq 1000 | head -n1\n\nIn the following example, we see how this is not possible to do\nwith traditional shells.  Here the first trap command sets SIGPIPE\nto ignore.  The second trap command ostensibly sets it back to its\ndefault, but POSIX mandates that the shell must not change\ninherited state of the signal - so it is a no-op.\n\ntrap '' PIPE && sh -c 'trap - PIPE ; seq inf | head -n1'\n\nUsing '--default-signal=PIPE' we can ensure the signal handling is\nset to its default behavior:\n\ntrap '' PIPE && sh -c 'env --default-signal=PIPE seq inf | head -n1'\n\n'--ignore-signal[=SIG]'\nIgnore signal SIG when running a program.  Without SIG all known\nsignals are set to ignore.  Multiple signals can be\ncomma-separated.  The following command runs 'seq' with SIGINT set\nto be ignored - pressing 'Ctrl-C' will not terminate it:\n\nenv --ignore-signal=INT seq inf > /dev/null\n\n'SIGCHLD' is special, in that '--ignore-signal=CHLD' might have no\neffect (POSIX says it's unspecified).\n\nMost operating systems do not allow ignoring 'SIGKILL', 'SIGSTOP'\n(and possibly other signals).  Attempting to ignore these signals\nwill fail.\n\nMultiple (and contradictory) '--default-signal=SIG' and\n'--ignore-signal=SIG' options are processed left-to-right, with the\nlatter taking precedence.  In the following example, 'SIGPIPE' is\nset to default while 'SIGINT' is ignored:\n\nenv --default-signal=INT,PIPE --ignore-signal=INT\n\n'--block-signal[=SIG]'\nBlock signal(s) SIG from being delivered.\n\n'--list-signal-handling'\nList blocked or ignored signals to stderr, before executing a\ncommand.\n\n'-v'\n'--debug'\nShow verbose information for each processing step.\n\n$ env -v -uTERM A=B uname -s\nunset:    TERM\nsetenv:   A=B\nexecuting: uname\narg[0]= 'uname'\narg[1]= '-s'\nLinux\n\nWhen combined with '-S' it is recommended to list '-v' first, e.g.\n'env -vS'string''.\n\n'-S STRING'\n'--split-string=STRING'\nprocess and split STRING into separate arguments used to pass\nmultiple arguments on shebang lines.  'env' supports FreeBSD's\nsyntax of several escape sequences and environment variable\nexpansions.  See below for details and examples.\n\nExit status:\n\n0   if no COMMAND is specified and the environment is output\n125 if 'env' itself fails\n126 if COMMAND is found but cannot be invoked\n127 if COMMAND cannot be found\nthe exit status of COMMAND otherwise\n\n",
                "subsections": []
            },
            "The '-S'/'--split-string' options enable using multiple arguments on the": {
                "content": "first one of scripts (shebang line, '#!').\n\nWhen a script's interpreter is in a known location, scripts typically\ncontain the absolute file name in their first line:\n\nShell script:         #!/bin/sh\necho hello\n\nPerl script:          #!/usr/bin/perl\nprint \"hello\\n\";\n\nPython script:        #!/usr/bin/python3\nprint(\"hello\")\n\n\nWhen a script's interpreter is in a non-standard location in the\n'PATH' environment variable, it is recommended to use 'env' on the first\nline of the script to find the executable and run it:\n\nShell script:         #!/usr/bin/env bash\necho hello\n\nPerl script:          #!/usr/bin/env perl\nprint \"hello\\n\";\n\nPython script:        #!/usr/bin/env python3\nprint(\"hello\")\n\n\nMost operating systems (e.g.  GNU/Linux, BSDs) treat all text after\nthe first space as a single argument.  When using 'env' in a script it\nis thus not possible to specify multiple arguments.\n\nIn the following example:\n#!/usr/bin/env perl -T -w\nprint \"hello\\n\";\n\nThe operating system treats 'perl -T -w' as one argument (the\nprogram's name), and executing the script fails with:\n\n/usr/bin/env: 'perl -T -w': No such file or directory\n\nThe '-S' option instructs 'env' to split the single string into\nmultiple arguments.  The following example works as expected:\n\n$ cat hello.pl\n#!/usr/bin/env -S perl -T -w\nprint \"hello\\n\";\n\n$ chmod a+x hello.pl\n$ ./hello.pl\nhello\n\nAnd is equivalent to running 'perl -T -w hello.pl' on the command\nline prompt.\n",
                "subsections": []
            },
            "Testing and troubleshooting": {
                "content": "...........................\n",
                "subsections": []
            },
            "To test 'env -S' on the command line, use single quotes for the '-S'": {
                "content": "string to emulate a single paramter.  Single quotes are not needed when\nusing 'env -S' in a shebang line on the first line of a script (the\noperating system already treats it as one argument).\n\nThe following command is equivalent to the 'hello.pl' script above:\n\n$ env -S'perl -T -w' hello.pl\n\nTo troubleshoot '-S' usage add the '-v' as the first argument (before\n'-S').\n\nUsing '-vS' on a shebang line in a script:\n\n$ cat hello-debug.pl\n#!/usr/bin/env -vS perl -T -w\nprint \"hello\\n\";\n\n$ chmod a+x hello-debug.pl\n$ ./hello-debug.pl\nsplit -S:  'perl -T -w'\ninto:    'perl'\n&    '-T'\n&    '-w'\nexecuting: perl\narg[0]= 'perl'\narg[1]= '-T'\narg[2]= '-w'\narg[3]= './hello-debug.pl'\nhello\n\nUsing '-vS' on the command line prompt (adding single quotes):\n\n$ env -vS'perl -T -w' hello-debug.pl\nsplit -S:  'perl -T -w'\ninto:    'perl'\n&    '-T'\n&    '-w'\nexecuting: perl\narg[0]= 'perl'\narg[1]= '-T'\narg[2]= '-w'\narg[3]= 'hello-debug.pl'\nhello\n\n",
                "subsections": []
            },
            "Splitting arguments by whitespace": {
                "content": ".................................\n",
                "subsections": []
            },
            "Running 'env -Sstring' splits the STRING into arguments based on": {
                "content": "unquoted spaces or tab characters.\n\nIn the following contrived example the 'awk' variable 'OFS' will be\n'<space>xyz<space>' as these spaces are inside double quotes.  The other\nspace characters are used as argument separators:\n\n$ cat one.awk\n#!/usr/bin/env -S awk -v OFS=\" xyz \" -f\nBEGIN {print 1,2,3}\n\n$ chmod a+x one.awk\n$ ./one.awk\n1 xyz 2 xyz 3\n\nWhen using '-S' on the command line prompt, remember to add single\nquotes around the entire string:\n\n$ env -S'awk -v OFS=\" xyz \" -f' one.awk\n1 xyz 2 xyz 3\n",
                "subsections": []
            },
            "Escape sequences": {
                "content": "................\n\n'env' supports several escape sequences.  These sequences are processed\nwhen unquoted or inside double quotes (unless otherwise noted).  Single\nquotes disable escape sequences except '\\'' and '\\\\'.\n\n'\\c'    Ignore the remaining characters in the string.  Cannot be used\ninside double quotes.\n\n'\\f'    form-feed character (ASCII 0x0C)\n\n'\\n'    new-line character (ASCII 0x0A)\n\n'\\r'    carriage-return character (ASCII 0x0D)\n\n'\\t'    tab character (ASCII 0x09)\n\n'\\v'    vertical tab character (ASCII 0x0B)\n\n'\\#'    A hash '#' character.  Used when a '#' character is needed as\nthe first character of an argument (see 'comments' section\nbelow).\n\n'\\$'    A dollar-sign character '$'.  Unescaped '$' characters are used\nto expand environment variables (see 'variables' section\nbelow).\n\n'\\'    Inside double-quotes, replaced with a single space character.\nOutside quotes, treated as an argument separator.  '\\' can be\nused to avoid space characters in a shebang line (see examples\nbelow).\n\n'\\\"'    A double-quote character.\n\n'\\''    A single-quote character.  This escape sequence works inside\nsingle-quoted strings.\n\n'\\\\'    A backslash character.  This escape sequence works inside\nsingle-quoted strings.\n\n\nThe following 'awk' script will use tab character as input and output\nfield separator (instead of spaces and tabs):\n\n$ cat tabs.awk\n#!/usr/bin/env -S awk -v FS=\"\\t\" -v OFS=\"\\t\" -f\n...\n",
                "subsections": []
            },
            "Comments": {
                "content": "........\n\nThe escape sequence '\\c' (used outside single/double quotes) causes\n'env' to ignore the rest of the string.\n\nThe '#' character causes 'env' to ignore the rest of the string when\nit appears as the first character of an argument.  Use '\\#' to reverse\nthis behavior.\n\n$ env -S'printf %s\\n A B C'\nA\nB\nC\n\n$ env -S'printf %s\\n A# B C'\nA#\nB\nC\n\n$ env -S'printf %s\\n A #B C'\nA\n\n$ env -S'printf %s\\n A \\#B C'\nA\n#B\nC\n\n$ env -S'printf %s\\n A\\cB C'\nA\n\nNOTE: The above examples use single quotes as they are executed on\nthe command-line.\n",
                "subsections": []
            },
            "Environment variable expansion": {
                "content": "..............................\n\nThe pattern '${VARNAME}' is used to substitute a value from the\nenvironment variable.  The pattern must include the curly braces\n('{','}').  Without them 'env' will reject the string.  Special shell\nvariables (such as '$@', '$*', '$$') are not supported.\n\nIf the environment variable is empty or not set, the pattern will be\nreplaced by an empty string.  The value of '${VARNAME}' will be that of\nthe executed 'env', before any modifications using\n'-i'/'--ignore-environment'/'-u'/'--unset' or setting new values using\n'VAR=VALUE'.\n\nThe following python script prepends '/opt/custom/modules' to the\npython module search path environment variable ('PYTHONPATH'):\n\n$ cat custom.py\n#!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:${PYTHONPATH} python\nprint \"hello\"\n...\n\nThe expansion of '${PYTHONPATH}' is performed by 'env', not by a\nshell.  If the curly braces are omitted, 'env' will fail:\n\n$ cat custom.py\n#!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$PYTHONPATH python\nprint \"hello\"\n...\n\n$ chmod a+x custom.py\n$ custom.py\n/usr/bin/env: only ${VARNAME} expansion is supported, error at: $PYTHONPATH python\n\nEnvironment variable expansion happens before clearing the\nenvironment (with '-i') or unsetting specific variables (with '-u'):\n\n$ env -S'-i OLDUSER=${USER} env'\nOLDUSER=gordon\n\nUse '-v' to diagnose the operations step-by-step:\n\n$ env -vS'-i OLDUSER=${USER} env'\nexpanding ${USER} into 'gordon'\nsplit -S:  '-i OLDUSER=${USER} env'\ninto:    '-i'\n&    'OLDUSER=gordon'\n&    'env'\ncleaning environ\nsetenv:   OLDUSER=gordon\nexecuting: env\narg[0]= 'env'\nOLDUSER=gordon\n",
                "subsections": []
            }
        }
    }
}