Home page:	NSIS
Documentation:	User Manual
	Modern UI
	InstallOptions2

General Purpose Instructions

4.2.1 CallInstDLL

CallInstDLL dllfile [/NOUNLOAD] function_name

Calls a function_name inside a NSIS extension DLL. See Contrib\ExDLL for an example of how to make one. Extension DLLs can access the stack and variables. Use /NOUNLOAD to force the installer to leave the DLL loaded.

4.2.2 CopyFiles

CopyFiles [/SILENT] [/FILESONLY] filespec_on_destsys destination_path \
          [size_of_files_in_kb]

Copies files from the source to the destination on the installing system. Useful with $EXEDIR if you want to copy from installation media, or to copy from one place to another on the system. Uses SHFileOperation, so the user might see a status window of the copy operation if it is large (to disable this, use /SILENT). The last parameter specifies how big the copy is (in kilobytes), so that the installer can approximate the disk space requirements. On error, or if the user cancels the copy (only possible when /SILENT was omitted), the error flag is set. If /FILESONLY is specified, only files are copied.

4.2.3 CreateDirectory

CreateDirectory path_to_create

Creates (recursively if necessary) the specified directory. The error flag is set if the directory couldn't be created.

4.2.4 CreateShortCut

CreateShortCut link.lnk target.file [parameters \
               [icon.file [icon_index_number \
               [start_options [keyboard_shortcut [description]]]]]]

Creates a shortcut 'link.lnk' that links to 'target.file', with optional parameters 'parameters'. The icon used for the shortcut is 'icon.file,icon_index_number'; for default icon settings use empty strings for both icon.file and icon_index_number. start_options should be one of: SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, or an empty string. keyboard_shortcut should be in the form of 'flag|c' where flag can be a combination (using |) of: ALT, CONTROL, EXT, or SHIFT. c is the character to use (a-z, A-Z, 0-9, F1-F24, etc). Note that no spaces are allowed in this string. A good example is "ALT|CONTROL|F8". $OUTDIR is used for the working directory. You can change it by using "SetOutPath" before creating the Shortcut. description should be the description of the shortcut, or comment as it is called under XP. The error flag is set if the shortcut cannot be created (i.e. the path does not exist, or some other error).

4.2.5 GetDLLVersion

GetDLLVersion filename user_var(high dword output) \
                       user_var(low dword output)

Gets the version information from the DLL (or any other executable containing version information) in "filename". Sets the user output variables with the high and low dwords of version information on success; on failure the outputs are empty and the error flag is set. The following example reads the DLL version and copies a human readable version of it into $0:

GetDllVersion "$INSTDIR\MyDLL.dll" $R0 $R1
IntOp $R2 $R0 / 0x00010000
IntOp $R3 $R0 & 0x0000FFFF
IntOp $R4 $R1 / 0x00010000
IntOp $R5 $R1 & 0x0000FFFF
StrCpy $0 "$R2.$R3.$R4.$R5"

4.2.6 GetDLLVersionLocal

GetDLLVersionLocal localfilename user_var(high dword output) \
                                 user_var(low dword output)

This is similar to GetDLLVersion, only it acts on the system building the installer (it actually compiles into two StrCpy commands). Sets the two output variables with the DLL version information of the DLL on the build system.

4.2.7 GetFileTime

GetFileTime filename user_var(high dword output) \
                     user_var(low dword output)

Gets the last write time of "filename". Sets the user output variables with the high and low dwords of the timestamp on success; on failure the outputs are empty and the error flag is set.

4.2.8 GetFileTimeLocal

GetFileTimeLocal localfilename user_var(high dword output) \
                               user_var(low dword output)

This is similar to GetFileTime, only it acts on the system building the installer (it actually compiles into two StrCpy commands). Sets the two output variables with the file timestamp of the file on the build system.

4.2.9 GetFullPathName

GetFullPathName [/SHORT] user_var(output) path_or_file

Assign to the user variable $x, the full path of the file specified. If the path portion of the parameter is not found, the error flag will be set and $x will be empty. If /SHORT is specified, the path is converted to the short filename form.

4.2.10 GetTempFileName

GetTempFileName user_var(output)

Assign to the user variable $x, the name of a temporary file. The file will have been created, so you can then overwrite it with what you please. The name of the temporary file is guaranteed to be unique. Delete the file when done with it.

4.2.11 SearchPath

SearchPath user_var(output) filename

Assign to the user variable $x, the full path of the file named by the second parameter. The error flag will be set and $x will be empty if the file cannot be found. Uses SearchPath() to search the system paths for the file.

4.2.12 SetFileAttributes

SetFileAttributes filename attribute1|attribute2|...

Sets the file attributes of 'filename'. Valid attributes can be combined with | and are:

• NORMAL or FILE_ATTRIBUTE_NORMAL (you can use 0 to abbreviate this)
• ARCHIVE or FILE_ATTRIBUTE_ARCHIVE
• HIDDEN or FILE_ATTRIBUTE_HIDDEN
• OFFLINE or FILE_ATTRIBUTE_OFFLINE
• READONLY or FILE_ATTRIBUTE_READONLY
• SYSTEM or FILE_ATTRIBUTE_SYSTEM
• TEMPORARY or FILE_ATTRIBUTE_TEMPORARY

The error flag will be set if the file's attributes cannot be set (i.e. the file doesn't exist, or you don't have the right permissions). You can only set attributes. It's not possible to unset them. If you want to remove an attribute use NORMAL. This way all attributes are erased. This command doesn't support wildcards.

4.2.13 RegDLL

RegDLL dllfile [entrypoint_name]

Loads the specified DLL and calls DllRegisterServer (or entrypoint_name if specified). The error flag is set if an error occurs (i.e. it can't load the DLL, initialize OLE, find the entry point, or the function returned anything other than ERROR_SUCCESS (=0)).

4.2.14 UnRegDLL

UnRegDLL dllfile

Loads the specified DLL and calls DllUnregisterServer. The error flag is set if an error occurs (i.e. it can't load the DLL, initialize OLE, find the entry point, or the function returned anything other than ERROR_SUCCESS (=0)).

Miscellaneous Instructions

4.2.15 InitPluginsDir

InitPluginsDir

Initializes the plugins dir ($PLUGINSDIR) if not already initialized.

4.2.16 SetShellVarContext

SetShellVarContext current|all

Sets the context of $SMPROGRAMS and other shell folders. If set to 'current' (the default), the current user's shell folders are used. If set to 'all', the 'all users' shell folder is used. The all users folder may not be supported on all OSes. If the all users folder is not found, the current user folder will be used. Please take into consideration that a "normal user" has no rights to write in the all users area. Only admins have full access rights to the all users area. You can check this by using the UserInfo Plugin. See Contrib\UserInfo\UserInfo.nsi for an example.

4.2.17 Sleep

Sleep sleeptime_in_ms

Pauses execution in the installer for sleeptime_in_ms milliseconds. sleeptime_in_ms can be a variable, e.g. "$0" or a number, e.g. "666".