Tcl Windows API extension

Several commands, for example, looking up account names or adding users, may be carried out on a target system other than the local system. The -system option allows specification of the target system. This option defaults to the local system if unspecified.

User and Group Accounts

The command lookup_account_name, map_account_to_name, lookup_account_sid and map_account_to_sid translate between user and group account names and their SID's. The command is_valid_sid_syntax validates the syntax of an SID.

The commands new_user and delete_user allow addition and deletion of user accounts. The commands enable_user, disable_user and unlock_user may be used to change the state of a user account. The command get_user_account_info returns various attributes and properties of a user account. These may be modified through the set_user_account_info function or alternatively, modified individually through the following set of functions: set_user_name, set_user_password, set_user_home_dir, set_user_comment, set_user_script_path, set_user_full_name, set_user_country_code, set_user_profile, set_user_home_dir_drive, set_user_expiration.

Information about global and local groups may be retrieved through the get_global_group_info and get_local_group_info commands. New global groups may be created and deleted through the new_global_group and delete_global_group commands. The equivalent commands for local groups are new_local_group and delete_local_group. Users may be added and removed using the commands add_user_to_global_group, add_member_to_local_group, remove_user_from_global and remove_member_from_local_group.

The rights and privileges associated with accounts can be managed through the get_account_rights, find_accounts_with_right, add_account_rights and remove_account_rights commands.

Enumerating Accounts

There are several commands for enumerating users and groups, including group membership.

The commands get_users, get_global_groups and get_local_groups enumerate users and groups on a system.

The commands get_local_group_members and get_global_group_members allow enumeration of the members of a group. get_user_local_groups_recursive returns information about the local groups in which the user account has direct or indirect membership.

With the exception of get_user_local_groups_recursive, all these commands follow the same pattern of invocation and use a standard set of options. Without any optional arguments, the commands return a simple list of user or group names as appropriate. However, the commands also allow retrieval of information with additional detail or in incremental fashion.

To get more detail about about the accounts being returned without making separate calls for each individual account, the -level option may be specified. When this option is specified, the list of accounts returned is a nested list instead of a flat list of names. Each sublist is a keyed list containing details for the account. The argument value passed with the option is an integer that indicates the level of detail desired. The valid values for the argument and the specific fields returned in the sublist are dependent on the command and are described in the documentation for the command. See the examples below for sample useage.

On systems (including domains) with a very large number of accounts, it may be better for performance and user responsiveness to retrieve the list in incremental fashion through -resume option. On the initial call to any of the commands, the RESUMEHANDLE value for the option must be specified as 0. The command will then return a list of the form { MOREDATA RESUMEHANDLE COUNT VALUELIST }. In the returned list, MOREDATA is a boolean indicating if there are more accounts to be enumerated. If this value is 1, then the appropriate command can be called again, this time passing RESUMEHANDLE as the value for the -resume option. This process can be repeated as long the MOREDATA field in the returned result is 1. If MOREDATA is 0, there is no more data to be retrieved. The RESUMEHANDLE must be treated as opaque and must not be modified in any way before being passed back in the next call to the command. It is critical that the command be repeated with the correct value of RESUMEHANDLE and only if MOREDATA is 1. The system does not protect against bad values which can crash your application. The other elements returned when the -resume option is used are COUNT and VALUELIST. The former is an estimate of the sum of items returned in this call and those remaining to be returned. Note this is only an estimate and should not be relied on except for rough purposes such as displaying a progress bar. The VALUELIST element is the actual values that are the result of the call. The format of this depends on the use of the -level option as described above.

The following sample session demonstrates the use of the two options and the format of the returned data:

(tcl) 63 % get_local_group_members Administrators
Administrator ashok
(tcl) 64 % get_local_group_members Administrators -level 1
{sid S-1-5-21-776561741-1580818891-725345543-500 sidusage 1 name Administrator} {sid S-1-5-21-776561741-1580818891-725345543-1003 sidusage 1 name ashok}
(tcl) 65 % get_local_group_members Administrators -resume 0
0 0 2 {Administrator ashok}
(tcl) 66 % get_local_group_members Administrators -resume 0 -level 1
0 0 2 {{sid S-1-5-21-776561741-1580818891-725345543-500 sidusage 1 name Administrator} {sid S-1-5-21-776561741-1580818891-725345543-1003 sidusage 1 name ashok}}

Commands

add_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?

Adds the privileges and account rights listed in RIGHTS to the account specified by ACCOUNTNAME. The option -system may be used to specify a system as described in Standard Options.

RIGHTS is a list of privileges and account rights. Refer to Authorization constants in the Windows SDK for valid values. Note: you must use the string form of the privilege or right, for example, SeBatchLogonRight, not SE_BATCH_LOGON_NAME.

add_user_to_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?

Adds the user account specified by USERNAME to the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

add_member_to_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?

Adds the account specified by ACCOUNTNAME to the local group GROUPNAME. ACCOUNTNAME may be either a user name or a global group and may include a domain in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

delete_global_group GROUPNAME ?-system SYSTEMNAME?

Deletes a global group GROUPNAME. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

delete_local_group GROUPNAME ?-system SYSTEMNAME?

Deletes a local group GROUPNAME. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

delete_user USERNAME ?-system SYSTEMNAME?

Delete the specified user account. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

disable_user USERNAME ?-system SYSTEMNAME?

Disables a user account. The option -system may be used to specify a system as described in Standard Options.

enable_user USERNAME ?-system SYSTEMNAME?

Enables a user account. The option -system may be used to specify a system as described in Standard Options.

find_accounts_with_right RIGHT ?-system SYSTEMNAME? ?-name?

Returns a list of all accounts (user and group) that hold the right or privilege specified by RIGHT. The returned list contains the SID's of the account unless the -name option is specified in which case the account names are returned instead.

Refer to Authorization constants in the Windows SDK for valid values for RIGHT. Note: you must use the string form of the privilege or right, for example, SeBatchLogon, not SE_BATCH_LOGON_NAME.

The option -system may be used to specify a system as described in Standard Options.

get_account_rights ACCOUNTNAME ?-system SYSTEMNAME?

Returns the list of rights and privileges for the user or group specified by ACCOUNTNAME. This only includes those directly belonging to the account, and does not include the ones inherited from membership in groups.

The option -system may be used to specify a system as described in Standard Options.

get_global_group_info GROUPNAME ?options?

Retrieves information about the specified global group. The actual information returned depends on the specified options and is returned as a list of the form "option value...". The following options may be specified:

-all	Returns all data items.
-attributes	Returns the group attributes as a list. See get_token_groups_and_attrs for values.
-comment	Returns the comment associated with the group account.
-name	Returns the name of the group.
-sid	Returns the SID for the group.
-members	Returns the members of the group.

get_global_group_members GROUPNAME ?options?

If no options are specified, returns a list of user accounts that are members of the global group GROUPNAME.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields are shown in the following table:

0	name
1	attributes, name

get_global_groups ?options?

If no options are specified, returns the list of global groups on the system.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields are shown in the following table:

0	name
1	comment, name
2	attributes, comment, group_id, name
3	attributes, comment, group_sid, name. This level may not be supported on all versions of Windows.

Refer to the documentation of get_global_group_info for a description of these fields.

get_local_group_info GROUPNAME ?options?

Retrieves information about the specified local group. The actual information returned depends on the specified options and is returned as a list of the form "option value...". The following options may be specified:

-all	Returns all data items.
-comment	Returns the comment associated with the group account.
-name	Returns the name of the group.
-sid	Returns the SID for the group.
-members	Returns the members of the group.

get_local_group_members GROUPNAME ?options?

If no options are specified, returns a list of user accounts that are members of the local group GROUPNAME.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields are shown in the following table:

0	sid
1	name, sid, sidusage
2	domainandname, sid, sidusage
3	domainandname

The meanings of the fields should be self-evident.

get_local_groups ?options?

If no options are specified, returns the list of local groups on the system.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields are shown in the following table:

0	name
1	comment, name

Refer to the documentation of get_local_group_info for a description of these fields.

get_user_account_info ACCOUNT ?-system SYSTEMNAME? ?options?

Returns attributes and properties of a user account as a list of the form "option1 value1 ...". ACCOUNT specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed.

The data returned depends on which of the following options are specified:

-acct_expires	Returns the time when the account is set to expire. This value may be never or unknown or the number of seconds since Jan 1, 1970 00:00:00 UTC as accepted by the Tcl clock command.
-all	Returns all data items.
-bad_pw_count	Returns the number of login attempts for that account that failed because of a bad password. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-code_page	Returns an integer corresponding to the code page for the user's preferred language.
-comment	Returns the comment associated with the user account.
-country_code	Returns an integer country/region value for the user's preferred language.
-full_name	Returns the full name of the user.
-global_groups	Returns the global groups of which the account is a member.
-home_dir	Returns the full path to the user's home directory.
-home_dir_drive	Returns the drive letter assigned to the user's home directory.
-last_logoff	Returns the time in GMT when the user last logged off. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-last_logon	Returns the time in GMT when the user last logged in. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-local_groups	Returns the local groups of which the account is a member. This includes only groups of which the account is directly a member and does not include indirect membership through a global group which is itself a member of a local group. See get_user_local_groups_recursive for a command that will recursively include groups.
-logon_hours	Returns a bit string of 1's and 0's corresponding to each hour in the week that the user is allowed to log on. Note the week starts based on GMT time, not local time.
-logon_server	Returns the name of the server to which logon requests are sent.
-max_storage	Returns the maximum amount of disk space the user is allowed to use.
-name	Returns the name of the account.
-num_logons	Returns the number of times the user has logged on. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried (using the -system option) separately. A value of -1 indicates the number is unknown.
-parms	Returns an application specific string.
-password_age	Returns the number of seconds since the password was last changed for the account.
-password_expired	Returns a value of 1 if the account password has expired, and 0 otherwise.
-primary_group_id	Returns the the RID (relative id component of a SID) of the primary global group for the account.
-profile	Returns the full path to the user's profile.
-script_path	Returns the full path to the user's logon script.
-sid	Returns the SID of the user.
-status	Returns one of the values disabled, enabled or locked.
-units_per_week	Returns an integer indicating the number of equal time units into which a week is divided (see -logon_hours).
-usr_comment	Returns the user comment for the account.
-user_id	Returns RID component of the user's SID.
-workstations	Returns a comma-separated list of upto eight workstations from which the user can log in.

get_user_local_groups_recursive ACCOUNT ?-system SYSTEMNAME?

Returns the local groups in which the given user account is a member either directly or indirectly by belonging to a global group which is a member of a local group. This differs from the -local_groups option of the get_user_account_info command.

The option -system may be used to specify a system as described in Standard Options.

get_users ?-system SYSTEMNAME?

If no options are specified, returns the list of user accounts on the system. Note the returned list includes only accounts defined on the system, not all accounts that are known to the system.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields are shown in the table below. Note that there may be additional fields returned that are not listed below. These should be considered internal and their values not relied on.

0	name
1	comment, flags, home_dir, name, password, password_age, script_path.
2	acct_expires, auth_flags, bad_pw_count, code_page, comment, country_code, flags, full_name, home_dir, last_logoff, last_logon, logon_hours, logon_server, max_storage, name, num_logons, parms, password, password_age, script_path, units_per_week, usr_comment, workstations.
3	acct_expires, auth_flags, bad_pw_count, code_page, comment, country_code, flags, full_name, home_dir, home_dir_drive, last_logoff, last_logon, logon_hours, logon_server, max_storage, name, num_logons, parms, password, password_age, password_expired, primary_group_id, profile, script_path, units_per_week, user_id, usr_comment, workstations.

Refer to get_user_account_info for the meaning of these fields.

lookup_account_name name ?options?

name specifies the name of the account and may be fully qualified in the form domain\name.

If no options are specified, this command returns the SID for the account. If one or more options are specified, returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all	Returns all values.
-sid	Returns the SID for the account.
-domain	Returns the domain in which the account was found.
-system	Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type	Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), logonid, wellknowngroup, deletedaccount, invalid, unknown, or computer. The logonid type is returned for SID's that identify a logon session.

lookup_account_sid sid ?options?

Argument sid specifies the SID of the account. If no options are specified, this command returns the name for the account. If one or more options are specified, the command returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all	Returns all values.
-name	Returns the name for the account.
-domain	Returns the domain in which the account was found.
-system	Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type	Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), wellknowngroup, deletedaccount, invalid, unknown, or computer.

map_account_to_name ACCOUNT ?-system SYSTEMNAME?

Returns the name for an account. If ACCOUNT is a valid account name, it is returned as is. Otherwise, it is assumed to be a SID and the corresponding account name is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

map_account_to_sid ACCOUNT ?-system SYSTEMNAME?

Returns the SID corresponding to an account. If ACCOUNT is a SID, it is returned as is. Otherwise, it is assumed to be an account name and the corresponding SID is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

new_global_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?

Creates a global group GROUPNAME. The option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

new_local_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?

Creates a local group GROUPNAME. The option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

new_user USERNAME ?options?

Creates a new user account. The following options may be specified to set the account properties:

-system SYSTEMNAME	Indicates the system on which to create the account.
-comment STRING	Sets the comment associated with the account.
-home_dir PATH	Sets the account's home directory path.
-script_path PATH	Sets the path to the logon script for the account.
-password STRING	Sets the password for the account.

remove_member_from_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?

Removes the user account or global group specified by ACCOUNTNAME from the local group GROUPNAME. ACCOUNTNAME may be a domain account in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

remove_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?

Removes the privileges and account rights listed in RIGHTS from the account specified by ACCOUNTNAME. The option -system may be used to specify a system as described in Standard Options.

RIGHTS is a list of privileges and account rights. Refer to Authorization constants in the Windows SDK for valid values. Note: you must use the string form of the privilege, for example, SeBatchLogonRight, not SE_BATCH_LOGON_NAME.

remove_user_from_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?

Removes the user account specified by USERNAME from the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

set_user_account_info account ?-system SYSTEMNAME? ?options?

Sets attributes and properties of a user account. account specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed. The following options may be specified to set various properties of the account:

-comment STRING	Sets the comment associated with the account.
-full_name STRING	Sets the full name of the user.
-country_code INTEGER	Sets the country code associated with the user account.
-home_dir PATH	Sets the account's home directory path.
-home_dir_drive	Sets the account's home directory drive.
-acct_expires DATETIME	Sets the time at which the account will expire. See set_user_expiration for valid formats for DATETIME.
-name STRING	Sets the name field containing the name of the account.
-script_path PATH	Sets the path to the logon script for the account.
-profile PATH	Sets the path to the account's profile.

set_user_comment USERNAME STRING ?-system SYSTEMNAME?

Sets the comment associated with the specified user account to STRING The option -system may be used to specify a system as described in Standard Options.

set_user_country_code USERNAME INTEGER ?-system SYSTEMNAME?

Sets the country code for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_expiration USERNAME DATETIME ?-system SYSTEMNAME?

Sets the time at which the specified user account expires. DATETIME may be specified as the number of seconds since Jan 1, 1970 00:00:00 UTC, the string never, or in any format accepted by the clock scan command. This last option is only for backward compatibility and is deprecated as it may lead to ambiguity. The option -system may be used to specify a system as described in Standard Options.

set_user_full_name USERNAME STRING ?-system SYSTEMNAME?

Sets the full name for the specified user to STRING. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir USERNAME PATH ?-system SYSTEMNAME?

Sets the home directory for the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir_drive USERNAME DRIVEPATH ?-system SYSTEMNAME?

Sets the home directory drive for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_name USERNAME NEWNAME ?-system SYSTEMNAME?

Modifies the name of the specified user account to NEWNAME. The option -system may be used to specify a system as described in Standard Options.

set_user_password USERNAME PASSWORD ?-system SYSTEMNAME?

Sets the password of the specified user account to PASSWORD. The option -system may be used to specify a system as described in Standard Options.

set_user_profile USERNAME PATH ?-system SYSTEMNAME?

Sets the location of the profile of the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_script_path USERNAME PATH ?-system SYSTEMNAME?

Sets the path to the login script for the specified user account. The option -system may be used to specify a system as described in Standard Options.

unlock_user USERNAME ?-system SYSTEMNAME?

Unlocks a user account that has been locked out. The option -system may be used to specify a system as described in Standard Options.

Users and Groups

SYNOPSIS

DESCRIPTION

Standard Options

User and Group Accounts

Enumerating Accounts

Commands

COPYRIGHT

TWAPI 3.0.29 Documentation