Skip to content

Files

Latest commit

Mar 8, 2023
8945954 · Mar 8, 2023

History

History
143 lines (103 loc) · 5.83 KB

nf-shellapi-commandlinetoargvw.md

File metadata and controls

143 lines (103 loc) · 5.83 KB
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NF:shellapi.CommandLineToArgvW
CommandLineToArgvW function (shellapi.h)
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.
CommandLineToArgvW
CommandLineToArgvW function [Windows Shell]
_shell_CommandLineToArgvW
shell.CommandLineToArgvW
shellapi/CommandLineToArgvW
shell\CommandLineToArgvW.htm
shell
9889a016-b7a5-402b-8305-6f7c199d41b3
12/05/2018
CommandLineToArgvW, CommandLineToArgvW function [Windows Shell], _shell_CommandLineToArgvW, shell.CommandLineToArgvW, shellapi/CommandLineToArgvW
shellapi.h
Windows
Windows 2000 Professional, Windows XP [desktop apps only]
Windows 2000 Server, Windows Server 2003 [desktop apps only]
CommandLineToArgvW (Unicode)
Shell32.lib
Shell32.dll (version 6.0 or later)
Windows
19H1
CommandLineToArgvW
shellapi/CommandLineToArgvW
c++
APIRef
kbSyntax
DllExport
Shell32.dll
API-MS-Win-DownLevel-shell32-l1-1-0.dll
ShCore.dll
API-MS-Win-ShCore-Obsolete-l1-1-0.dll
CommandLineToArgvW
CommandLineToArgvW

CommandLineToArgvW function

-description

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.

-parameters

-param 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.

-param pNumArgs [out]

Type: int*

Pointer to an int that receives the number of array elements returned, similar to argc.

-returns

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 ("). This interpretation assumes that any preceding argument is a valid file system path, or else it may behave unpredictably.

This special interpretation controls the "in quotes" mode tracked by the parser. When this mode is off, whitespace terminates the current argument. When on, whitespace is added to the argument like all other characters.

  • 2n backslashes followed by a quotation mark produce n backslashes followed by begin/end quote. This does not become part of the parsed argument, but toggles the "in quotes" mode.
  • (2n) + 1 backslashes followed by a quotation mark again produce n backslashes followed by a quotation mark literal ("). This does not toggle the "in quotes" mode.
  • n backslashes not followed by a quotation mark simply produce n backslashes.
Important  

CommandLineToArgvW treats whitespace outside of quotation marks as argument delimiters. However, if lpCmdLine starts with any amount of whitespace, CommandLineToArgvW will consider the first argument to be an empty string. Excess whitespace at the end of lpCmdLine is ignored.

 

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);
}