Logo Computer scientist,
engineer, and educator
• Articles• Articles about computing• Utility corner

win7util command reference

win7util - A set of Windows system utilities for Cygwin

SYNTAX

win7util-{action} [ options ]

 

DESCRIPTION

win7util is a set of utilities for performing many Windows system and desktop operations from Cygwin. These utilities are primarily provided for use in scripts, but the output is generally reasonably human-readable. Among the features provided by win7util are utilities to
*
List and manage processes
*
List and manage windows
*
Modify the desktop settings and appearance
*
Run commands with elevated privileges

win7util is primarily designed for Windows 7, and may not work on other versions of Windows.

 

IMPLEMENTATION

win7util is implemented as a multi-call binary. That is, one executable, called win7util serves all functions. The actual commands invoked by the user, e.g., win7util-list-processes are actually just symbolic links to the same binary. This scheme — the same that is adopted in the BusyBox project — substantially reduces the size of the total package, since a great deal of logic is common to all the utilities. Technical reasons aside, all functions can be invoked using the command name, e.g.,

$ win7util-list-processes

or through the main executable:

$ win7util list-processes

Each command has its own arguments and options but there is (hopefully) consistency between the different commands.

 

AUTHOR

win7util is maintained by Kevin Boone. Comments, suggestions, are welcome: kevin at kevinboone dot net.

 

SEE ALSO


win7util-close-window - Sends a quit or close message to a window

SYNTAX

win7util-close-window [ options ] [ hWnd ]

 

DESCRIPTION

win7util-close-window sends a WM_CLOSE or a WM_QUIT message to a window; WM_CLOSE is the default. The handle may be obtained from win7util-list-windows, among other places. If the window is an application's top-level window, the application typically responds to the WM_CLOSE message in the same way as to a click the close button in the caption — it might not immediately shut down. If the WM_QUIT Message is send, an application normally shuts down immediately, without prompting or saving state. Both messages are a more begign way to shut down an application than terminating its process, but an application that is completely stuck may not respond to either.  

OPTIONS

-h, --help
Print the usage and exit.
-q, --quit
Send WM_QUIT rather than WM_CLOSE
 

EXIT CODE

Returns zero if the window handle is valid. Windows does not provide any information about the effect of the message.  

SEE ALSO

win7util-kill, win7util-list-windows

This command is part of the win7util package for Cygwin.


win7util-empty-recycle-bin - Empty the recycle bin

SYNTAX

win7util-empty-recycle-bin [ options ] [ path ]

 

DESCRIPTION

win7util-empty-recycle-bin attempts to empty the recycle bin, either for all drives, or for the drive that contains the optional path. The command does not prompt for confirmation, nor provide any graphical display of progress.  

NOTES

The use of a path to control the emptying of the recycle bin is not well documented, and does not always appear to have much effect.  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Always seturns zero.  

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-get-clipboard - Get text from the clipboard

SYNTAX

win7util-get-clipboard [ options ]

 

DESCRIPTION

win7util-get-clipboard retrieves text from the clipboard, and prints it to standard out. This command always writes data in UTF-8 Unicode format. If this format is not available on the clipboard, but another text format is, then a conversion will be attempted. If there is no data on the clipboard, or it is not convertible to text, the command fails. Unless told otherwise, the command will convert Windows (CRLF) line terminators to Unix (LF) terminators.  

OPTIONS

-h, --help
Print the usage and exit.
-n, --nocrlf
Do not convert line terminators to Unix format.
 

EXIT CODE

Returns zero if text is successfully read from the clipboard.  

SEE ALSO

win7util-put-clipboard

This command is part of the win7util package for Cygwin.


win7util-get-desktop-window - Gets the handle of the desktop window

SYNTAX

win7util-get-desktop-window [ options ]

 

DESCRIPTION

win7util-get-desktop-window prints to standard output the numeric handle of the desktop window. This handle can be used as an argument to, for example, win7util-post-message. The desktop window is the top of the window stack, and the implicit ancestor of all other windows. However, it does not form the visible user interface — that is the shell window. Blah  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Always returns zero.  

SEE ALSO

win7util-get-shell-window

This command is part of the win7util package for Cygwin.


win7util-get-shell-window - Gets the handle of the shell window

SYNTAX

win7util-get-shell-window [ options ]

 

DESCRIPTION

win7util-get-shell-window prints to standard output the handle of the shell window. This handle can be used, for example, as an argument to win7util-post-message.

The shell window is the visible user interface of the Windows desktop. Various (largely undocumented) operations can be performed by posting messages to it.  

OPTIONS

-h, --help
Print the usage and exit.
 

NOTES

The shell window is a window whose class name is ShellDLL_DefView. The exact place of the shell window in the user interface window stack is undocumented, and varies from one version of Windows 7 to another. It may not even exist in other versions of Windows. Therefore, the success of this command must not be assumed.  

EXIT CODE

Returns zero if the shell window is found.  

SEE ALSO

win7util-get-desktop-window

This command is part of the win7util package for Cygwin.


win7util-get-window-pos - Gets the screen coordinates of a window

SYNTAX

win7util-get-window-pos [ options ] [ hWnd ]

 

DESCRIPTION

win7util-get-window-pos prints to standard output the position and size of a window, in the following form:

x,y,width,height

The x,y values are the pixel position of the top left corner of the window. This position is measured from the top left corner of the primary desktop window. So, for example, in a dual-monitor setup, where the primary desktop is on the right-hand monitor, then a window showing on the left-hand monitor will have a negative x value.

The width,height values are the pixel width and height of the complete window, including the frame (if any).  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Returns zero if the command line is value and hWnd identifies a valid window.  

SEE ALSO

win7util-set-window-pos, win7util-list-windows

This command is part of the win7util package for Cygwin.


win7util-hide-taskbar - Hides the taskbar

SYNTAX

win7util-hide-taskbar

 

DESCRIPTION

win7util-hide-taskbar makes the taskbar invisible. It can be restored using win7util-show-taskbar.  

OPTIONS

None  

NOTES

This command makes use of an undocumented feature of Windows Explorer, and may not work on all Windows versions.  

EXIT CODE

Always returns zero.  

SEE ALSO

win7util-show-taskbar

This command is part of the win7util package for Cygwin.


win7util-kill - Terminates a Windows process

SYNTAX

win7util-kill [ options ] [ PID ]

 

DESCRIPTION

win7util-kill terminates the process identified by the process ID PID. The PID might be identified by, for example, win7util-list-processes.

Terminating a process is a brutal way to stop an application; win7util-close-window is preferable unless the application is totally unresponsive.  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Returns zero if the process ID is valid. An error might be raised if, for example, the user does not have access rights to kill the specified process.  

SEE ALSO

win7util-close-window, win7util-list-processes

This command is part of the win7util package for Cygwin.


win7util-list-actions - List built-in win7util commands

SYNTAX

win7util-list-actions [ options ]

 

DESCRIPTION

win7util-list-actions prints to standard output a list of all the actions that are built into the win7util multi-call binary. It is not really intended to be used by end users, but is provided primarily to allow the installer to create symbolic links for each of the built-in commands. Blah  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Always returns zero.  

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-list-processes - List running Windows processes

SYNTAX

win7util-list-processes [ options ]

 

DESCRIPTION

win7util-list-processes prints a list of running processes, and various information about them.  

OPTIONS

-h, --help
Print the usage and exit.
--csv
Show as comma-separated values
-p, --pathnames
Show full pathnames for executables
--no-caption
Do not show column headings
 

NOTES

Windows allows a user to get a full list of running processes. But if the user does not have access rights to inspect them, no useful information is available.Consequently, win7util-list-processes suppresses these processes. The descriptionc column is taken from the version info block in the executable file; many applications do not provide this data; the field is left blank in such cases.

The Mem column normally gives the memory usage of the process in kB for readability, but shows it in bytes in CSV mode. The memory usage is the 'working set size', one of several different memory measures available through Windows APIs.

 

EXIT CODE

Always returns zero.  

SEE ALSO

win7util-list-windows

This command is part of the win7util package for Cygwin.


win7util-list-recent - List recently-used files, according to the Windows desktop

SYNTAX

win7util-list-recent [ options ] [ number ]

 

DESCRIPTION

win7util-list-recent lists the files and directories most recently used, according to Windows desktop. Typically these will be files that have been opened through Explorer — Windows does not provide access to any have kernel-level record of file access.

The list of recent files is stored as a set of shortcut (.lnk) files in the user profile. Because this list is not managed by the kernel, in practice many of these shortcuts will be out of date. win7util-list-recent can be told to check files and only report valid ones. Additionally, it can purge the list and remove invalid links completely.

Files are listed with the most recent first. When run with a number argument, only that number of files is displayed.  

OPTIONS

-h, --help
Print the usage and exit.
-p, --purge
Delete links to files that no longer exist
-c, --check
Only list files that exist
 

EXIT CODE

Always returns zero, so long as the command-line is well-formed  

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-lock - Locks the workstation

SYNTAX

win7util-lock [ options ]

 

DESCRIPTION

win7util-lock puts the workstation into locked mode, so it cannot be used without entering a password. Optionally, it will then start the screensaver, provided that a screensaver is enabled.  

OPTIONS

-h, --help
Print the usage and exit.
-s, --screensaver
Print the usage and exit.
 

EXIT CODE

Always returns zero  

SEE ALSO

win7util-start-screensaver

This command is part of the win7util package for Cygwin.


win7util-messagebox - Pop up a message dialog box

SYNTAX

win7util-messagebox [ options ]

 

DESCRIPTION

win7util-messagebox pops up a message box containing a text message and one or more buttons. The message box text and caption can be set, as can the number and labelling of the buttons, and the icon displayed in the box. The defaults are unhelpful text messsages, a single 'OK' button, and no icon.

The button selected by the user is indicated by a numeric value written to standard output. These values are as follows:

OK 1
Cancel 2
Abort 3
Retry 4
Ignore 5
Yes 6
No 7
Try again 10
Continue 11

Yes, Windows does distinguish between 'Retry' and 'Try again' and, yes, there are no buttons that produce the results 8 or 9. If the user presses the Escape key, the output is the same as for clicking 'Cancel'.

 

OPTIONS

-h, --help
Print the usage and exit.

-b, --buttons
A numeric code that selects the number and labelling of buttons. These codes are documented in the Windows API documentation for the MessageBox function. Aternatively, use one of the following constants, which should be self-explanatory: MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL, MB_ABORTRETRYIGONRE, MB_CANCELTRYCONTINUE. THe default is MB_OK, that is, a single OK button.

-i, --icon
A numeric code that selects the type of icon to display in the messagebox. Thes codes are documented in the Windows API documentation for the MessageBox function. Aternatively, use one of the following constants, which should be self-explanatory: MB_ICONEXCLAMATION, MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONASTERISK, MB_ICONQUESTION, MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND. The default is not to display any icon.

 

NOTES

win7util-messagebox is Unicode-aware, and expects the text arguments it is passed to be UTF-8 (or ASCII) encoded.

This command does not allow the default button to be set. The default will always be the first button in the messagebox, if there is more than one.

The text that appears on the button will not necessarily be
 'OK', 'Cancel', etc, but will depend on the system language.

The text '\n' in the textR argument is interpreted as an end-of-line indicator. Otherwise, the text will be broken at word boundaries in a way that Windows feels is appropriate.
 
 

EXIT CODE

Returns zero if the command line is valid and the messagebox can be shown. The value selected by the user is present to standard output, not returned as an exit code.
   

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-open - Opens a specified file or directory using the Windows shell

SYNTAX

win7util-open [ options ] [ path ]

 

DESCRIPTION

win7util-open converts a specified path to Windows format, and passes it to the shell to open. The default open action is applied, whatever that is for the specified file. For example, if the path refers to an HTML document, the default action might be to open it with a Web browser.

If path is a directory, then its contents will be displayed using Windows Explorer.

 

OPTIONS

-h, --help
Print the usage and exit.
-s, --state
Sets the initial window state. This can be a number, or a Windows constant such as SW_MAXIMIZE.
 

EXIT CODE

Returns zero the file can be opened by the shell.  

SEE ALSO

win7util-runas

This command is part of the win7util package for Cygwin.


win7util-post-message - Post an arbitrary message to a window

SYNTAX

win7util-post-message [ options ] [ hWnd ] [ uMsg ] [ wParam ] [ lParam ]

 

DESCRIPTION

win7util-post-message posts any message to any window. The arguments are extensively described in the Windows developer documentation at MSDN.

Any of the standard WM_XXX constants can be used for the uMsg argument, but most messages will have no purpose outside an application. Many, for example, expect the lParam argument to contain a pointer to a specific memory structure — something that can't be replicated in a simple command-line utility. It should go without saying that careless use of this command can be highly destructive.  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Returns zero if the window handle is valud.  

SEE ALSO

win7util-list-windows

This command is part of the win7util package for Cygwin.


win7util-put-clipboard - Puts text from a file or stdin onto the clipboard

SYNTAX

win7util-put-clipboard [ options ] [ file ]

 

DESCRIPTION

win7util-put-clipboard reads from a file, if a file is specified, or standard input if not, and puts the text onto the clipboard. The file is assumed to be in UTF-8 (or ASCII) encoding, with Unix LF line terminators. The results will be unpredictable if that is not the case.

By default, the data is converted to Windows Unicode (UTF-16, essentiallY), and Windows CR-LF line terminators. This is almost always the right thing to do if you want to paste the data into a Windows application, but this behaviour can be changed by command-line options.  

OPTIONS

-h, --help
Print the usage and exit.
-a, --ansi
Puts data onto the clipboard in the ANSI character set, rather than Windows Unicode
-n, --nocrlf
Do not convert Unix LF line terminators to Windows CR-LF
 

NOTES

The results will be unpredictable if the --ansi option is used with text that cannot be represented in the 8-bit ANSI character set. This command can not be properly be used to put anything onto the clipboard except text.  

EXIT CODE

Returns zero if text is successfully written to the clipboard.  

SEE ALSO

win7util-get-clipboard

This command is part of the win7util package for Cygwin.


win7util-read-shortcut - Read the target and other information from a desktop shortcut

SYNTAX

win7util-read-shortcut [ options ] { path }

 

DESCRIPTION

win7util-read-shortcut reads the target and, optionally, other information from a desktop shortcut. Shortcuts typically have names ending in .lnk, and are in a Microsoft proprietary format.

 

OPTIONS

-f, --full
Print working directory, icon path, etc., as well as the target
-h, --help
Print the usage and exit.
-r, --resolve
Invoke the Windows link resolution process. If the link does not indicate a valid target (for example, the target has been deleted), then Windows may offer to try to find it, or to delete the link
 

LIMITATIONS

*
The hot-key code from the shortcut is not displayed, as this is a numeric value that would probably make little sense outside a Windows application
*
It is possible to create shortcuts to things that are not files; however, such shortcuts are not (yet) supported by this utility.
*
So far as possible, all pathnames displayed are in Cygwin format. However, the command-line arguments specified in the shortcut (if any) are not in any defined format. If they do contain filenames, there is no safe way to convert them.
*
This command is not Unicode-aware. Information that this stored in the shortcut, and which cannot be coverted to ANSI text, will not be rendered correctly.

 

EXIT CODE

Returns zero if the shortcut can be read.  

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-runas -Runs a program or shell as a different user

SYNTAX

win7util-runas [ options ] { user } [ command ]

 

DESCRIPTION

win7util-runas is broadly equivlanent to the Windows RUNAS command, except that the path to the command is in Unix format, and the Cygwin terminal (mintty) will host the shell (if it is available), rather than a DOS Box. If the Cygwin terminal is not available (as is the case with old versions of Cygwin), then bash is invoked in a DOS Box.

This command can run Windows, rather than Cygwin, binaries; but there is little point, as RUNAS does the same thing better — the arguments to the Windows binary would still have to be in Windows format, and you'd get an unnecessary terminal window.

Unlike RUNAS, win7util-runas will let you throw caution to the wind and specify the password on the command line. Needless to say, this could be magnificently damaging to security.  

OPTIONS

-h, --help
Print the usage and exit.
-p, --password {password}
Use this password, rather than prompting.
 

NOTES

win7util-runas is really intended as a quick way to get a shell with administrator privileges. Like RUNAS, it has to open a session in a new terminal, because an ordinary user won't have access rights to run a new process with elevated privileges (this is why the Cygin su command has never really worked). The new session starts with the same working directory as the one in which win7util-runas was invoked.

This command does its best to set profile-specific environment variables in the process is creates, but there is no definitive method to get an appropriate environment for a user without a security token, which we don't get until after spawning the process. So a certain amount of guesswork is involved here. Utilities that rely on user-specific environment settings like APPDATA probably won't work.

Note that win7util-runas does not use the Windows shell to execute the process, so the command argument must actually be an executable, not a document file (unlike win7util-open).

 

EXIT CODE

Returns zero if the command or shell can be executed. This command can fail with an error code for a whole host of reasons; most obviously, the user credentials may be incorrect, or the command may not exist.  

SEE ALSO

win7util-open

This command is part of the win7util package for Cygwin.


win7util-set-background - Sets the desktop background image

SYNTAX

win7util-set-background [ options ] [ file ]

 

DESCRIPTION

win7util-set-background sets the specified image to be the desktop background. The existing settings regarding image scaling and fitting are not changed. On Windows 7, this command has the side-effect of setting the directory containg the file as the slideshow directory.  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Returns zero if the file exists. Windows does not indicate whether the background was successfully changed.  

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-show-taskbar - Shows the taskbar

SYNTAX

win7util-show-taskbar

 

DESCRIPTION

win7util-show-taskbar makes the taskbar visible, if it has previously been made invisible using win7util-hide-taskbar.  

OPTIONS

None  

NOTES

This command makes use of an undocumented feature of Windows Explorer, and may not work on all Windows versions.  

EXIT CODE

Always returns zero.  

SEE ALSO

win7util-hide-taskbar

This command is part of the win7util package for Cygwin.


win7util-show-window - set the visibility and state of a window

SYNTAX

win7util-show-window [ options ] [ hWnd ] [ state ]

 

DESCRIPTION

win7util-show-window Sets the window state, if possible. The hWnd argument argument is the handle of a window, perhaps obtained by win7util list-windows. state is a numeric code,
 which can be one of the constants sw_show, etc.

Blah  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Returns zero if the window handle is valid. Windows does not provide any information about whether the state actually changed.  

SEE ALSO

win7util-list-windows

This command is part of the win7util package for Cygwin.


win7util-start-screensaver - Starts the screensaver

SYNTAX

win7util-start-screensaver

 

DESCRIPTION

win7util-start-screensaver does exactly what its name implies — it starts the screensaver immediately. This command has an effect only if a screensaver is currently configured and enabled.  

OPTIONS

None  

EXIT CODE

Always returns zero  

SEE ALSO

win7util-lock

This command is part of the win7util package for Cygwin.


win7util-suspend - Tells the system to sleep or hibernate

SYNTAX

win7util-suspend [ options ]

 

DESCRIPTION

win7util-suspend tells the system to sleep (the default), or to hibernate. The result should be exactly the same as for selecting these power states from the Windows shell. As for the shell, hibernation will fail if it is not enabled in the power scheme settings.  

OPTIONS

-h, --help
Print the usage and exit.
--hibernate
Hibernate, rather than sleep
 

EXIT CODE

Returns zero if the operation succeeds. If it succeeds, then the command does not exit until the system has resumed.  

SEE ALSO

This command is part of the win7util package for Cygwin.

win7util-toggle-desktop-icons - Change visibility of desktop icons

SYNTAX

win7util-toggle-desktop-icons

 

DESCRIPTION

win7util-toggle-desktop-icons switches the desktop icons between visible and invisible.  

OPTIONS

None  

NOTES

This command makes use of an undocumented feature of Windows Explorer, and may not work on all Windows versions.  

EXIT CODE

Always returns zero.  

SEE ALSO

win7util-show-taskbar, win7util-hide-taskbar

This command is part of the win7util package for Cygwin.


win7util-unmount - Dismounts and ejects removeable drives

SYNTAX

win7util-unmount [ options ] { drive_letter }

 

DESCRIPTION

win7util-unmount YYY Dismounts and optionally ejects media from a removable drive. Unlike in Unix, a 'dismount' in Windows is only a partial unmount. Locking and dismounting " the drive ensures that it is not in use, and can safely be removed, but the drive letter remains known to the system. The eject operation both removes the drive from the system, and physically ejects the " media, if the drive allows it. Most often, therefore, this command " will best be used with the --eject option.

Unlike most win7util commands, win7util-dismount takes a Windows drive letter as an argument, as the Windows API requires a reference to the driver, not a path.  

NOTES

This command cannot be used to eject devices that are considered non-removable, such as external SATA drives.  

OPTIONS

-h, --help
Print the usage and exit.
 

EXIT CODE

Returns zero if the operation succeeds.  

SEE ALSO

This command is part of the win7util package for Cygwin.
Copyright © 1994-2013 Kevin Boone. Updated Mar 03 2013