[PATCH v1] man/man7/environ.7: Fix underspecification of "name=value" strings

[PATCH v1] man/man7/environ.7: Fix underspecification of "name=value" strings

[Jason Yundt]

Before this change, environ(7) said this:

> By convention, the strings in environ have the form "name=value".  The
> name is case-sensitive and may not contain the character "=".  The
> value can be anything that can be represented as a string.  The name
> and the value may not contain an embedded null byte ('\0'), since this
> is assumed to terminate the string.

That description has a few problems:

1. It talks about ‘the character "="’, but it doesn’t specify what
   character encoding would be used to represent that character.  Two
   different character encodings could represent that same “=” character
   using two different bytes (or even sequences of bytes).

2. It mentions that ‘The name is case-sensitive and may not contain the
   character "=".’  It doesn’t clearly say what what is allowed to be in
   a name.  It only says that those two things are explicitly
   disallowed.

This change fixes those two problems.  For the first problem, this
change makes it so that the description is all about bytes, not
characters.  Describing the format in terms of bytes allows us to
sidestep the question of character encoding entirely.  Additionally, it
is more accurate to describe strings in environ as being sequences of
bytes instead of sequences of characters.  Both the name and value of an
environment variable could be sequences of bytes that don’t contain any
characters at all.

For the second problem, this change clarifies that the name of an
environment variable can contain any byte except for 0x3D.  It also
clarifies that while it’s OK for environment variable values to be
empty, it’s not OK for environment variable names to be empty.

Additionally, this change replaces "=" with '='.  In the C programming
language, "=" refers to two bytes: one for the equals character plus one
for the terminating null byte.  In the C programming language, '='
refers to a single byte.  In this particular instance, we’re talking
about a single byte, so it’s better to use '='.  Using '=' also makes
environ(7) more internally consistent.  Before this change, environ(7)
used '\0' and "=".  This change makes it so that environ(7) uses '\0'
and '='.

I was able to obtain obtain the information that I needed in order to
create this change by writing a test program.  You can find the test
program here [1].  Additionally, I got the information about the setenv(3)
and unsetenv(3) functions from their man pages (specifically, the parts
of their man pages that talk about EINVAL).

[1]: <https://codeberg.org/JasonYundt/environ-format-example-program>

Signed-off-by: Jason Yundt <jason@jasonyundt.email>
---
 man/man7/environ.7 | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/man/man7/environ.7 b/man/man7/environ.7
index 31a69017cf75..bf5726e32429 100644
--- a/man/man7/environ.7
+++ b/man/man7/environ.7
@@ -28,12 +28,23 @@ .SH DESCRIPTION
 .I environ
 have the form
 .RI \[dq] name\f[B]=\f[]value \[dq].
-The name is case-sensitive and may not contain
-the character
-.RB \[dq] = \[dq].
-The value can be anything that can be represented as a string.
-The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
-since this is assumed to terminate the string.
+The name is case-sensitive
+and may contain any byte
+other than null (\[aq]\[rs]0\[aq]) and 0x3D (the
+.BR ascii (7)
+.RB \[aq] = \[aq]
+character).
+The name must be at least one byte long,
+or else programs will not be able to manipulate it using the
+.BR setenv (3)
+or
+.BR unsetenv (3)
+functions.
+Immediately after the name, there should be a 0x3D byte.
+Immediately after the 0x3D byte is the value.
+The value may contain any byte except for null.
+The value may be zero bytes long.
+Immediately after the value, there must be a terminating null byte.
 .P
 Environment variables may be placed in the shell's environment by the
 .I export

Range-diff against v0:
-:  ------------ > 1:  d5b0d9b86029 man/man7/environ.7: Fix underspecification of "name=value" strings
-- 
2.54.0

Re: [PATCH v1] man/man7/environ.7: Fix underspecification of "name=value" strings

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 5407 bytes --]

Hi Jason,

On 2026-07-06T10:26:20-0400, Jason Yundt wrote:
> Before this change, environ(7) said this:
> 
> > By convention, the strings in environ have the form "name=value".  The
> > name is case-sensitive and may not contain the character "=".  The
> > value can be anything that can be represented as a string.  The name
> > and the value may not contain an embedded null byte ('\0'), since this
> > is assumed to terminate the string.
> 
> That description has a few problems:
> 
> 1. It talks about ‘the character "="’, but it doesn’t specify what
>    character encoding would be used to represent that character.  Two
>    different character encodings could represent that same “=” character
>    using two different bytes (or even sequences of bytes).

POSIX says that '=' is part of the portable character set.  Do we really
need to care about the value of '='?  Is this really possible?

> 2. It mentions that ‘The name is case-sensitive and may not contain the
>    character "=".’  It doesn’t clearly say what what is allowed to be in
>    a name.  It only says that those two things are explicitly
>    disallowed.

Anything else is allowed, obviously.

> This change fixes those two problems.  For the first problem, this
> change makes it so that the description is all about bytes, not
> characters.  Describing the format in terms of bytes allows us to
> sidestep the question of character encoding entirely.  Additionally, it
> is more accurate to describe strings in environ as being sequences of
> bytes instead of sequences of characters.  Both the name and value of an
> environment variable could be sequences of bytes that don’t contain any
> characters at all.
> 
> For the second problem, this change clarifies that the name of an
> environment variable can contain any byte except for 0x3D.  It also
> clarifies that while it’s OK for environment variable values to be
> empty, it’s not OK for environment variable names to be empty.
> 
> Additionally, this change replaces "=" with '='.  In the C programming
> language, "=" refers to two bytes: one for the equals character plus one
> for the terminating null byte.  In the C programming language, '='
> refers to a single byte.  In this particular instance, we’re talking
> about a single byte, so it’s better to use '='.  Using '=' also makes
> environ(7) more internally consistent.  Before this change, environ(7)
> used '\0' and "=".  This change makes it so that environ(7) uses '\0'
> and '='.
> 
> I was able to obtain obtain the information that I needed in order to
> create this change by writing a test program.  You can find the test
> program here [1].  Additionally, I got the information about the setenv(3)
> and unsetenv(3) functions from their man pages (specifically, the parts
> of their man pages that talk about EINVAL).
> 
> [1]: <https://codeberg.org/JasonYundt/environ-format-example-program>

Please include the C program in the commit message so that it can be
compiled and run easily, without having to understand Nix stuff.

> 
> Signed-off-by: Jason Yundt <jason@jasonyundt.email>
> ---
>  man/man7/environ.7 | 23 +++++++++++++++++------
>  1 file changed, 17 insertions(+), 6 deletions(-)
> 
> diff --git a/man/man7/environ.7 b/man/man7/environ.7
> index 31a69017cf75..bf5726e32429 100644
> --- a/man/man7/environ.7
> +++ b/man/man7/environ.7
> @@ -28,12 +28,23 @@ .SH DESCRIPTION
>  .I environ
>  have the form
>  .RI \[dq] name\f[B]=\f[]value \[dq].
> -The name is case-sensitive and may not contain
> -the character
> -.RB \[dq] = \[dq].
> -The value can be anything that can be represented as a string.
> -The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
> -since this is assumed to terminate the string.

I liked the old wording about the terminating null byte more.

> +The name is case-sensitive
> +and may contain any byte
> +other than null (\[aq]\[rs]0\[aq]) and 0x3D (the
> +.BR ascii (7)
> +.RB \[aq] = \[aq]
> +character).
> +The name must be at least one byte long,
> +or else programs will not be able to manipulate it using the
> +.BR setenv (3)
> +or
> +.BR unsetenv (3)
> +functions.
> +Immediately after the name, there should be a 0x3D byte.

What should readers interpret of 'should'?  Is it a recommendation or an
obligation?  This is unclear wording.

> +Immediately after the 0x3D byte is the value.

This seems redundant with the sentence that shows the format
"name=value".

> +The value may contain any byte except for null.

What is the null value?  You mean an empty string?  Or you mean embedded
null bytes in the string?  Please clarify.

> +The value may be zero bytes long.

That's commonly known as an empty string.

I think saying that the value can be anything that can be represented as
a string is fine (the old wording).

> +Immediately after the value, there must be a terminating null byte.

The fact that it's a string already implied this.


Have a lovely day!
Alex

>  .P
>  Environment variables may be placed in the shell's environment by the
>  .I export
> 
> Range-diff against v0:
> -:  ------------ > 1:  d5b0d9b86029 man/man7/environ.7: Fix underspecification of "name=value" strings
> -- 
> 2.54.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1] man/man7/environ.7: Fix underspecification of "name=value" strings

[Jason Yundt]

On Mon Jul 6, 2026 at 11:27 AM EDT, Alejandro Colomar wrote:
> Hi Jason,
>
> On 2026-07-06T10:26:20-0400, Jason Yundt wrote:
>> Before this change, environ(7) said this:
>> 
>> > By convention, the strings in environ have the form "name=value".  The
>> > name is case-sensitive and may not contain the character "=".  The
>> > value can be anything that can be represented as a string.  The name
>> > and the value may not contain an embedded null byte ('\0'), since this
>> > is assumed to terminate the string.
>> 
>> That description has a few problems:
>> 
>> 1. It talks about ‘the character "="’, but it doesn’t specify what
>>    character encoding would be used to represent that character.  Two
>>    different character encodings could represent that same “=” character
>>    using two different bytes (or even sequences of bytes).
>
> POSIX says that '=' is part of the portable character set.

I don’t really think that '=' being a part of the POSIX Portable
Character Set matters here.  For one thing, environ(7) doesn’t mention
the POSIX Portable Character Set at all.  Even if it did, the POSIX
Portable Character Set does not specify that the character encoding of
'=' is 0x3D so it wouldn’t really help us.

> Do we really need to care about the value of '='?

There needs to be a specification somewhere that says what the character
encoding would be.  You can’t represent any characters on a computer
without choosing a character encoding.

> Is this really possible?

Definitely.  Anyone can create whatever character encoding that they
want to.  There’s nothing that would force people to always encode the
“=” character as 0x3D in every character encoding that they create.
There are already character encodings in existence where “=” is not
encoded as a 0x3D byte.  For example, “=” is encoded as a 0x7E byte in
EBCDIC [1].

>
>> 2. It mentions that ‘The name is case-sensitive and may not contain the
>>    character "=".’  It doesn’t clearly say what what is allowed to be in
>>    a name.  It only says that those two things are explicitly
>>    disallowed.
>
> Anything else is allowed, obviously.

I don’t think that the current wording clearly specifies what is allowed
to be in a name.  It’s definitely not obvious to me.

>
>> This change fixes those two problems.  For the first problem, this
>> change makes it so that the description is all about bytes, not
>> characters.  Describing the format in terms of bytes allows us to
>> sidestep the question of character encoding entirely.  Additionally, it
>> is more accurate to describe strings in environ as being sequences of
>> bytes instead of sequences of characters.  Both the name and value of an
>> environment variable could be sequences of bytes that don’t contain any
>> characters at all.
>> 
>> For the second problem, this change clarifies that the name of an
>> environment variable can contain any byte except for 0x3D.  It also
>> clarifies that while it’s OK for environment variable values to be
>> empty, it’s not OK for environment variable names to be empty.
>> 
>> Additionally, this change replaces "=" with '='.  In the C programming
>> language, "=" refers to two bytes: one for the equals character plus one
>> for the terminating null byte.  In the C programming language, '='
>> refers to a single byte.  In this particular instance, we’re talking
>> about a single byte, so it’s better to use '='.  Using '=' also makes
>> environ(7) more internally consistent.  Before this change, environ(7)
>> used '\0' and "=".  This change makes it so that environ(7) uses '\0'
>> and '='.
>> 
>> I was able to obtain obtain the information that I needed in order to
>> create this change by writing a test program.  You can find the test
>> program here [1].  Additionally, I got the information about the setenv(3)
>> and unsetenv(3) functions from their man pages (specifically, the parts
>> of their man pages that talk about EINVAL).
>> 
>> [1]: <https://codeberg.org/JasonYundt/environ-format-example-program>
>
> Please include the C program in the commit message so that it can be
> compiled and run easily, without having to understand Nix stuff.

OK.  I created a shorter version of the test code that’s available at
that link.  I have embedded the new shorter version in the commit
message for the second version of this patch.

>
>> 
>> Signed-off-by: Jason Yundt <jason@jasonyundt.email>
>> ---
>>  man/man7/environ.7 | 23 +++++++++++++++++------
>>  1 file changed, 17 insertions(+), 6 deletions(-)
>> 
>> diff --git a/man/man7/environ.7 b/man/man7/environ.7
>> index 31a69017cf75..bf5726e32429 100644
>> --- a/man/man7/environ.7
>> +++ b/man/man7/environ.7
>> @@ -28,12 +28,23 @@ .SH DESCRIPTION
>>  .I environ
>>  have the form
>>  .RI \[dq] name\f[B]=\f[]value \[dq].
>> -The name is case-sensitive and may not contain
>> -the character
>> -.RB \[dq] = \[dq].
>> -The value can be anything that can be represented as a string.
>> -The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
>> -since this is assumed to terminate the string.
>
> I liked the old wording about the terminating null byte more.

OK.  In the second version of this patch, I brought back the old wording
about the terminating null byte.

>
>> +The name is case-sensitive
>> +and may contain any byte
>> +other than null (\[aq]\[rs]0\[aq]) and 0x3D (the
>> +.BR ascii (7)
>> +.RB \[aq] = \[aq]
>> +character).
>> +The name must be at least one byte long,
>> +or else programs will not be able to manipulate it using the
>> +.BR setenv (3)
>> +or
>> +.BR unsetenv (3)
>> +functions.
>> +Immediately after the name, there should be a 0x3D byte.
>
> What should readers interpret of 'should'?  Is it a recommendation or an
> obligation?  This is unclear wording.

OK.  In the second version of this patch, I replaced the word “should”
with the word “must”.

>
>> +Immediately after the 0x3D byte is the value.
>
> This seems redundant with the sentence that shows the format
> "name=value".

OK.  In the second version of this patch, I got rid of that sentence.

>
>> +The value may contain any byte except for null.
>
> What is the null value?  You mean an empty string?  Or you mean embedded
> null bytes in the string?  Please clarify.

When I wrote “The value may contain any byte except for null.”, I meant
“The value may contain any byte except for the null byte.”  That being
said, I have removed that sentence from the second version of this
patch.

>
>> +The value may be zero bytes long.
>
> That's commonly known as an empty string.
>
> I think saying that the value can be anything that can be represented as
> a string is fine (the old wording).

OK.  In the second version of this patch, I got rid of the sentence “The
value may be zero bytes long.”

>
>> +Immediately after the value, there must be a terminating null byte.
>
> The fact that it's a string already implied this.

OK.  In the second version of this patch, I got rid of the sentence
“Immediately after the value, there must be a terminating null byte.”

>
>
> Have a lovely day!
> Alex
>
>>  .P
>>  Environment variables may be placed in the shell's environment by the
>>  .I export
>> 
>> Range-diff against v0:
>> -:  ------------ > 1:  d5b0d9b86029 man/man7/environ.7: Fix underspecification of "name=value" strings
>> -- 
>> 2.54.0
>> 
>> 

[1]: <https://en.wikipedia.org/wiki/Ebcidic#Code_page_layout>

Re: [PATCH v1] man/man7/environ.7: Fix underspecification of "name=value" strings

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 8780 bytes --]

Hi Jason,

On 2026-07-07T06:54:49-0400, Jason Yundt wrote:
> On Mon Jul 6, 2026 at 11:27 AM EDT, Alejandro Colomar wrote:
> > Hi Jason,
> >
> > On 2026-07-06T10:26:20-0400, Jason Yundt wrote:
> >> Before this change, environ(7) said this:
> >> 
> >> > By convention, the strings in environ have the form "name=value".  The
> >> > name is case-sensitive and may not contain the character "=".  The
> >> > value can be anything that can be represented as a string.  The name
> >> > and the value may not contain an embedded null byte ('\0'), since this
> >> > is assumed to terminate the string.
> >> 
> >> That description has a few problems:
> >> 
> >> 1. It talks about ‘the character "="’, but it doesn’t specify what
> >>    character encoding would be used to represent that character.  Two
> >>    different character encodings could represent that same “=” character
> >>    using two different bytes (or even sequences of bytes).
> >
> > POSIX says that '=' is part of the portable character set.
> 
> I don’t really think that '=' being a part of the POSIX Portable
> Character Set matters here.  For one thing, environ(7) doesn’t mention
> the POSIX Portable Character Set at all.  Even if it did, the POSIX
> Portable Character Set does not specify that the character encoding of
> '=' is 0x3D so it wouldn’t really help us.

Oh, I thought POSIX required ASCII-compatible encoding, but it seems I
was likely wrong.

> > Do we really need to care about the value of '='?
> 
> There needs to be a specification somewhere that says what the character
> encoding would be.  You can’t represent any characters on a computer
> without choosing a character encoding.

After reading the POSIX specification of putenv(3), I have some doubts.
putenv(3) is specified to use '=', not 0x3D.  Thus, if working on a
system that uses a different value for '=', it seems that the
specification says that environ will still contain '=' in that encoding,
regardless of the value it has.  In fact, reading the musl and glibc
implementations, they use '=', not 0x3D (maybe those libc
implementations don't support encodings of '=' that don't use 0x3D;
I don't know).


Have a lovely day!
Alex

> > Is this really possible?
> 
> Definitely.  Anyone can create whatever character encoding that they
> want to.  There’s nothing that would force people to always encode the
> “=” character as 0x3D in every character encoding that they create.
> There are already character encodings in existence where “=” is not
> encoded as a 0x3D byte.  For example, “=” is encoded as a 0x7E byte in
> EBCDIC [1].
> 
> >
> >> 2. It mentions that ‘The name is case-sensitive and may not contain the
> >>    character "=".’  It doesn’t clearly say what what is allowed to be in
> >>    a name.  It only says that those two things are explicitly
> >>    disallowed.
> >
> > Anything else is allowed, obviously.
> 
> I don’t think that the current wording clearly specifies what is allowed
> to be in a name.  It’s definitely not obvious to me.
> 
> >
> >> This change fixes those two problems.  For the first problem, this
> >> change makes it so that the description is all about bytes, not
> >> characters.  Describing the format in terms of bytes allows us to
> >> sidestep the question of character encoding entirely.  Additionally, it
> >> is more accurate to describe strings in environ as being sequences of
> >> bytes instead of sequences of characters.  Both the name and value of an
> >> environment variable could be sequences of bytes that don’t contain any
> >> characters at all.
> >> 
> >> For the second problem, this change clarifies that the name of an
> >> environment variable can contain any byte except for 0x3D.  It also
> >> clarifies that while it’s OK for environment variable values to be
> >> empty, it’s not OK for environment variable names to be empty.
> >> 
> >> Additionally, this change replaces "=" with '='.  In the C programming
> >> language, "=" refers to two bytes: one for the equals character plus one
> >> for the terminating null byte.  In the C programming language, '='
> >> refers to a single byte.  In this particular instance, we’re talking
> >> about a single byte, so it’s better to use '='.  Using '=' also makes
> >> environ(7) more internally consistent.  Before this change, environ(7)
> >> used '\0' and "=".  This change makes it so that environ(7) uses '\0'
> >> and '='.
> >> 
> >> I was able to obtain obtain the information that I needed in order to
> >> create this change by writing a test program.  You can find the test
> >> program here [1].  Additionally, I got the information about the setenv(3)
> >> and unsetenv(3) functions from their man pages (specifically, the parts
> >> of their man pages that talk about EINVAL).
> >> 
> >> [1]: <https://codeberg.org/JasonYundt/environ-format-example-program>
> >
> > Please include the C program in the commit message so that it can be
> > compiled and run easily, without having to understand Nix stuff.
> 
> OK.  I created a shorter version of the test code that’s available at
> that link.  I have embedded the new shorter version in the commit
> message for the second version of this patch.
> 
> >
> >> 
> >> Signed-off-by: Jason Yundt <jason@jasonyundt.email>
> >> ---
> >>  man/man7/environ.7 | 23 +++++++++++++++++------
> >>  1 file changed, 17 insertions(+), 6 deletions(-)
> >> 
> >> diff --git a/man/man7/environ.7 b/man/man7/environ.7
> >> index 31a69017cf75..bf5726e32429 100644
> >> --- a/man/man7/environ.7
> >> +++ b/man/man7/environ.7
> >> @@ -28,12 +28,23 @@ .SH DESCRIPTION
> >>  .I environ
> >>  have the form
> >>  .RI \[dq] name\f[B]=\f[]value \[dq].
> >> -The name is case-sensitive and may not contain
> >> -the character
> >> -.RB \[dq] = \[dq].
> >> -The value can be anything that can be represented as a string.
> >> -The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
> >> -since this is assumed to terminate the string.
> >
> > I liked the old wording about the terminating null byte more.
> 
> OK.  In the second version of this patch, I brought back the old wording
> about the terminating null byte.
> 
> >
> >> +The name is case-sensitive
> >> +and may contain any byte
> >> +other than null (\[aq]\[rs]0\[aq]) and 0x3D (the
> >> +.BR ascii (7)
> >> +.RB \[aq] = \[aq]
> >> +character).
> >> +The name must be at least one byte long,
> >> +or else programs will not be able to manipulate it using the
> >> +.BR setenv (3)
> >> +or
> >> +.BR unsetenv (3)
> >> +functions.
> >> +Immediately after the name, there should be a 0x3D byte.
> >
> > What should readers interpret of 'should'?  Is it a recommendation or an
> > obligation?  This is unclear wording.
> 
> OK.  In the second version of this patch, I replaced the word “should”
> with the word “must”.
> 
> >
> >> +Immediately after the 0x3D byte is the value.
> >
> > This seems redundant with the sentence that shows the format
> > "name=value".
> 
> OK.  In the second version of this patch, I got rid of that sentence.
> 
> >
> >> +The value may contain any byte except for null.
> >
> > What is the null value?  You mean an empty string?  Or you mean embedded
> > null bytes in the string?  Please clarify.
> 
> When I wrote “The value may contain any byte except for null.”, I meant
> “The value may contain any byte except for the null byte.”  That being
> said, I have removed that sentence from the second version of this
> patch.
> 
> >
> >> +The value may be zero bytes long.
> >
> > That's commonly known as an empty string.
> >
> > I think saying that the value can be anything that can be represented as
> > a string is fine (the old wording).
> 
> OK.  In the second version of this patch, I got rid of the sentence “The
> value may be zero bytes long.”
> 
> >
> >> +Immediately after the value, there must be a terminating null byte.
> >
> > The fact that it's a string already implied this.
> 
> OK.  In the second version of this patch, I got rid of the sentence
> “Immediately after the value, there must be a terminating null byte.”
> 
> >
> >
> > Have a lovely day!
> > Alex
> >
> >>  .P
> >>  Environment variables may be placed in the shell's environment by the
> >>  .I export
> >> 
> >> Range-diff against v0:
> >> -:  ------------ > 1:  d5b0d9b86029 man/man7/environ.7: Fix underspecification of "name=value" strings
> >> -- 
> >> 2.54.0
> >> 
> >> 
> 
> [1]: <https://en.wikipedia.org/wiki/Ebcidic#Code_page_layout>

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2] man/man7/environ.7: Fix underspecification of "name=value" strings

[Jason Yundt]

Before this change, environ(7) said this:

> By convention, the strings in environ have the form "name=value".  The
> name is case-sensitive and may not contain the character "=".  The
> value can be anything that can be represented as a string.  The name
> and the value may not contain an embedded null byte ('\0'), since this
> is assumed to terminate the string.

That description has a few problems:

1. It talks about ‘the character "="’, but it doesn’t specify what
   character encoding would be used to represent that character.  Two
   different character encodings could represent that same “=” character
   using two different bytes (or even sequences of bytes).

2. It mentions that ‘The name is case-sensitive and may not contain the
   character "=".’  It doesn’t clearly say what what is allowed to be in
   a name.  It only says that those two things are explicitly
   disallowed.

This change fixes those two problems.  For the first problem, this
change makes it so that the description is all about bytes, not
characters.  Describing the format in terms of bytes allows us to
sidestep the question of character encoding entirely.  Additionally, it
is more accurate to describe strings in environ as being sequences of
bytes instead of sequences of characters.  Both the name and value of an
environment variable could be sequences of bytes that don’t contain any
characters at all.

For the second problem, this change clarifies that the name of an
environment variable can contain any byte except for 0x3D.  It also
clarifies that while it’s OK for environment variable values to be
empty, it’s not OK for environment variable names to be empty.

Additionally, this change replaces "=" with '='.  In the C programming
language, "=" refers to two bytes: one for the equals character plus one
for the terminating null byte.  In the C programming language, '='
refers to a single byte.  In this particular instance, we’re talking
about a single byte, so it’s better to use '='.  Using '=' also makes
environ(7) more internally consistent.  Before this change, environ(7)
used '\0' and "=".  This change makes it so that environ(7) uses '\0'
and '='.

I was able to obtain obtain the information that I needed in order to
create this change by writing two test programs:

show-env-var-bytes.c:

	#include <stdio.h>
	#include <stdlib.h>

	void print_string_bytes(char *s) {
		printf("\"");
		for (size_t i = 0; s[i] != '\0'; i++) {
			printf("\\x%02hhX", s[i]);
		}
		printf("\"\n");
	}

	int main(int argc, char *argv[]) {
		if (argc != 2) {
			fprintf(stderr, "USAGE: %s <NAME>\n", argv[0]);
			return EXIT_FAILURE;
		}
		printf("Name: ");
		print_string_bytes(argv[1]);
		char *getenv_result = getenv(argv[1]);
		if (getenv_result == NULL) {
			fprintf(stderr, "Environment variable not found.\n");
			return EXIT_FAILURE;
		}
		printf("Value: ");
		print_string_bytes(getenv_result);
	}

set-env-var-then-show-bytes.c:

	#include <stdbool.h>
	#include <stdio.h>
	#include <stdlib.h>
	#include <string.h>
	#include <unistd.h>

	char *every_nonnull_byte(bool exclude_3d_byte);
	char *environ_item(char *name, char *value);

	char *every_nonnull_byte(bool exclude_3d_byte) {
		char           *ret;
		size_t         i = 0, size = 256;
		unsigned char  byte = '\1';

		if (exclude_3d_byte)
			size -= 1;
		ret = malloc(size);
		for (size_t i = 0; i < (size - 1); i++) {
			if (exclude_3d_byte && byte == '\x3D') {
				byte++;
			}
			ret[i] = byte;
			byte++;
		}
		ret[size - 1] = '\0';
		return ret;
	}

	char *environ_item(char *name, char *value) {
		char  *ret = malloc(strlen(name) + 1 + strlen(value) + 1);

		sprintf(ret, "%s\x3D%s", name, value);
		return ret;
	}

	int main(int argc, char *argv[]) {
		char *name = every_nonnull_byte(true);
		char *value = every_nonnull_byte(false);
		char *env[] = { environ_item(name, value), NULL };

		if (argc != 2) {
			fprintf(stderr, "USAGE: %s <PATH>\n", argv[0]);
			return EXIT_FAILURE;
		}

		execle(argv[1], argv[1], name, NULL, env);
		perror("execle() failed");
		free(name);
		free(value);
		free(env[0]);
		return EXIT_FAILURE;
	}

Once those two programs are compiled you can run them by running this
command:

    ./set-env-var-then-show-bytes ./show-env-var-bytes

Additionally, I got the information about the setenv(3) and unsetenv(3)
functions from their man pages (specifically, the parts of their man pages
that talk about EINVAL).

Signed-off-by: Jason Yundt <jason@jasonyundt.email>
---
 man/man7/environ.7 | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/man/man7/environ.7 b/man/man7/environ.7
index 31a69017cf75..89d48991e8b7 100644
--- a/man/man7/environ.7
+++ b/man/man7/environ.7
@@ -28,9 +28,19 @@ .SH DESCRIPTION
 .I environ
 have the form
 .RI \[dq] name\f[B]=\f[]value \[dq].
-The name is case-sensitive and may not contain
-the character
-.RB \[dq] = \[dq].
+The name is case-sensitive
+and may contain any nonnull byte
+other than 0x3D (the
+.BR ascii (7)
+.RB \[aq] = \[aq]
+character).
+The name must be at least one byte long,
+or else programs will not be able to manipulate it using the
+.BR setenv (3)
+or
+.BR unsetenv (3)
+functions.
+Immediately after the name, there must be a 0x3D byte.
 The value can be anything that can be represented as a string.
 The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
 since this is assumed to terminate the string.

Range-diff against v1:
1:  d5b0d9b86029 ! 1:  74bea4adebbd man/man7/environ.7: Fix underspecification of "name=value" strings
    @@ Commit message
         and '='.
     
         I was able to obtain obtain the information that I needed in order to
    -    create this change by writing a test program.  You can find the test
    -    program here [1].  Additionally, I got the information about the setenv(3)
    -    and unsetenv(3) functions from their man pages (specifically, the parts
    -    of their man pages that talk about EINVAL).
    +    create this change by writing two test programs:
     
    -    [1]: <https://codeberg.org/JasonYundt/environ-format-example-program>
    +    show-env-var-bytes.c:
    +
    +            #include <stdio.h>
    +            #include <stdlib.h>
    +
    +            void print_string_bytes(char *s) {
    +                    printf("\"");
    +                    for (size_t i = 0; s[i] != '\0'; i++) {
    +                            printf("\\x%02hhX", s[i]);
    +                    }
    +                    printf("\"\n");
    +            }
    +
    +            int main(int argc, char *argv[]) {
    +                    if (argc != 2) {
    +                            fprintf(stderr, "USAGE: %s <NAME>\n", argv[0]);
    +                            return EXIT_FAILURE;
    +                    }
    +                    printf("Name: ");
    +                    print_string_bytes(argv[1]);
    +                    char *getenv_result = getenv(argv[1]);
    +                    if (getenv_result == NULL) {
    +                            fprintf(stderr, "Environment variable not found.\n");
    +                            return EXIT_FAILURE;
    +                    }
    +                    printf("Value: ");
    +                    print_string_bytes(getenv_result);
    +            }
    +
    +    set-env-var-then-show-bytes.c:
    +
    +            #include <stdbool.h>
    +            #include <stdio.h>
    +            #include <stdlib.h>
    +            #include <string.h>
    +            #include <unistd.h>
    +
    +            char *every_nonnull_byte(bool exclude_3d_byte);
    +            char *environ_item(char *name, char *value);
    +
    +            char *every_nonnull_byte(bool exclude_3d_byte) {
    +                    char           *ret;
    +                    size_t         i = 0, size = 256;
    +                    unsigned char  byte = '\1';
    +
    +                    if (exclude_3d_byte)
    +                            size -= 1;
    +                    ret = malloc(size);
    +                    for (size_t i = 0; i < (size - 1); i++) {
    +                            if (exclude_3d_byte && byte == '\x3D') {
    +                                    byte++;
    +                            }
    +                            ret[i] = byte;
    +                            byte++;
    +                    }
    +                    ret[size - 1] = '\0';
    +                    return ret;
    +            }
    +
    +            char *environ_item(char *name, char *value) {
    +                    char  *ret = malloc(strlen(name) + 1 + strlen(value) + 1);
    +
    +                    sprintf(ret, "%s\x3D%s", name, value);
    +                    return ret;
    +            }
    +
    +            int main(int argc, char *argv[]) {
    +                    char *name = every_nonnull_byte(true);
    +                    char *value = every_nonnull_byte(false);
    +                    char *env[] = { environ_item(name, value), NULL };
    +
    +                    if (argc != 2) {
    +                            fprintf(stderr, "USAGE: %s <PATH>\n", argv[0]);
    +                            return EXIT_FAILURE;
    +                    }
    +
    +                    execle(argv[1], argv[1], name, NULL, env);
    +                    perror("execle() failed");
    +                    free(name);
    +                    free(value);
    +                    free(env[0]);
    +                    return EXIT_FAILURE;
    +            }
    +
    +    Once those two programs are compiled you can run them by running this
    +    command:
    +
    +        ./set-env-var-then-show-bytes ./show-env-var-bytes
    +
    +    Additionally, I got the information about the setenv(3) and unsetenv(3)
    +    functions from their man pages (specifically, the parts of their man pages
    +    that talk about EINVAL).
     
         Signed-off-by: Jason Yundt <jason@jasonyundt.email>
     
    @@ man/man7/environ.7: .SH DESCRIPTION
     -The name is case-sensitive and may not contain
     -the character
     -.RB \[dq] = \[dq].
    --The value can be anything that can be represented as a string.
    --The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
    --since this is assumed to terminate the string.
     +The name is case-sensitive
    -+and may contain any byte
    -+other than null (\[aq]\[rs]0\[aq]) and 0x3D (the
    ++and may contain any nonnull byte
    ++other than 0x3D (the
     +.BR ascii (7)
     +.RB \[aq] = \[aq]
     +character).
    @@ man/man7/environ.7: .SH DESCRIPTION
     +or
     +.BR unsetenv (3)
     +functions.
    -+Immediately after the name, there should be a 0x3D byte.
    -+Immediately after the 0x3D byte is the value.
    -+The value may contain any byte except for null.
    -+The value may be zero bytes long.
    -+Immediately after the value, there must be a terminating null byte.
    - .P
    - Environment variables may be placed in the shell's environment by the
    - .I export
    ++Immediately after the name, there must be a 0x3D byte.
    + The value can be anything that can be represented as a string.
    + The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
    + since this is assumed to terminate the string.
-- 
2.54.0

Re: [PATCH v2] man/man7/environ.7: Fix underspecification of "name=value" strings

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 13090 bytes --]

Hi Jason,

On 2026-07-07T06:53:26-0400, Jason Yundt wrote:
> Before this change, environ(7) said this:
> 
> > By convention, the strings in environ have the form "name=value".  The
> > name is case-sensitive and may not contain the character "=".  The
> > value can be anything that can be represented as a string.  The name
> > and the value may not contain an embedded null byte ('\0'), since this
> > is assumed to terminate the string.
> 
> That description has a few problems:
> 
> 1. It talks about ‘the character "="’, but it doesn’t specify what
>    character encoding would be used to represent that character.  Two
>    different character encodings could represent that same “=” character
>    using two different bytes (or even sequences of bytes).
> 
> 2. It mentions that ‘The name is case-sensitive and may not contain the
>    character "=".’  It doesn’t clearly say what what is allowed to be in
>    a name.  It only says that those two things are explicitly
>    disallowed.
> 
> This change fixes those two problems.  For the first problem, this
> change makes it so that the description is all about bytes, not
> characters.  Describing the format in terms of bytes allows us to
> sidestep the question of character encoding entirely.  Additionally, it
> is more accurate to describe strings in environ as being sequences of
> bytes instead of sequences of characters.  Both the name and value of an
> environment variable could be sequences of bytes that don’t contain any
> characters at all.
> 
> For the second problem, this change clarifies that the name of an
> environment variable can contain any byte except for 0x3D.  It also
> clarifies that while it’s OK for environment variable values to be
> empty, it’s not OK for environment variable names to be empty.
> 
> Additionally, this change replaces "=" with '='.  In the C programming
> language, "=" refers to two bytes: one for the equals character plus one
> for the terminating null byte.  In the C programming language, '='
> refers to a single byte.  In this particular instance, we’re talking
> about a single byte, so it’s better to use '='.  Using '=' also makes
> environ(7) more internally consistent.  Before this change, environ(7)
> used '\0' and "=".  This change makes it so that environ(7) uses '\0'
> and '='.

I like the change from this paragraph.  If you send a separate patch
with only this change, I'll apply it.

> 
> I was able to obtain obtain the information that I needed in order to
> create this change by writing two test programs:
> 
> show-env-var-bytes.c:
> 
> 	#include <stdio.h>
> 	#include <stdlib.h>
> 
> 	void print_string_bytes(char *s) {
> 		printf("\"");
> 		for (size_t i = 0; s[i] != '\0'; i++) {
> 			printf("\\x%02hhX", s[i]);
> 		}
> 		printf("\"\n");
> 	}
> 
> 	int main(int argc, char *argv[]) {
> 		if (argc != 2) {
> 			fprintf(stderr, "USAGE: %s <NAME>\n", argv[0]);
> 			return EXIT_FAILURE;
> 		}
> 		printf("Name: ");
> 		print_string_bytes(argv[1]);
> 		char *getenv_result = getenv(argv[1]);
> 		if (getenv_result == NULL) {
> 			fprintf(stderr, "Environment variable not found.\n");
> 			return EXIT_FAILURE;
> 		}
> 		printf("Value: ");
> 		print_string_bytes(getenv_result);
> 	}
> 
> set-env-var-then-show-bytes.c:
> 
> 	#include <stdbool.h>
> 	#include <stdio.h>
> 	#include <stdlib.h>
> 	#include <string.h>
> 	#include <unistd.h>
> 
> 	char *every_nonnull_byte(bool exclude_3d_byte);
> 	char *environ_item(char *name, char *value);
> 
> 	char *every_nonnull_byte(bool exclude_3d_byte) {
> 		char           *ret;
> 		size_t         i = 0, size = 256;

Unused variable 'i'.

> 		unsigned char  byte = '\1';
> 
> 		if (exclude_3d_byte)
> 			size -= 1;
> 		ret = malloc(size);
> 		for (size_t i = 0; i < (size - 1); i++) {
> 			if (exclude_3d_byte && byte == '\x3D') {
> 				byte++;
> 			}
> 			ret[i] = byte;
> 			byte++;
> 		}
> 		ret[size - 1] = '\0';
> 		return ret;
> 	}
> 
> 	char *environ_item(char *name, char *value) {
> 		char  *ret = malloc(strlen(name) + 1 + strlen(value) + 1);
> 
> 		sprintf(ret, "%s\x3D%s", name, value);
> 		return ret;
> 	}
> 
> 	int main(int argc, char *argv[]) {
> 		char *name = every_nonnull_byte(true);
> 		char *value = every_nonnull_byte(false);
> 		char *env[] = { environ_item(name, value), NULL };
> 
> 		if (argc != 2) {
> 			fprintf(stderr, "USAGE: %s <PATH>\n", argv[0]);
> 			return EXIT_FAILURE;
> 		}
> 
> 		execle(argv[1], argv[1], name, NULL, env);
> 		perror("execle() failed");
> 		free(name);
> 		free(value);
> 		free(env[0]);
> 		return EXIT_FAILURE;
> 	}
> 
> Once those two programs are compiled you can run them by running this
> command:
> 
>     ./set-env-var-then-show-bytes ./show-env-var-bytes

I think these programs don't prove what happens on a system with an
encoding incompatible with ASCII.  I think if you compile glibc on an
EBDIC-based system (if that is possible at all, which I ignore), you'll
get the behavior based on '=' and not 0x3D.  I think this is required by
POSIX.  0x3D is not special.

Of course, if your system is a mix of ASCII and EBDIC, you have
a problem: glibc might have been compiled as ASCII (and thus use 0x3D)
and your program might be using something else.


Cheers,
Alex

> Additionally, I got the information about the setenv(3) and unsetenv(3)
> functions from their man pages (specifically, the parts of their man pages
> that talk about EINVAL).
> 
> Signed-off-by: Jason Yundt <jason@jasonyundt.email>
> ---
>  man/man7/environ.7 | 16 +++++++++++++---
>  1 file changed, 13 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man7/environ.7 b/man/man7/environ.7
> index 31a69017cf75..89d48991e8b7 100644
> --- a/man/man7/environ.7
> +++ b/man/man7/environ.7
> @@ -28,9 +28,19 @@ .SH DESCRIPTION
>  .I environ
>  have the form
>  .RI \[dq] name\f[B]=\f[]value \[dq].
> -The name is case-sensitive and may not contain
> -the character
> -.RB \[dq] = \[dq].
> +The name is case-sensitive
> +and may contain any nonnull byte
> +other than 0x3D (the
> +.BR ascii (7)
> +.RB \[aq] = \[aq]
> +character).
> +The name must be at least one byte long,
> +or else programs will not be able to manipulate it using the
> +.BR setenv (3)
> +or
> +.BR unsetenv (3)
> +functions.
> +Immediately after the name, there must be a 0x3D byte.
>  The value can be anything that can be represented as a string.
>  The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
>  since this is assumed to terminate the string.
> 
> Range-diff against v1:
> 1:  d5b0d9b86029 ! 1:  74bea4adebbd man/man7/environ.7: Fix underspecification of "name=value" strings
>     @@ Commit message
>          and '='.
>      
>          I was able to obtain obtain the information that I needed in order to
>     -    create this change by writing a test program.  You can find the test
>     -    program here [1].  Additionally, I got the information about the setenv(3)
>     -    and unsetenv(3) functions from their man pages (specifically, the parts
>     -    of their man pages that talk about EINVAL).
>     +    create this change by writing two test programs:
>      
>     -    [1]: <https://codeberg.org/JasonYundt/environ-format-example-program>
>     +    show-env-var-bytes.c:
>     +
>     +            #include <stdio.h>
>     +            #include <stdlib.h>
>     +
>     +            void print_string_bytes(char *s) {
>     +                    printf("\"");
>     +                    for (size_t i = 0; s[i] != '\0'; i++) {
>     +                            printf("\\x%02hhX", s[i]);
>     +                    }
>     +                    printf("\"\n");
>     +            }
>     +
>     +            int main(int argc, char *argv[]) {
>     +                    if (argc != 2) {
>     +                            fprintf(stderr, "USAGE: %s <NAME>\n", argv[0]);
>     +                            return EXIT_FAILURE;
>     +                    }
>     +                    printf("Name: ");
>     +                    print_string_bytes(argv[1]);
>     +                    char *getenv_result = getenv(argv[1]);
>     +                    if (getenv_result == NULL) {
>     +                            fprintf(stderr, "Environment variable not found.\n");
>     +                            return EXIT_FAILURE;
>     +                    }
>     +                    printf("Value: ");
>     +                    print_string_bytes(getenv_result);
>     +            }
>     +
>     +    set-env-var-then-show-bytes.c:
>     +
>     +            #include <stdbool.h>
>     +            #include <stdio.h>
>     +            #include <stdlib.h>
>     +            #include <string.h>
>     +            #include <unistd.h>
>     +
>     +            char *every_nonnull_byte(bool exclude_3d_byte);
>     +            char *environ_item(char *name, char *value);
>     +
>     +            char *every_nonnull_byte(bool exclude_3d_byte) {
>     +                    char           *ret;
>     +                    size_t         i = 0, size = 256;
>     +                    unsigned char  byte = '\1';
>     +
>     +                    if (exclude_3d_byte)
>     +                            size -= 1;
>     +                    ret = malloc(size);
>     +                    for (size_t i = 0; i < (size - 1); i++) {
>     +                            if (exclude_3d_byte && byte == '\x3D') {
>     +                                    byte++;
>     +                            }
>     +                            ret[i] = byte;
>     +                            byte++;
>     +                    }
>     +                    ret[size - 1] = '\0';
>     +                    return ret;
>     +            }
>     +
>     +            char *environ_item(char *name, char *value) {
>     +                    char  *ret = malloc(strlen(name) + 1 + strlen(value) + 1);
>     +
>     +                    sprintf(ret, "%s\x3D%s", name, value);
>     +                    return ret;
>     +            }
>     +
>     +            int main(int argc, char *argv[]) {
>     +                    char *name = every_nonnull_byte(true);
>     +                    char *value = every_nonnull_byte(false);
>     +                    char *env[] = { environ_item(name, value), NULL };
>     +
>     +                    if (argc != 2) {
>     +                            fprintf(stderr, "USAGE: %s <PATH>\n", argv[0]);
>     +                            return EXIT_FAILURE;
>     +                    }
>     +
>     +                    execle(argv[1], argv[1], name, NULL, env);
>     +                    perror("execle() failed");
>     +                    free(name);
>     +                    free(value);
>     +                    free(env[0]);
>     +                    return EXIT_FAILURE;
>     +            }
>     +
>     +    Once those two programs are compiled you can run them by running this
>     +    command:
>     +
>     +        ./set-env-var-then-show-bytes ./show-env-var-bytes
>     +
>     +    Additionally, I got the information about the setenv(3) and unsetenv(3)
>     +    functions from their man pages (specifically, the parts of their man pages
>     +    that talk about EINVAL).
>      
>          Signed-off-by: Jason Yundt <jason@jasonyundt.email>
>      
>     @@ man/man7/environ.7: .SH DESCRIPTION
>      -The name is case-sensitive and may not contain
>      -the character
>      -.RB \[dq] = \[dq].
>     --The value can be anything that can be represented as a string.
>     --The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
>     --since this is assumed to terminate the string.
>      +The name is case-sensitive
>     -+and may contain any byte
>     -+other than null (\[aq]\[rs]0\[aq]) and 0x3D (the
>     ++and may contain any nonnull byte
>     ++other than 0x3D (the
>      +.BR ascii (7)
>      +.RB \[aq] = \[aq]
>      +character).
>     @@ man/man7/environ.7: .SH DESCRIPTION
>      +or
>      +.BR unsetenv (3)
>      +functions.
>     -+Immediately after the name, there should be a 0x3D byte.
>     -+Immediately after the 0x3D byte is the value.
>     -+The value may contain any byte except for null.
>     -+The value may be zero bytes long.
>     -+Immediately after the value, there must be a terminating null byte.
>     - .P
>     - Environment variables may be placed in the shell's environment by the
>     - .I export
>     ++Immediately after the name, there must be a 0x3D byte.
>     + The value can be anything that can be represented as a string.
>     + The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
>     + since this is assumed to terminate the string.
> -- 
> 2.54.0
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]