CommandLineToArgvW function
Applies to: desktop apps only
Parses a Unicode command line string and returns an array of pointers to the command line arguments, along with a count of such arguments, in a way that is similar to the standard C run-time argv and argc values.
Syntax
LPWSTR* CommandLineToArgvW( __in LPCWSTR lpCmdLine, __out int *pNumArgs );
Parameters
- lpCmdLine [in]
-
Type: LPCWSTR
Pointer to a null-terminated Unicode string that contains the full command line. If this parameter is an empty string the function returns the path to the current executable file.
- pNumArgs [out]
-
Type: int*
Pointer to an int that receives the number of array elements returned, similar to argc.
Return value
Type: LPWSTR*
A pointer to an array of LPWSTR values, similar to argv.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The address returned by CommandLineToArgvW is the address of the first element in an array of LPWSTR values; the number of pointers in this array is indicated by pNumArgs. Each pointer to a null-terminated Unicode string represents an individual argument found on the command line.
CommandLineToArgvW allocates a block of contiguous memory for pointers to the argument strings, and for the argument strings themselves; the calling application must free the memory used by the argument list when it is no longer needed. To free the memory, use a single call to the LocalFree function.
For more information about the argv and argc argument convention, see Argument Definitions and Parsing C++ Command-Line Arguments.
The GetCommandLineW function can be used to get a command line string that is suitable for use as the lpCmdLine parameter.
This function accepts command lines that contain a program name; the program name can be enclosed in quotation marks or not.
CommandLineToArgvW has a special interpretation of backslash characters when they are followed by a quotation mark character ("), as follows:
- 2n backslashes followed by a quotation mark produce n backslashes followed by a quotation mark.
- (2n) + 1 backslashes followed by a quotation mark again produce n backslashes followed by a quotation mark.
- n backslashes not followed by a quotation mark simply produce n backslashes.
Examples
The following example demonstrates how to parse a Unicode command-line string. The code frees the memory for the argument list at exit.
#include <windows.h>
#include <stdio.h>
#include <shellapi.h>
int __cdecl main()
{
LPWSTR *szArglist;
int nArgs;
int i;
szArglist = CommandLineToArgvW(GetCommandLineW(), &nArgs);
if( NULL == szArglist )
{
wprintf(L"CommandLineToArgvW failed\n");
return 0;
}
else for( i=0; i<nArgs; i++) printf("%d: %ws\n", i, szArglist[i]);
// Free memory allocated for CommandLineToArgvW arguments.
LocalFree(szArglist);
return(1);
}
Requirements
|
Minimum supported client | Windows 2000 Professional, Windows XP |
|---|---|
|
Minimum supported server | Windows 2000 Server, Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | CommandLineToArgvW (Unicode) |
Send comments about this topic to Microsoft
Build date: 3/7/2012
The documentation lacks a very important detail:
2n+1 backslashes followed by a quote result in the quote being counted as an "inner" quote, i.e. it is part of the argument token.
2n backslashes followed by a quote result in the quote being counted as an "outer" quote, i.e. it terminates the current argument token and CommandLineToArgv continues to parse the next token after skipping any subsequent white-spaces.
- 4/15/2012
- Nase0815
The simplest way to test for this case seems to be to use GetModuleFileNameW() with 0 as the first parameter to get the exe path and then compare it to the command line.
- 9/29/2008
- Goatspawn
- 8/10/2008
- Myria
- 6/25/2008
- Roland Illig
- 6/25/2008
- Roland Illig
