System

Operating system and machine configuration and control

SYNOPSIS

package require twapi_os
abort_system_shutdown ?-system SYSTEM?
find_domain_controller ?options?
get_computer_name ?NAMETYPE?
get_computer_netbios_name
get_memory_info ?options?
get_numa_config
get_primary_domain_controller ?options?
get_primary_domain_info ?options?
get_os_description
get_os_info
get_os_version
get_processor_count
get_processor_group_config
get_processor_info PROCESSOR ?options?
get_system_parameters_info PARAMETER
get_system_sid
get_system_time
get_system_uptime
lock_workstation
logoff ?-force? ?-forceifhung?
min_os_version osmajor ?osminor? ?spmajor? ?spminor?
set_system_parameters_info PARAMETER VALUE ?-persist? ?-notify?
shutdown_system ?options?
start_wts_session_monitor COMMAND ?-all?
stop_wts_session_monitor WTS_MONITOR_ID
suspend_system ?options?

DESCRIPTION

This module provides commands related to the system configuration including operating system functions and hardware configuration.

Overview

The commands get_os_version and min_os_version get and verify operating system version information.

The commands get_os_info and get_os_description allow retrieval of more detailed operating system information than the standard Tcl commands which do not distinguish between service packs, Professional versus Server versions and so on.

The command get_computer_name returns one of several forms of the system name. The command get_computer_netbios_name returns the NETBIOS name of the computer. Domain and workgroup information about the system can be obtained through the get_primary_domain_info command. find_domain_controller returns information about a domain controller with specified characteristics. get_primary_domain_controller returns the name of the primary domain controller of the computer.

The commands get_processor_count, get_processor_group_configuration and get_processor_info retrieve information about the processors in the system.

The command get_memory_info returns the physical and virtual memory configuration of the system.

The command get_system_time returns the current system time in high resolution. The command get_system_uptime returns the how long the system has been running. The command shutdown_system may be used to shutdown or reboot the system. The command abort_system_shutdown may be used to abort an ongoing system shutdown. The command suspend_system may be used to put the system in stand by or hibernate states. You can prevent the system from being suspended due to inactivity through the SetThreadExecutionState command. The commands logoff and lock_workstation may be used to log out of a user account and to lock a workstation respectively. Notifications regarding user switching, logon, logoff etc. can be enabled and disabled with the start_wts_session_monitor and stop_wts_session_monitor commands.

Various system settings related to the user experience can be retrieved and set through the get_system_parameters_info and set_system_parameters_info commands.

Commands

abort_system_shutdown ?-system SYSTEM?
Aborts a previously initiated system shut down or reboot. Note this is only possible if the system shutdown was initiated with a non-zero timeout value. The command enables any required privileges and restores the original privileges before returning.
find_domain_controller ?options?
Returns the name of a domain controller with specified characteristics and optionally, details about its characteristics and capabilities.
-allowstale BOOLEAN If specified as true, the system will return cached domain controller information even if it is marked as expired. Default is false. This option has no effect if -rediscover is specified as true.
-avoidself BOOLEAN If specified as true, and the command is run on a domain controller, the domain controller will return the name of another domain controller, not itself. Default is false.
-domain DOMAINNAME Specifies the domain whose domain controller is to be retrieved. If unspecified, defaults to the primary domain of the computer.
-domainguid GUID If the domain specified by the -domain option or the primary domain of system cannot be found, the command will attempt to return the domain controller for the domain with the specified GUID. Note this option may require -system to specify a system that knows about the specified domain GUID.
-getdetails By default, the command returns the name of the domain controller. If this option is specified, the command returns detailed information whose format is described below.
-inputnameformat NAMEFORMAT Specifies the format of the specified domain name. NAMEFORMAT may be one of dns, which implies DNS format, netbios which implies flat Netbios format, or any (default) which results in the command searching both namespaces.
-justldap BOOLEAN If specified as true, the command searches for a LDAP server without caring if it is a domain controller.
-rediscover BOOLEAN If specified as true, the system ignores any cached domain controller data. Default is false. Note specifying this option as true significantly increases the time to execute the command.
-outputaddrformat ADDRFORMAT If ADDRFORMAT is specified as ip, the -dcaddr field in the returned information is the Internet address.
-outputnameformat NAMEFORMAT Specifies the format in which the domain controller and domain names should be returned. NAMEFORMAT may be one of dns, which implies DNS format, netbios which implies flat Netbios format, or any (default). The command will raise an error if the name is not available in the specified format.
-prefer FEATURE Indicates that the domain controller that support the specified features and services is returned in preference to one that does not. FEATURE is either directoryservice or timeserver (see below).
-require FEATURELIST Indicates that the domain controller to be returned must support the specified features and services. FEATURELIST is a list of zero or more features from the following: directoryservice (Active Directory support), globalcatalog (global catalog server for the forest rooted by this domain), pdc (primary domain controller for this domain) kdc (Kerberos Key Distribution center service) timeserver (running Windows Time Service) writable (must not be read-only). Note that the features pdc, kdc and globalcatalog are mutually exclusive and must not be specified together.
-site SITENAME Specifies the name of the site where the domain controller should be physically located. If an empty string (default), the command will attempt to return a controller in a site that is closest to the site of the system specified by the -system option.
-system COMPUTERNAME Specifies the DNS or NETBIOS name of the computer on which the lookup is to be done. If unspecified, defaults to the local system.
If the -getdetails option is specified, the command returns detailed information about the controller instead of just its name. The returned information is a flat list of key value pairs with the following elements:
-clientsite The name of the site containing the system specified by the -system option.
-dcname Name of the domain controller which may be either in DNS or Netbios format.
-dcnameformat Either dns if the -dcname field is in DNS format, or netbios if it is a Netbios name.
-dcaddr Address of the domain controller. This may be either the Netbios address or the IP address depending on the value of the specified -outputaddrformat option.
-dcaddrformat Either ip if the -dcaddr field is in IP address format, or netbios if it is a Netbios address.
-dcsite The name of the site containing the domain controller.
-dnsforest Name of the domain that is at the root of the directory service tree.
-dnsforestformat Either dns if the -dnsforest field is in DNS format, or netbios if it is a Netbios name.
-domainguid GUID of the domain.
-domain Name of the domain.
-domainformat Either dns if the -domain field is in DNS format, or netbios if it is a Netbios name.
-features Contains a list describing domain controller features. This list may contain zero or more of the following: closest (domain controller is closest site to client), directoryservice (Active Directory support), ldap (supports LDAP access), globalcatalog (global catalog server for the forest rooted by this domain), pdc (primary domain controller for this domain), kdc (Kerberos Key Distribution center service), timeserver (running Windows Time Service), goodtimeserver (running Windows Time Service with a physical clock), writable (is not read-only).
Note that any of these fields may have empty string values if the information is not relevant or cannot be found.
get_computer_name ?NAMETYPE?
Returns the name of the computer. NAMETYPE must be one of the following:
netbios Returns the NETBIOS name of the local computer or the cluster virtual server if it is in a cluster.
dnshostname Returns the DNS host name of the local computer or the cluster virtual server if it is in a cluster.
dnsdomain Returns the DNS domain of the local computer or the cluster virtual server if it is in a cluster.
dnsfullyqualified Returns the fully qualified DNS domain of the local computer or the cluster virtual server if it is in a cluster.
physicalnetbios Returns the NETBIOS name of the local computer.
physicaldnshostname Returns the DNS host name of the local computer.
physicaldnsdomain Returns the DNS domain of the local computer.
physicaldnsfullyqualified Returns the fully qualified DNS name of the local computer.
If NAMETYPE is not specified, it defaults to netbios.
get_computer_netbios_name
Returns the NETBIOS name of the computer.
get_memory_info ?options?
Returns various information about the physical and virtual memory configuration of the system. The information returned is in the form of a flat list of the form "field1 value1 field2 value2 ..." depending on which of the following options are specified:
-all Returns all the options listed below.
-allocationgranularity Returns the granularity with which virtual memory is allocated.
-availcommit Returns the amount of additional memory that can be committed by the system without extending the paging files.
-availphysical Returns the amount of free physical memory.
-kernelpaged Returns the amount of memory in the kernel paged pool.
-kernelnonpaged Returns the amount of memory in the kernel non-paged pool.
-maxappaddr Returns the highest address that may be mapped into an application's address space.
-minappaddr Returns the lowest address that may be mapped into an application's address space.
-pagesize Returns the size of a virtual memory page
-peakcommit Returns the peak size of the paging files since the last system reboot.
-physicalmemoryload Percentage of physical memory currently in use.
-processavailcommit Returns the amount of additional memory that can be committed by the current process.
-processcommitlimit Returns the maxiumm amount of memory that can be committed by the current process.
-processtotalvirtual Size of the user-mode virtual address space of the current process.
-processavailvirtual Size of the user-mode virtual address space that is currently not reserved or committed.
-systemcache Returns amount of memory used for the system cache.
-swapfiles Returns a list of the swap files for the system.
-swapfiledetail Returns a flat list of pairs corresponding to the swap files. The first element of each pair is the name of the swap file. The second element is a list of consisting of the current size of the file (in pages), the number of pages in use, and the peak number of pages that have been used in the file.
-totalcommit Returns the maximum amount of virtual memory that can be committed without extending the swap files.
-totalphysical Returns the total amount of physical memory installed in the system.
-usedcommit Returns the current size of memory committed.
get_numa_config
Returns the NUMA configuration of the system as a dictionary keyed by the NUMA node number. The corresponding value is a nested dictionary with keys -group and -processormask which processors in a processor group comprise that NUMA node.

Returns an empty string if the Windows version does not support NUMA.
get_primary_domain_controller ?options?
Returns the primary domain controller (PDC) for a domain. The command find_domain_controller should be preferred to this command.

The following options may be specified:
-domain DOMAINNAME Specifies the domain whose PDC is to be retrieved. If unspecified, defaults to the primary domain.
-system COMPUTERNAME Specifies the DNS or NETBIOS name of the computer on which the lookup is to be done. If unspecified, defaults to the local system.
get_primary_domain_info ?options?
Returns information about the primary domain or workgroup of the system as a flat list of option value pairs. The following options control what information is returned.
-all Equivalent to specifying all options.
-dnsdomainname Returns the DNS name of the primary domain.
-dnsforestname Returns the DNS forest name of the primary domain.
-domainguid Returns the GUID of the primary domain.
-name Returns the domain or workgroup name.
-sid Returns the SID of the primary domain.
-type Returns workgroup or domain depending on whether the system belongs to a workgroup or a domain.
If the system belongs to a workgroup, all options will return empty values except -name and -type.
get_os_description
This commmand returns the same operating system information as returned by get_os_info but in a form suitable for displaying to a user.
get_os_info
This command retrieves operating system version and configuration information and returns a keyed list with the following fields:
os_build_number Contains the operating system build number.
os_major_version Major operating system version.
os_minor_version Minor operating system version.
sp_major_version Major service pack version.
sp_minor_version Minor service pack version.
suites Contains a list of values (see below) that indicate various options that may be installed as part of the operating system.
system_type Indicates the operating system base type. This is workstation for Windows NT 4.0 Workstation, Windows 2000 Professional, or any Windows XP operating system versions. If the system is a domain controller, this value is domain_controller. In all other cases, this value is server.
The suites element in the returned array contains a list of values from the following set that indicates additional operating system components that are present:
backoffice Microsoft BackOffice components are installed.
blade Windows .NET Server 2003 family Web Edition is installed.
communications A version of Microsoft Office Communications Server is installed.
compute_server Windows Server 2003 family Computer Cluster Edition is installed.
datacenter Datacenter version of Windows 2000, Windows Server 2003 or Windows Server 2008 is installed.
embeddednt Windows XP Embedded is installed.
embedded_restricted
enterprise Windows 2000 Advanced Server, or the Enterprise version of Windows Server 2003 or Windows Server 2008 is installed.
personal A Home Edition of Windows XP, Windows Vista or Windows 7 is installed.
security_appliance A hardened installation of Windows Server 2003 in a security appliance.
singleuserrts Remote desktop is supported only for a single interactive session.
smallbusiness Microsoft Small Business Server is installed.
smallbusiness_restricted Microsoft Small Business Server is installed with the restrictive client license in force.
storage_server A Windows Storage Server version of Windows 2003 or Windows 2003 R2 is installed.
terminal Terminal Services are installed.
wh_server Windows Home Server is installed.
get_os_version
This command returns the operating system version as list of four elements - the operating system major version number, the operating system minor version number, the service pack major version number, the service pack minor version number.
get_processor_count
Returns the number of processors in the system.
get_processor_group_config
Newer versions of Windows partition processors into processor groups when there more than 64 processors in the system. This command returns information about how the groups are configured. The return value is a dictionary with two keys, -maxgroupcount which is the maximum number of processor groups that can be configured in the system, and -activegroups which is a dictionary keyed by the processor group number. The corresponding value is a nested dictionary with keys -maxprocessorcount, -activeprocessorcount and -processormask which contains the maximum number of processors that can be configured in the group, the number of currently active processors and the group's processor mask.

On older versions of Windows, the information returned will contain the single processor group 0.
get_processor_info PROCESSOR ?options?
Returns various pieces of information related to the processors in the system. PROCESSOR identifies the processor whose information is to be retrieved. If specified as an empty string, information across all processors in the processor group for the current process is returned. Note this is different from processors across the entire system when it has more than 64 processors.

The return value is a dictionary keyed by the specified options:
-all Returns all fields listed below.
-arch Returns the processor architecture.
-dpctime The amount of CPU time in 100ns units spent in servicing deferred procedure calls. Note this value is included in the -privilegedtime value.
-idletime The amount of idle CPU time in 100ns units since system start. Note this value is included in the -privilegedtime value.
-interrupts Returns the total number of interrupts serviced since system start.
-interrupttime The amount of CPU time in 100ns units spent in servicing interrupts. Note this value is included in the -privilegedtime value.
-privilegedtime The amount of privileged (kernel) context CPU time since system start in 100ns units. Note this includes the DPC, interrupt and idle CPU cycles.
-processormodel Returns the processor model. PROCESSOR must not be an empty string if this option is specified.
-processorname Returns a human readable form of the processor description. PROCESSOR must not be an empty string if this option is specified.
-processorrev Returns the processor revision as defined by the CPU manufacturer. PROCESSOR must not be an empty string if this option is specified.
-processorspeed Returns the nominal speed in Mhz of the processor PROCESSOR must not be an empty string if this option is specified.
-processorlevel Returns the processor level as defined by the CPU manufacturer.
-usertime The amount of user context CPU time in 100ns units since the system was started.
get_system_parameters_info PARAMETER
This command wraps the Windows SystemParametersInfo function and allows retrieval of various user interface settings such as screensaver timeout, mouse speed etc. The information retrieved depends on the PARAMETER which must be one of the SPI_ symbols listed in the SystemParametersInfo documentation.
get_system_sid
Returns the SID of the system.
get_system_time
Returns the current system time in UTC as the number of 100 nanosecond units since Jan 1, 1601. This can be converted to a format suitable for use with the clock command through the use of the command large_system_time_to_secs_since_1970.
get_system_uptime
Returns the number of seconds elapsed since the system was booted.
lock_workstation
Initiates a request to lock the work station display.
logoff ?-force? ?-forceifhung?
Logs off the current session. If -force is specified, it forces processes to terminate without notifying them. This options should generally not be specified as it can result in data loss. If -forceifhung is specified, it only terminates processes if they do not respond to the session end notifications.
min_os_version osmajor ?osminor? ?spmajor? ?spminor?
This function checks that the operating system version meets the specified minimum version. It returns 1 if the operating system version is greater than osmajor.osminor.spmajor.spminor. Otherwise it returns 0. Any unspecified optional arguments default to 0.
set_system_parameters_info PARAMETER VALUE ?-persist? ?-notify?
This command wraps the Windows SystemParametersInfo function and allows setting of various user interface settings such as screensaver timeout, mouse speed etc. The information retrieved depends on the PARAMETER which must be one of the SPI_ symbols listed in the SystemParametersInfo documentation. The corresponding setting is assigned VALUE.

If the -persist is specified, the changed setting is written to the user's profile. If -notify is specified, all applications are notified of the change. Note -notify only has effect if -persist is also specified since other applications will update based on the user's persistent profile.
shutdown_system ?options?
Initiates a system shut down or reboot. The command enables any required privileges and restores the original privileges before returning.

The following options may be specified:
-system SYSTEMNAME Specifies the system to be shut down. By default, this is the local system.
-timeout SECONDS Specifies the amount of time to wait before shutting down the system. During this time, a shutdown dialog is displayed to the user. If a value of 0 is specified, the system is shut down immediately and no dialog is displayed to the user.
-message MESSAGE Specifies a message to be displayed to the user in the shutdown dialog.
-force Normally, the system displays a dialog box asking the user to close any applications with unsaved data. If the -force option is specified, applications are forcible closed resulting in possible data loss.
-restart If specified, the system is restarted after the shut down.
start_wts_session_monitor COMMAND ?-all?
Starts monitoring state of Windows Terminal services sessions. Any changes will result in the command prefix COMMAND being invoked with two additional arguments - the numeric value identifying the change and the session identifier of the session whose state changed. See the SDK documentation of the WM_WTSSESSION_CHANGE Windows message for possible event change values.

By default, only events for the current session are monitored. Specify the -all option to monitor events for all sessions.

The command returns a handle that must be passed to stop_wts_session_monitor to stop the monitor when no longer required.
stop_wts_session_monitor WTS_MONITOR_ID
Stops monitoring of Windows Terminal services sessions. WTS_MONITOR_ID must be a handle returned by a previous call to start_wts_session_monitor.
suspend_system ?options?
Places the system in a stand by or hibernate state. The command takes the following options:
-state STATE STATE must be one of standby (default) or hibernate depending on whether the state into which the system is to be placed.
-force BOOLEAN If false (default), the system sends a PBT_ATMQUERYSUSPEND message to all applications before placing the system in stand by or hibernate states. If this option is specified as true, the message is not sent and the system is immediately placed into the appropriate state.
-disablewakeevents BOOLEAN If false (default), system wake events remain enabled. If true they are disabled.

COPYRIGHT

Copyright © 2003-2021 Ashok P. Nadkarni

Tcl Windows API 4.7.1