ExpandEnvironmentStrings function (Windows)

ExpandEnvironmentStrings function

ExpandEnvironmentStrings function

Applies to: desktop apps only

Expands environment-variable strings and replaces them with the values defined for the current user.

To specify the environment block for a particular user or the system, use the ExpandEnvironmentStringsForUser function.

Syntax

DWORD WINAPI ExpandEnvironmentStrings(
  __in       LPCTSTR lpSrc,
  __out_opt  LPTSTR lpDst,
  __in       DWORD nSize
);

Parameters

lpSrc [in]

A buffer that contains one or more environment-variable strings in the form: %variableName%. For each such reference, the %variableName% portion is replaced with the current value of that environment variable.

Case is ignored when looking up the environment-variable name. If the name is not found, the %variableName% portion is left unexpanded.

Note that this function does not support all the features that Cmd.exe supports. For example, it does not support %variableName:str1=str2% or %variableName:~offset,length%.

lpDst [out, optional]

A pointer to a buffer that receives the result of expanding the environment variable strings in the lpSrc buffer. Note that this buffer cannot be the same as the lpSrc buffer.

nSize [in]

The maximum number of characters that can be stored in the buffer pointed to by the lpDst parameter. When using ANSI strings, the buffer size should be the string length, plus terminating null character, plus one. When using Unicode strings, the buffer size should be the string length plus the terminating null character.

Return value

If the function succeeds, the return value is the number of TCHARs stored in the destination buffer, including the terminating null character. If the destination buffer is too small to hold the expanded string, the return value is the required buffer size, in characters.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The size of the lpSrc and lpDst buffers is limited to 32K.

To replace folder names in a fully qualified path with their associated environment-variable strings, use the PathUnExpandEnvStrings function.

To retrieve the list of environment variables for a process, use the GetEnvironmentStrings function.

Examples

For an example, see Getting System Information.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Winbase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll
Unicode and ANSI names	ExpandEnvironmentStringsW (Unicode) and ExpandEnvironmentStringsA (ANSI)

Hi, herewith a minimal example reproducing the problem with CreateProcess:

#include <windows.h>
#include <iostream>

int main()
{
PROCESS_INFORMATION pi = {0};
STARTUPINFO si = {0};
si.cb = sizeof(si);
char command[] = "cmd /C \"%ProgramFiles%\\Internet Explorer\\iexplore.exe\"";

if (!::CreateProcess(NULL, command, NULL, NULL, TRUE, 0, 0, NULL, &;;si, &;;pi))
{
std::cerr << "CreateProcess error " << ::GetLastError() << "\n";
return -1;
}
::WaitForSingleObject( pi.hProcess, INFINITE );
DWORD exitCode;
::GetExitCodeProcess(pi.hProcess, &;;exitCode);
std::cout << "Process finished with code " << exitCode << "\n";
return 0;
}

This works fine and IE starts. However if I replace 'C:\\Program Files' with '%ProgramFiles%, I receive the following error in the console:

'C:\Program' is not recognized as an internal or external command, operable program or batch file.
Process finished with code 1

%ProgramFiles% env. variable is set correctly. It seems that whуn env variable is expanded, the quotes surrounding the command are just gone. Can anyone please explain me what happens?

BTW the remedy is:
1. replace quites with double quotes
2. or call ExpandEnvironmentStrings to prepare command for CreateProcess

But these seem workarounds to me. Whom shell I blame? Myself or CreateProcess?

Tags

: Add a tag

Flag as ContentBug

C# syntax

dmex | Edit | Show History

[DllImport("kernel32.dll", CharSet=CharSet.Auto, SetLastError=true)]
public static extern int ExpandEnvironmentStrings(string lpSrc, StringBuilder lpDst, int nSize);

Tags

: c# (x) syntax (x) Add a tag

Flag as ContentBug

vb.net syntax

dmex | Edit | Show History

<DllImport("kernel32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Public Shared Function ExpandEnvironmentStrings(ByVal lpSrc As String, ByVal lpDst As StringBuilder, ByVal nSize As Integer) As Integer
End Function

Tags

: syntax (x) vb.net (x) Add a tag

Flag as ContentBug

ExpandEnvironmentStringsA returns the wrong length

Gideon7 | Edit | Show History

Note: The ANSI version of ExpandEnvironmentStrings (ExpandEnvironmentStringsA) on Windows NT incorrectly returns the length of the Unicode string (in bytes), not the character length of the ANSI string. In later versions of Windows it returns the byte length/2 of the Unicode string. The latter is incorrect if Windows is installed with an East-Asian default ANSI code page.

In general ExpandEnvironmentStringsA should be considered broken and its use avoided. If you need the returned string(s) in the context of an ANSI code page call the Unicode version (ExpandEnvironmentStringsW) and translate the returned wide-string to an 8-bit string using a conversion function such as WideCharToMultiByte.

Tags

: contentbug (x) Add a tag

The 'CD' and 'ERRORLEVEL' values are not expanded

Peter Smith in Redmond | Edit | Show History

Note that this function really doesn't work the same way as the CMD shell at all -- like the documementation notes, it doesn't do the fancy expansion. But it also doesn't expand the CD or ERRORLEVEL "variables" either.

See Raymond Chen's Old New Thing blog entry http://blogs.msdn.com/oldnewthing/archive/2008/09/26/8965755.aspx

for even more details.

Tags

: Add a tag

Flag as ContentBug

Syntax

Parameters

Return value

Remarks

Examples

Requirements

See also