StartX v1.15

Welcome to StartX, A very simple utility to allow you to call the CreateProcess API from the command line.

History

v1.15 (27 May 2022)

• Updated copyright details.
• Updated the code to use C++ uniform initialization for all variable declarations.

v1.14 (5 April 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.13 (29 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.

v1.12 (16 November 2019)

• Updated initialization of various structs to use C++ 11 list initialization

v1.11 (1 June 2019)

• Updated copyright details.
• Updated the code to clean compile on VC 2019

v1.10 (17 October 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.

v1.09 (5 December 2017)

• Updated copyright details
• Replaced NULL throughout the codebase with nullptr.
• Replaced BOOL throughout the codebase with bool.
• Replaced CString::operator LPC*STR() calls throughout the codebase with CString::GetString calls
• GetNumaNodeProcessorMaskEx is now called directly rather than via GetProcAddress. This means that the minimum supported version of Windows is Windows 7.
• CMyCommandLineInfo::GetIdlPath has been reworked and renamed to work with KNOWNFOLDERID values instead of CSIDL values.

v1.08 (5 June 2016)

• Updated documentation for the /TITLEISAPPID, /TITLEISLINKNAME & /UNTRUSTEDSOURCE parameters. Thanks to Marc Kupper for reporting this issue.
• Updated documentation to remove double reference to /NOUI. Thanks to Marc Kupper for reporting this issue.
• Removed documentation reference to /I command line parameter. Thanks to Marc Kupper for reporting this issue.
• Updated documentation to refer to /MIN, /MAX & /HIDE as mutually exclusive. Thanks to Marc Kupper for reporting this issue.
• Updated documentation to refer to /LP & /LNCO as mutually exclusive. Thanks to Marc Kupper for reporting this issue.
• Updated documentation for parameters to be in the same order in the parameters list and the description table. Thanks to Marc Kupper for reporting this issue.
• Added code to support the /REALTIME parameter. Thanks to Marc Kupper for reporting this issue.

v1.07 (22 May 2016)

• Updated copyright details.
• Update the project settings to more modern defaults
• Updated the code to clean compile on VC 2010 - VC 2015
• CMyCommandLineInfo::GetIdlPath now calls ShGetFolderPath directly instead of through GetProcAddress.
• Code now calls CreateProcessWithLogonW directly instead of through GetProcAddress
• Code now calls CredUIPromptForCredentials directly instead of through GetProcAddress
• Reviewed the documentation's description of all the CSIDL values and made sure it was up to date.
• StartX now supports a /HIDE command line option.
• StartX now supports a /NODE command line option similiar to the internal Start Windows command
• StartX now supports a /PREVENTPINNING command line option.
• StartX now supports a /TITLEISAPPID command line option.
• StartX now supports a /TITLEISLINKNAME command line option.
• StartX now supports a /UNTRUSTEDSOURCE command line option.
• The download now includes a number of precompiled binaries of StartX.exe. In the ReleaseU directory is a Unicode x86 build while the ReleaseU64 directory includes a Unicode x64 build.
• As of this version, the code is designed for VC 2010 or later. It will not compile on earlier releases of VC.

v1.06 (11 November 2008)

• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• The code has now been updated to support VC 2005 or later only.
• StartX can now set the process affinity mask via the new AFFINITY command line option. The value you provide here is the value passed to SetProcessAffinityMask. So for example if you wanted to limit the new process to only run on the 2nd and 3rd CPU only of a computer then you would use the command line "/AFFINITY6". i.e. 0x2 & 0x4. Probably the most common value you would use for this would be "/AFFINITY1" which would limit the process to run on the first CPU only. Please note that the value you provide on the command line should be decimal and not hexadecimal. Thanks to "Cobus" for prompting this update.

v1.05 (8 February 2008)

• Updated copyright details.
• Removed VC 6 style AppWizard comments from the code
• Updated the code to clean compile on VC 2008
• The code and shipped exe has been updated to take advantage of VC 2005 specific coding techniques.
• In fact the shipped exe in the zip was compiled with VC 2005 SP1.
• CStartXApp::GetErrorMessage now uses the FORMAT_MESSAGE_IGNORE_INSERTS flag. For more information please see Raymond Chen's blog at http://blogs.msdn.com/oldnewthing/archive/2007/11/28/6564257.aspx. Thanks to Alexey Kuznetsov for reporting this issue.

v1.04 (17 July 2006)

• Updated copyright details.
• Optimized CMyCommandLineInfo constructor code
• Code now uses new C++ style casts rather than old style C casts where necessary.
• CSIDL folders parameter replacement now uses the value @CSIDLnumber@ instead of just @number@. This avoids problems where you need to pass a real "@" onto the application being controlled. Thanks to Ramon Hansman for reporting this issue.
• Updated the documentation to use the same style as the web site.
• Replaced all calls to ZeroMemory with memset
• Code now securely deletes the domain, username and password strings once they have been used.
• Updated the code to clean compile on VC 2005
• The code now requires the Platform SDK if compiled using VC 6.
• Code now uses SHGFP_TYPE_CURRENT instead of SHGFP_TYPE_DEFAULT when calling SHGetFolderPath.
• Fixed a coding error where CStartXApp::InitInstance returned TRUE instead of FALSE.
• CreateProcessWithLogonW is now used if a username is specified or if the prompt password command line option is set.

v1.03 (19 August 2005)

• Error codes are now reported as a string by calling FormatMessage. Thanks to Dennis Bareis for prompting this update.
• String resources which are displayed to the end user now use the format IDP_...

v1.02 (20 December 2004)

• Now supports a /RETURNERROR command line parameter, which returns the error code of the process being run. Setting this parameter implies using /WAIT. Thanks to Tomasz Nowak for suggesting this addition.

v1.01 (20 August 2004)

• Now returns the error code back to the OS as returned from any failures when calling the Win32 SDK calls which StartX uses.
• Now includes a /NOUI command line parameter, which suppresses any messages boxes which can appear when an error occurs. Thanks to Trevor Hart for these 2 suggestions.

3 July 2004

• Now includes explicit info on the usage of the executable "StartX.exe" in the documentation

v1.0 (29 January 2003)

• First public release.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.
• The executable file itself, namely "StartX.exe" can be freely redistributed by anyone.

Installation Requirements

• The program is for Windows (32 bit or 64 bit) and has no external requirements on DLLs other than the ones shipped as standard with any Windows platform. It supports versions of Windows as far back as Windows Vista.

Usage

• Places where you might find StartX useful are in adding an Autorun.inf file to your CD-R / CD-RW Discs. For example suppose you have a text file called readme.txt on the root of your CD which you would like to run it automatically by displaying it in Wordpad maximized whenever the user inserts the CD. All you need to do is put StartX.exe, some ico file and the readme.txt files into the root directory and create a autorun.inf file with the following contents:

[autorun]
open=StartX.exe /MAX "wordpad.exe readme.txt"
icon=youricon.ico

• The more technically minded of you may say why is there a need to have this program since you can use "start filename" on autorun CD's without any apparent problems. The problem with this approach is that it does not work on versions of Windows based on the NT kernel as "start" is implemented as an "Internal" command in cmd.exe (as opposed to a standard exe on Windows 9x) with the upshot that your CD's will not AutoRun on versions of Windows based on the NT kernel. Using StartX will mean that your CD's will autorun on all OS's which support it.
• StartX includes a nearly full superset of the commands which the Windows XP and later internal Start command provides. The full list is:
  
  StartX ["title"] [/Dpath] [/MIN | /MAX | /HIDE] [/NOUI] [/SEPARATE | /SHARED] [/PP] [/Uuser] [/Wpassword] [/Odomain] [/K[desktop]] [/Px,y] [/Scx1,cy1] [/CScx2,cy2] [/FR] [/FG] [/FB] [/BR] [/BG] [/BB] [/FS] [/LP | /LNCO] [/LOW | /NORMAL | /HIGH | /REALTIME | /ABOVENORMAL | /BELOWNORMAL] [/WAIT] [/B] [/RETURNERROR] [/AFFINITYx] [/NODEx] [/PREVENTPINNING] [/TITLEISAPPID] [/TITLEISLINKNAME] [/UNTRUSTEDSOURCE] ["command/program parameters"]
   

  Parameter	Description
  "title"	Title to display in window title bar.
  path	Starting directory
  MIN	Start window minimized
  MAX	Start window maximized
  HIDE	Start window hidden
  NOUI	Suppresses any UI which StartX displays in response to runtime errors. This is helpful when StartX is being called by another process and we want to avoid displaying any UI which requires a user to click a button to close the message displayed.
  SEPARATE	Start 16-bit Windows program in separate memory space
  SHARED	Start 16-bit Windows program in shared memory space
  PP	Prompts for credentials if the program is to be run under another user account.
  user	The account under which to run the program.
  password	The password to use when logging in using the account "user"
  domain	The NT domain to log into when using the account "user"
  desktop	Name of the desktop only or the name of both the desktop and window station to run the program on. A backslash in the string indicates that the string includes both desktop and window station names. If /K is not specified, the program inherits the desktop and window station of the StartX program. If no value for desktop is specified but /K is used, then the process does not inherit the desktop and window station of its parent process; instead, the system determines if a new desktop and window station need to be created. If the impersonated user already has a desktop, the system will use the existing desktop.
  x,y	Specifies the x and y offset, in pixels, of the upper left corner of a window if a new window is created. The offset is from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls CreateWindow to create an overlapped window if the y parameter of CreateWindow is CW_USEDEFAULT.
  cx1, cy2	Specifies the width and height, in pixels, of the window if a new window is created. For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.
  cx2, cy2	For console processes, if a new console window is created, specifies the screen buffer width and height in character columns.
  FR	Specifies that initial text of red color if a new console window is created in a console application
  FG	Specifies that initial text of green color if a new console window is created in a console application
  FB	Specifies that initial text of blue color if a new console window is created in a console application
  BR	Specifies the initial background color of red color if a new console window is created in a console application
  BG	Specifies the initial background color of green color if a new console window is created in a console application
  BB	Specifies the initial background color of blue color if a new console window is created in a console application
  FS	Indicates that the process should be run in full-screen mode, rather than in windowed mode.
  LP	Used in conjunction with the /Uuser parameter. Log on, then load the user's profile. Loading the profile can be time-consuming, so it is best to use this value only if you must access the user's profile information
  LNCO	Used in conjunction with the /Uuser parameter. Log on, but use the specified credentials on the network only. The new process uses the same token as the caller, but the system creates a new logon session within LSA, and the process uses the specified credentials as the default credentials. This value can be used to create a process that uses a different set of credentials locally than it does remotely. This is useful in inter-domain scenarios where there is no trust relationship.
  LOW	Start application in the IDLE priority class
  NORMAL	Start application in the NORMAL priority class
  HIGH	Start application in the HIGH priority class
  REALTIME	Start application in the REALTIME priority class
  ABOVENORMAL	Start application in the ABOVENORMAL priority class
  BELOWNORMAL	Start application in the BELOWNORMAL priority class
  WAIT	Start application and wait for it to terminate
  B	Start application without creating a new window.
  RETURNERROR	Returns the error code of the remote process when it exits. Setting this implies /WAIT
  AFFINITYx	The value "x" will be passed to the function SetProcessAffinityMask. So for example if you wanted to limit the new process to only run on the 2nd and 3rd CPU of a computer then you would use the command line "/AFFINITY6". i.e. 0x2 & 0x4. Probably the most common value you would use for this would be "/AFFINITY1" which would limit the process to run on the first CPU only. Please note that the value you provide on the command line should be decimal and not hexadecimal.
  NODEx	The value "x" specifies the preferred Non-Uniform Memory Architecture (NUMA) node as a decimal integer. This uses the GetNumaNodeProcessorMaskEx API which is available on Windows 7, Windows Server 2008 R2 or later only
  PREVENTPINNING	Sets the STARTF_PREVENTPINNING flag for the newly created process.
  TITLEISAPPID	Sets the STARTF_TITLEISAPPID flag for the newly created process.
  TITLEISLINKNAME	Sets the STARTF_TITLEISLINKNAME flag for the newly created process.
  UNTRUSTEDSOURCE	Sets the STARTF_UNTRUSTEDSOURCE flag for the newly created process.
  command / program parameters	This is the actual command line to use. Please note that the full command line should be enclosed in quotes.

• StartX also supports four replaceable parameters in the all string commands sent to it. These values are parsed case sensitively and are:
  
  @EXEDRV@ which gets replaced with the drive letter path where StartX is run from.
  The other variable is @EXEDIR@ which is the fully qualified folder where StartX is run from.
  @QUOTE@ which puts a Quote character i.e. " into the string when the program is called.
  
  For example:
  
  StartX.exe "@EXEDRV@\Prog\MyProg.exe @EXEDIR@\DataFiles\myfile.xyz"
  
  Another example would if calling Notepad with the file "c:\A directory with spaces\file.txt" and ensuring that the filename is embedded with quotes. In this case, you would use the following command line:
  
  StartX.exe "notepad.exe @QUOTE@c:\directory with spaces\file.txt@QUOTE@"
  
  The final replaceable parameter is @KFIDguid@ where guid corresponds to the value a programmer would use when calling the API SHGetKnownFolderPath. For example to display win.in in notepad assuming it is stored in the Windows directory (FOLDERID_Windows) you would use the command line:
  
  StartX.exe "notepad.exe @KFID{F38BF404-1D43-42F2-9305-67DE0B28FC23}@\win.ini". Please refer to https://msdn.microsoft.com/en-us/library/dd378457(v=vs.85).aspx for the list of Known folder id values.
   

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
27 May 2022