deskcommands(X) 06 January 1993 deskcommands(X) Name deskshell commands - the commands of the Deskshell command language Description This manual page gives an alphabetical list of the Deskshell commands, built into the Desktop. The syntax and description for all commands are provided; examples are included for some commands. When applicable, returned status values are also included for the relevant commands. For information on Deskshell syntax and control constructs, see the deskshell(X) manual page or the . The two following sections contain a summary table of all commands and a table of returned status descriptions. The subsequent sections contain detailed descriptions of all Deskshell commands. Deskshell command summary All valid commands begin with a mnemonic keyword, followed in some cases by an accepted abbreviation. Some commands require an exact number of arguments; in such cases, the wrong number of arguments results in unde- fined behavior. Other commands accept any number of arguments. The following table shows which commands return a status value, take options, and return textual output (so that the result can be used in a `(...) type substitution): _________________________________________________________________________ NOTE See the following section for an explanation of the abbrevia- tions used in the table. _________________________________________________________________________ Commands summary table _________________________________________________________________________ Command Return code Options Text _________________________________________________________________________ absreadlink filename _________________________________________________________________________ actions_of rs opt _________________________________________________________________________ adw rs opt _________________________________________________________________________ basename filename _________________________________________________________________________ bring_to_front rs opt _________________________________________________________________________ canonical filename _________________________________________________________________________ cd rs _________________________________________________________________________ change_environment urs opt _________________________________________________________________________ check rs opt close_desktop rs opt _________________________________________________________________________ close_directories rs opt _________________________________________________________________________ contents_of filename _________________________________________________________________________ copy_desktop rs opt _________________________________________________________________________ copy_into rs opt _________________________________________________________________________ ddw rs opt _________________________________________________________________________ die rs opt _________________________________________________________________________ dirname filename _________________________________________________________________________ display_directory rs opt _________________________________________________________________________ do_actions_of ars opt _________________________________________________________________________ do_drop_in_actions_of ars opt _________________________________________________________________________ do_menu_actions_of ars opt _________________________________________________________________________ drop_in_actions_of rs opt _________________________________________________________________________ duplicate_file rs opt _________________________________________________________________________ duplicate_link rs opt _________________________________________________________________________ duplicate_symlink rs opt _________________________________________________________________________ dynamic_rule rs opt _________________________________________________________________________ environ _________________________________________________________________________ exit _________________________________________________________________________ extension filename _________________________________________________________________________ false rs _________________________________________________________________________ fileclass filename _________________________________________________________________________ followlink filename _________________________________________________________________________ for_info rs opt _________________________________________________________________________ get_attribute rs opt txt _________________________________________________________________________ get_out rs opt _________________________________________________________________________ get_resource txt _________________________________________________________________________ gti rs opt txt _________________________________________________________________________ help rs opt _________________________________________________________________________ join txt _________________________________________________________________________ kill _________________________________________________________________________ link_into rs opt _________________________________________________________________________ make_new_file rs opt _________________________________________________________________________ mark_changed_directory rs opt _________________________________________________________________________ menu_actions_of rs opt _________________________________________________________________________ merge txt _________________________________________________________________________ move_into rs opt open_desktop rs opt _________________________________________________________________________ pixmap_check rs opt _________________________________________________________________________ put_back rs opt _________________________________________________________________________ pwd txt _________________________________________________________________________ query all_triggers rs txt _________________________________________________________________________ query picture rs opt filename _________________________________________________________________________ query pixmap rs opt filename _________________________________________________________________________ query size rs opt filename _________________________________________________________________________ query title rs opt filename _________________________________________________________________________ rdw rs opt _________________________________________________________________________ readlink filename _________________________________________________________________________ relativepath filename _________________________________________________________________________ remove rs opt _________________________________________________________________________ remove_dynamic_rule rs opt _________________________________________________________________________ rename rs opt _________________________________________________________________________ reorganize_desktop rs opt _________________________________________________________________________ replace_environment urs opt _________________________________________________________________________ report_status rs opt _________________________________________________________________________ reset rs _________________________________________________________________________ resource_line rs _________________________________________________________________________ return _________________________________________________________________________ select rs opt _________________________________________________________________________ sequence txt _________________________________________________________________________ shell_window rs _________________________________________________________________________ show_greeting rs opt _________________________________________________________________________ sleep _________________________________________________________________________ split txt _________________________________________________________________________ symlink_into rs opt _________________________________________________________________________ test rs _________________________________________________________________________ tidy_desktop rs opt _________________________________________________________________________ true rs _________________________________________________________________________ unextended filename _________________________________________________________________________ variables txt _________________________________________________________________________ variation_class rs opt _________________________________________________________________________ yni rs opt Explanation of abbreviations rs has a status (error) value urs has a status value that is not undefined ars has a status value that is either NOTRIGGER or is the status value of the action opt has standard option (flag) processing txt returns text filename return text -- one string per argument, where each argument is a filename _________________________________________________________________________ NOTE The following option is available for all commands that take options. e Errors are not indicated to the user through dialog boxes, but only through the returned status value. _________________________________________________________________________ Deskshell status variable When a Deskshell command is executed, it generates a numerical status value between 0 and 1023. When a command is executed and generates a status, that status is con- verted to a string and stored in the variable status. When a pipeline is executed, the individual statuses are collected, and the strings all stored in the variable status, in the same order as the commands in the pipeline. _________________________________________________________________________ NOTE Certain built-in Deskshell commands and the function command do not return a status. _________________________________________________________________________ The following table gives a listing of the returned status names, values, and descriptions: Status values and explanations ___________________________________________________________ Name Value Meaning ___________________________________________________________ Success OK 0 The command com- pleted successfully. ___________________________________________________________ Interaction YES 0 The answer is Yes or return code the user pressed Yes (for yni commands). ____________ NO 1 The answer is No or the user pressed No (for yni commands). ____________ WASCLOSED 0 The window was closed (for reportstatus com- mands only). ____________ WASOPEN 1 The window was open (for reportstatus commands only). ____________ CANCELED 2 The user canceled the command. ___________________________________________________________ Specific errors ERROR 255 There was an error (not further speci- fied). ____________ NOTOPEN 1 The specified Desk- top was not open. ____________ NOTRIGGER 1 The specified file did not have an action for that trigger. ___________________________________________________________ Parsing errors NOTCOMMAND 768 The specified com- mand is unknown. ____________ BADFLAG 769 A flag word contains a character other than a dash or a known switch, key, or attribute. ____________ KEYCLASH 770 An argument had two conflicting keys. ____________ ATTRCLASH 771 An argument had two conflicting attri- butes. ____________ MISSINGARG 772 A flag word contain- ing a key or attri- bute was not fol- lowed by an argu- ment. ___________________________________________________________ Special errors MANY 780 A command returning a count produced a count of 256 or above. ____________ ARGCOUNT 781 The number of posi- tional parameters was wrong. Notation The following notation is used for describing the arguments in the com- mands that follow this section: _________________________________________________________________________ Notation Represents _________________________________________________________________________ file a filename dir an existing directory desktop a Desktop opendesktop an open Desktop visibledesktop a Desktop that is open and visible absreadlink returns the absolute pathname of a link Syntax absreadlink pathname... Description The absreadlink command returns the absolute pathname of a link. If the argument is a symbolic link, the result is the absolute pathname corre- sponding to the contents of the link (which is not the same as the canon- ical form of the contents of the link). If the argument is not a sym- bolic link, it is the canonical form of the argument. For more informa- tion, see the entry on the canonical command. actions_of [act] emulates an icon trigger Syntax actionsof trigger staticobject [dynamicobject ...] [-d dynamicdesktop] [-s staticdesktop] [-D dynamicposn] [-S staticposn] where: trigger a trigger name staticdesktop the open Desktop that the static objects are on dynamicdesktop the open Desktop that the dynamic objects are on staticposn the nominal positions of the static objects dynamicposn the nominal positions of the dynamic objects Description The actionsof command (abbreviated act) emulates an icon trigger action. You can specify either a static or dynamic trigger. This command completes as soon as the first command in the list starts executing. In each case, any commands following the actionsof command in the action list execute immediately, independent from the triggered action list. The rules are searched to locate a triggeraction clause for trigger and staticobject. The rules for a staticdesktop, if specified, will be used in the search. The rules used for determining the attributes of the dynamic objects include those for the dynamicdesktop. The following variables are set: _________________________________________________________________________ Variable Value _________________________________________________________________________ static_arg staticobject in canonical form dynamic_args dynamicobject in canonical form s_obj_type, d_obj_type the object types of the static and dynamic objects s_desktop staticdesktop, or an empty list d_desktop dynamicdesktop, or an empty list s_position staticposn, or V if not specified d_position dynamicposn, or V if not specified trigger trigger * all elements of dynamicargs Returned status [OK] if the static argument has an action for the specified trigger, or [NOTRIGGER] if not. Example If you wish to simulate the d1 (drag and drop) trigger of the Editor object from within any Deskshell script, enter the command: actionsof d1 /usr/lib/X11/XDesktop3/english.xdt /toolsheds/Accessories/Editor.obj $dynamicargs The $dynamicargs variable represents all current dynamic arguments. The above command will cause the Desktop to behave as if these dynamic argu- ments were dragged and dropped onto the Editor icon with the first mouse button. This command causes a window running the scoedit client to appear, with the dynamic arguments as the files to be edited. adw The adw command is equivalent to the displaydirectory command with no arguments. It is retained for backwards compatibility only. Syntax adw [-flags] attr See the getattribute command. basename returns the basename of its argument Syntax basename pathname... Description The basename command returns the basename of the argument. The argument is converted to canonical form. The result is the section of the path that follows the last slash. If the argument specifies the root direc- tory, the result is ``/'' (slash). bring_to_front [btf] brings a directory window to the front or back of the stack Syntax bringtofront [-flags] { [dir or visibledesktop] ... } where flags can be: f Put the directory or Desktop at the front (default). b Put the directory or Desktop at the back. Description The bringtofront command (abbreviated btf) brings the named directory windows and desktops, if open, to the front or back of the Desktop's win- dow stack. If more than one directory or Desktop is specified, they are displayed so that the first entry's window is at the extreme back or the extreme front. Returned status the number of directories and desktops specified that were not visible canonical converts its argument to canonical form Syntax canonical pathname... Description The canonical command converts its argument to the canonical or unambigu- ous form. In this process, relative pathnames are converted to absolute pathnames; redundant slashes are removed; and ``.'' (dot) and ``..'' (dot-dot) elements are eliminated, except when they follow the last slash in the argument (a trailing slash will cause them to be removed before the slash itself is). cd sets the current directory to its argument Syntax cd [dir...] Description The cd command sets the current directory of the last thread to the argu- ment. If there are no arguments, it acts is as if the arguments were the contents of the $HOME environment variable. Each argument is processed as follows until a searchable directory is located. The current directory of the thread is changed to that direc- tory, and the remaining arguments are ignored. If an argument begins with a slash, it is taken to be the name of a directory without modification. Otherwise, each string in the value of the cdpath variable is taken in order. If the first argument string con- tains a slash, then . (the current directory) is added at the front of this list. Each string in turn is joined by the argument (with an inter- vening slash) to generate a filename. Each filename is checked in turn until a searchable directory is found or the variable is exhausted. cdt See the copydesktop command. cdw See the closedirectories command. change_environment [ndt] saves the current desktop environment, and replaces it Syntax changeenvironment desktop [-d opendesktop] Description This command is equivalent to the sequence: opendesktop [opendesktop] desktop -m removedynamicrule ' ' dynamicrule ' ' -f desktop The changeenvironment command is retained for backwards compatibility only. check [chk] checks icon appearance Syntax check [-flags] [object ...] where flags can be: D Check the contents of the objects, not the objects themselves. R Put back ghosts, and do not generate new ghosts. Description The check command (abbreviated chk) checks to see if the icon appearances are updated. The rules for the named objects are checked to determine if any icon for the object should now have a different picture. If so, the picture is changed. If the R flag is specified and the object no longer exists, the icon is removed, rather than having the picture changed. If the D flag is specified, the objects must be directories or Desktops, and all the icons within these directories or Desktops are checked, rather than the named objects. If no objects are specified, this is equivalent to specifying the names of all icons in all open Desktops. Returned status [OK], or a special code close_desktop [cldt] closes specified Desktops Syntax closedesktop [-flags] [desktop ...] where flags can be: m Close the main Desktop. N Do not save the Desktop contents. Description The closedesktop command (abbreviated cldt) closes the Desktops named in the desktop argument. If no Desktops are named and the m flag is not specified, then all Desktops are closed. Returned status the number of Desktops specified that were not open close_directories [cdw] closes open directory windows Syntax closedirectories [dir ...] Description The closedirectories command (abbreviated cdw) closes the open directory windows named in dir. If no directories are specified, all open direc- tories are closed. Returned status the number of directories specified that were not open contents_of returns the contents of a directory or Desktop Syntax contentsof [directory or desktop] Description If the argument is a directory, the command returns a list of the basenames of the files in the directory other than the ``.'' (dot) and ``..'' (dot-dot) entries (but including all sub-directories and special files). If the argument is a Desktop, the command lists the full pathnames of the objects on that Desktop. Otherwise, the result is an empty list. copy_desktop [cdt] saves a specified Desktop Syntax copydesktop [file] [-d opendesktop] Description The copydesktop command (abbreviated cdt) saves the Desktop named by opendesktop and its rules into the filename specified by file (by default, the file of the same name as the Desktop). The copydesktop command is equivalent to the saveenvironment command. Returned status [OK] if the Desktop was saved successfully, [NOTOPEN] if the Desktop was open, or [ERROR] if any other error occurred copy_into [cpi] copies files into a directory Syntax copyinto dir file ... Description The copyinto command (abbreviated cpi) copies the file(s) specified in the file variables into the dir directory. If the dir directory window is open, the icons for the new files appear immediately. Files are not copied if they already exist in the directory, or if there is a file in directory with the same basename. Undefined behavior results if you specify two or more files with the same basename. Returned status the number of files not copied cpi See the copyinto command. ddw Syntax ddw dir [-flags] Description This command is equivalent to the command: displaydirectory -flags dir The ddw command is retained for backwards compatibility only. die terminates the Desktop Syntax die [-flags] where flags can be: i Terminate without prompting the user. N Do not save any open Desktops. Description The die command causes the Desktop to enter a termination state. Depend- ing on the resources and user response to prompts, this might terminate the Desktop session. Executing the die command produces the same results as selecting Exit from the Desktop File menu. Returned status [CANCELED] if the command was canceled by the user, or [ERROR] if any error occurred dirname returns the directory name of its argument Syntax dirname pathname... Description The dirname command returns the directory name of its argument. The argument is converted to canonical form, and the result is the section of the path that precedes the last slash. If the argument is root, or a file in the root directory, the result is ``/.'' (slash followed by dot). display_directory [odw] display the contents of directory windows, opening them first if neces- sary Syntax displaydirectory [-flags] [-f format] [dir [dir2]] where flags can consist of a list of letters, at most one from each of the following sets: Sort order a sort alphabetically c sort by class d sort by major class and then alphabetically s or u sort by size t sort by time of last change Display options i display icons n display names and additional information Redisplay options v redisplay only if directory has changed The format can be one of the following to determine the information dis- played for the n option: _________________________________________________________________________ Format Description _________________________________________________________________________ %B the basename of the file %C the class of the file %I the title of the object used in icon mode %P the absolute pathname of the file %R the basename of the file %S the size of the file, in bytes %T the time the file was last changed %% a percent character Whenever one of the switches a, c, d, s, t or u takes effect without a format specified in the same command, the following formats are used: _________________________________________________________________________ Flag Default format _________________________________________________________________________ a %B c %C %B d %B s %S %B t %T %B u %S %B Description The displaydirectory command (abbreviated odw) displays the contents of a directory in one of many specifiable formats. The following behaviors are available: _________________________________________________________________________ Option Description _________________________________________________________________________ No directories specified All open directory windows are modified according to flags. Any property not specified is unaffected. _________________________________________________________________________ One directory specified If no window is open for dir, a window is opened and properties set according to flags. The v flag is ignored, and unspecified sort order and display option default to a and i, respectively. If a window is open for dir, it is modi- fied according to flags, with unspecified properties unaltered. _________________________________________________________________________ Same directory is speci- If a window is open for dir, it is modi- fied twice fied according to flags, with unspecified properties unaltered. _________________________________________________________________________ Two different direc- If a window is open for dir, it is changed tories specified to show dir2 (flags as for one directory). Any existing window for dir2 is closed. Returned status [OK] if the command is successful, or [ERROR] if any error occurred do_actions_of [do_act] synchronous version of the actionsof command. The actions are executed in the same thread; a child process will not begin executing until the parent has finished. Conversely, in the asyn- chronous version of this command, child and parent processes execute simultaneously. do_drop_in_actions_of [do_drp] synchronous version of the dropinactionsof command. The actions are executed in the same thread; a child process will not begin executing until the parent has finished. Conversely, in the asyn- chronous version of this command, child and parent processes execute simultaneously. do_menu_actions_of [do_menu] synchronous version of the menuactionsof command. The actions are executed in the same thread; a child process will not begin executing until the parent has finished. Conversely, in the asyn- chronous version of this command, child and parent processes execute simultaneously. drop_in_actions_of [drp] emulates a drag and drop trigger on a directory or Desktop The command is identical to the actionsof command, but it searches for a dropinaction rule clause in the specified rule files. duplicate_file [dup] duplicates the file Syntax duplicatefile file [-b basename] Description The duplicatefile command (abbreviated dup) creates a file that is identical to file. It prompts the user to name the new file or optionally specify its basename in basename (any leading directory is stripped). The specified file is duplicated (by copying) in the same directory. If basename is not specified, that directory must be open. In addition, an interactive prompt is invoked to generate the name for the duplicate file. The file specified must be a regular file in the open directory. If you specify no file, specify more than one file, or specify a file that is not valid, the Desktop issues a warning to the user and the command is ignored. Returned status [OK] if the command is successful, [CANCELED] if it was canceled by the user, or [ERROR] if any error occurred duplicate_link [dupl] gives a second link to a file Syntax duplicatelink file [-b basename] Description The duplicatelink command (abbreviated dupl) gives a second link to a file and prompts the user to name the new link name or optionally specify it in basename (any leading directory is stripped). The file argument must not be a directory. Unless exactly one argument is specified, the Desktop will warn the user, and the command will be ignored. The specified file is given a second link in the same directory. If basename is not specified, that directory must be open. In addition, an interactive prompt is invoked to generate the name for the new link. Returned status [OK] if the command is successful, [CANCELED] if it was canceled by the user, or [ERROR] if any error occurred duplicate_symlink [dupsl] Creates a symbolic link to a file. Syntax duplicatelink [-flags] file [-b basename] where flags can be the following: r create a relative link Description The duplicatesymlink command (abbreviated dupsl) creates a symbolic link to a file and prompts the user to name the new link name or optionally specify it in basename (any leading directory is stripped). Unless exactly one argument is specified, the Desktop warns the user, and the command is ignored. A symbolic link to the specified file is created in the same directory. If basename is not specified, that directory must be open. In addition, an interactive prompt is invoked to generate the name for the symbolic link. By default, the link will contain an absolute name. The r flag causes it to contain a relative name that is just a basename. Returned status [OK] if the command is successful, [CANCELED] if it was canceled by the user, or [ERROR] if any error occurred dynamic_rule [idr] installs a dynamic rule Syntax dynamicrule [-flags] [-A after] [-B before] name word ... where flags can be: f The words are filenames. t brings together all rules with this name a place after the last rule with the name name b place before the first rule with the name name F place at the front of all other rules and where: name names the dynamic rule after specify the names of rules after which the rule is placed before specify the names of rules before which the rule is placed Description The dynamicrule (abbreviated idr) command installs a dynamic rule, optionally reading it from a specified file and placing it in a specified position within the dynamic rule hierarchy. The remaining arguments (if the f flag is specified, then the contents of the files named by the remaining arguments) are catenated together, separated by single spaces. The resulting string is installed as a new dynamic rule, with the given name. Its position is determined by flags and the after and before options (the default is after all other rules). For more information on creating and using dynamic rules, see the . Returned status [OK] if the command is successful, or [ERROR] if a parsing error occurs. If a parsing error occurs, it is undefined how much of the rule has been installed. If a rule of the given name already exists, then both rules will have the same name. environ [env] modifies Desktop environment variables Syntax environ [name value] Description The environ command (abbreviated env) modifies Desktop environment vari- ables. The named Desktop global variable, specified in name, is set to the single string value specified in value. Returned status [OK] if the command is successful, or [ERROR] if any error occurred exit terminates a script Syntax exit [status...] Description If there are any arguments, the variable status is set to the arguments. The thread then terminates. Returned status any arguments specified extension returns the extension of its argument Syntax extension pathname... Description The extension command returns the extension, if any, of its argument. The basename of the argument (converted to canonical form) is taken, after which any leading sequence of dots is removed. If the remaining name (which may now be null) contains a dot, the result is the part com- mencing with the last dot. Otherwise, it is the null string. Example The command: extension /usr/roms/code.bin returns .bin false returns the value false Syntax false Description The false command serves as the constant 1, and actually has no effect. It can be used in various Deskshell constructs and comparisons. Returned status [NO] fileclass returns the class of its argument Syntax fileclass pathname... Description The fileclass command returns the class of the argument, in canonical form. Example The command: fileclass $HOME returns a string value that matches the canonical fileclass of the user's home directory. The value returned is DNWM+0. The D indicates that the object is a directory. The N indicates that the object is not executable by any user. The W indicates that the object is both readable and writeable by the user. The M indicates that the object is owned by the user. The ``+'' indicates that the object is not a sym- bolic link. The 0 indicates that the object's variation class is 0 (the default variation class for all objects). followlink returns the absolute pathname of the final destination of a link Syntax followlink file Description The followlink command returns the absolute pathname of the final desti- nation of the link. If the argument is a symbolic link, the result is the canonical form of the file to which the link finally points (this is done by repeatedly applying the absreadlink command until the result con- verges). If the argument is not a symbolic link, it is the canonical form of the argument. Example Assume the following is true: + The directory /usr/michaelk is a symbolic link to the directory /usr/benh. + The directory /usr/benh is a symbolic link to the directory /usr/ravis. + The directory /usr/ravis is not a symbolic link. The command: followlink /usr/michaelk will yield a result of /usr/ravis. The above command finds that the destination of /usr/michaelk is /usr/benh and that /usr/benh has a destination of /usr/ravis. Since /usr/ravis leads to nowhere, it is the final destination and therefore, the result. for_info [fyi] displays an information window Syntax forinfo [-p picture] [-t title] [-b book] [-h help] text where: picture specifies a picture file to use for a general picture title specifies text to put in the title bar book specifies the help book to be used by the help button help specifies the help topic to be used by the help button text text displayed in a window Description The forinfo command (abbreviated fyi) displays an information window on the Desktop for the user. If a help facility is provided in the window, this causes the command: help topic [-b book] to be performed, with the default topic being FyiUserHelp. Returned status [OK] if the command is success, or [ERROR] if any error occurred get_attribute [attr] gets attribute values Syntax getattribute [-flags] name object where flags is one of: d Use the rules of this Desktop. D Use the rules of this directory. Description The getattribute command (abbreviated attr) gets values. The rules are searched for an attribute clause with the given name for each specified object in turn. The result is a list containing the body of the clauses for those objects that have an attribute of that name. Returned status the number of objects which do not have an attribute of that name Example For example, if various files are given different attributes for the printer depending on what kind of file they are, a specific file's attribute can be queried with following command: getattribute -D printer /usr/bobk/map.ps If somewhere in the directory's rules, the following clause for the /usr/bobk/map.psobject is found: attribute: printer = postscript; the above command returns the string postscript. get_out [goi] adds specified objects to the Desktop Syntax getout object ... [-a position or -l] [-f desktop] [-d opendesktop] where: desktop the Desktop to remove icons from (no default) opendesktop the Desktop to place icons into (default is initial Desktop) position can be one of the following: Px,y position in an exact number of pixels Gx,y position in the standard tidying grid F first free position on the grid where x and y are integers. Description The getout command (abbreviated goi) adds specified objects to a speci- fied Desktop. position specifies the position of the first object, or -l indicates that no position is given. Subsequent objects are given the position code V so that their position is determined by the Desktop. Alternatively, a position can be specified for each object with the syn- tax: getout [object position ... [-f desktop] [-d opendesktop] where position specifies the position for the corresponding object. A position can be omitted if the next object is preceded by -@ or -!, to identify it as an object, in which case the position code defaults to V. Returned status [OK] if the command is successful, or [ERROR] if any error occurred get_resource gets resource values Syntax getresource name class Description The getresource command gets resource values. Both the name and the class must have the same number of elements, separated by single dots. The name/class pair is looked up in the Desktop's resource database. If it is found, the result is the single string consisting of the resource value; otherwise, it is an empty list. Example The command: iconsize=`( getresource xdt3.icon.size XDesktop3.Icon.Size ) sets the variable iconsize to the string value returned by the command getresource xdt3.icon.size XDesktop3.Icon.Size. If this resource has not been changed, the returned string is 32 if the screen is less than 800 pixels or 64 if the screen is greater than 800 pixels. If the xdt3.icon.size resource was altered, the returned string should correspond to the new value. goi see the getout command gti displays a prompt and reads user input Syntax gti [-p pic] [-t title] [-d default] [-l length] [-b book] [-h help] [text] where: pic specifies the picture file to use for a general picture title specifies text to be put in the title bar default specifies the default text to put in the input area length specifies the length of the input area book specify the help book used by the help button help specify the help topic used by the help button Description The gti command displays a prompt and obtains user input. The text and input are displayed in the window. The resulting input is output as a single string. If a help facility is provided in the window, it causes the following command to execute: help topic [-b book] where topic defaults to GtiUserHelp. Returned status [OK] if the command is successful, [CANCELED] if it was canceled by the user, or [ERROR] if any error occurred help request help Syntax help topic [-b book] where: book the help book to be used Description The help command invokes the help service. book defaults to Xdesktop. The topic and book are passed to the help system. Returned status [OK] if the command is successful, or [ERROR] if any error occurred idr see the dynamicrule command in_text_window [text] see the shellwindow command irl see the resourceline command join joins its arguments into one string Syntax join string ... Description The join command joins its arguments into one string. The arguments are catenated, separated by the value of the first string in the variable ofs or by a single space if this variable holds no strings. The final result is always a single string. kill sends a signal to specified threads or processes Syntax kill [-signal] [thread or processid ...] where: thread specifies the name of a thread processid the number of one or more processes signal one of the following optional signal names: sigint (default) sighup sigkill sigquit sigterm sigusr1 sigusr2 Description The kill command sends a signal to a thread or process. The corresponding signal is sent to each of the indicated processes and threads. link_into [lni] links file into a directory Syntax linkinto dir file ... Description The linkinto command (abbreviated lni) links the files specified by file into the specified dir directory. Files are not linked if: + they are already in the specified directory + there exists a file in the directory with the same basename + the directory and file are on different filesystems Undefined behavior results if two or more files with the same basename are specified. Returned status the number of files not linked make_new_file [mkf] creates a new file or directory Syntax makenewfile [-flags] dir [-b basename] where flags can be: f Create an empty file (default). d Create a new directory. Description The makenewfile command (abbreviated mkf) creates a new file or direc- tory. It then prompts the user for a name if the optional basename argu- ment (any leading directory is stripped) is not included. A new directory or empty file is created in the named directory. If basename is not specified, the directory must be open. In addition, an interactive prompt is then invoked to generate the name for the new file or directory. Returned status [OK] if the command is successful, [CANCELED] if it was canceled by the user, or [ERROR] if any error occurred mark_changed_directory [mcd] marks a directory window if the contents have changed Syntax markchangeddirectory [dir ...] Description The markchangeddirectory command (abbreviated mcd) marks with a button any of the named directories specified in dir (all open directories by default) that have changed. Clicking on the button redisplays the direc- tory and removes the mark. Returned status the number of directory names that were not open menu_actions_of [menu] executes a command from a menu Syntax menuactionsof menu item [-d desktop [-D directory] where: item specifies the item name, or a numeric position desktop specifies a Desktop whose rules are to be used in locating the menu directory specifies a directory whose rules are to be used in locating the menu Description The menuactionsof command (abbreviated menu) executes a command from a menu. The following variables are set: _________________________________________________________________________ Variable Value _________________________________________________________________________ static_arg directory, or an empty list dynamic_args the objects, with filenames in canonical form * elements of dynamicargs d_obj_types the type of each object in dynamicargs d_desktop desktop, or an empty list Returned status [OK] if the static argument has an action for that trigger, or [NOTRIGGER] if not merge returns the contents of each of its arguments, merged Syntax merge name ... Description The merge command returns the contents of each of its arguments, merged. Each argument is taken to be the name of a variable. The result is the first string in each variable, in the order they are named in the argu- ments, followed by the second string in each variable, and so on until all the variables are exhausted. Each argument is ignored once the end of the contents of the corre- sponding variable are reached. mkf see the makenewfile command move_into [mvi] moves files into a directory Syntax moveinto dir file... Description The moveinto command (abbreviated mvi) moves the file(s) named in the file variables to the directory dir. If the directory window is open, new icons appear in the window. If icons for the specified files are visible in a different directory window before you move the files, the icons disappear from that window when you issue the command. If the icons for the specified files are on the Desktop, their titles change to reflect any filename changes. Files are not moved if they are already in the directory specified in dir, or if there is a file in dir with the same basename as the specified files. Files cannot be moved if the directory and the file are on dif- ferent filesystems. If you try to move files into a directory on a different filesystem, or if you specify two or more files with the same basename, the behavior is undefined. Returned status the number of files not moved ndt see the changeenvironment command odt see the opendesktop command odw see the displaydirectory command open_desktop [odt] opens specified Desktops Syntax opendesktop [-flags] [-f format] [desktop [desktop2]] where flags can be: h hide the window of the Desktop i display icons n display names and formatted information m make desktop or desktop2 the main Desktop (see below) r reread the contents of the Desktop(s), without first saving them N do not save contents of desktop (2 arguments only) and format determines the format of the information displayed for the n option, as follows: %B basename of the object %C class of the object %I title of the object that would be used in icon mode %P absolute pathname of the object %R name of the object relative to the user's $HOME directory %S size of file, in bytes %T time the file was last changed %% a percent character Whenever the n switch is specified without a format, the format %R is used. Description The opendesktop command (abbreviated odt) opens the named Desktops with a specifiable formatting. The following behaviors are available: _________________________________________________________________________ Option Description _________________________________________________________________________ No Desktops specified The h, m, and N flags are ignored. If the r flag is specified, all open Desktop windows are reloaded from their rule files, losing the current contents and rules. If the i and n flags and the -f format are specified, all Desktops are redisplayed in this format. _________________________________________________________________________ One Desktop specified If no window is open for it, a window is opened for it, and the r flag is ignored. If a window is open for it, the r flag causes it to be reloaded from its rule file, losing the current contents and rules. In either case, the m flag causes it to become the main Desktop. The h flag causes the window to be hidden (otherwise it is visible to the user). The N flag is ignored. If the i and n flags and the -f format are specified, this Desktop is redisplayed in this format. _________________________________________________________________________ Two Desktops specified If no window is open for desk- top, this command has no effect. If the same Desktop is speci- fied for desktop and desktop2 and it is open, the effect is the same as if it were speci- fied only once. Otherwise, any existing window for desktop2 is closed. Its contents are displayed in the window for desktop. The m switch causes desktop2 to become the main Desktop. The h switch causes the window to be hidden (otherwise it will be visible to the user). The N switch means that the contents of desktop will not be saved (by default, they are). The r switch means the desktop2 will be reloaded from its rule file, losing the current contents and rules. If the i and n flags and the -f format are specified, the Desktop is redisplayed in this format. Returned status [OK] if the command is successful, or [ERROR] if any error occurred pbi see the putback command pixmap_check [pxc] checks specified pictures to see if they have changed Syntax pixmapcheck [picture ...] Description The pixmapcheck command (abbreviated pxc) checks specified pictures to see if they have changed. If the named pictures have changed, the infor- mation about them is updated. All affected icons have the pictures changed. If no arguments are specified, it is equivalent to specifying all pic- tures used so far. With the present picture mechanism, a picture has changed if: + the search mechanism would yield a different picture file + the mechanism would yield the same picture file, but the contents of that file have changed Returned status the number of pictures not used to date by the Desktop put_back [pbi] puts back icons Syntax putback object ... [-d opendesktop] Description The putback command (abbreviated pbi) removes the files named in object from the Desktop specified by opendesktop. This command affects neither icons that are locked on the Desktop nor their underlying files. Returned status the number of icons that are locked or not on the specified Desktop pwd returns the current directory Syntax pwd Description The pwd command returns the current directory of the thread in canonical form as a list of one string. pxc see the pixmapcheck command query all_triggers returns a list containing one string for each trigger available Syntax query alltriggers Description The query alltriggers command returns a list containing one string for each available trigger. Returned status [OK], or a special code query picture returns a list of the pictures used for specified objects Syntax query picture [-d desktop] object... Description The query picture command returns a list of the pictures used for speci- fied objects. desktop uses the rules of the specified Desktop. Returned status [OK], or a special code query pixmap returns a list of the pixmaps used for specified objects, with one string for each argument Syntax query pixmap [-d desktop] object... Description The format of each returned string is: A P<pixmapid>C<colormapid> W<width>H<height> The pixmapid and colormapid are in hexadecimal, and the width and height in decimal. desktop uses the rules of the specified Desktop. Returned status [OK], or a special code query size returns a list of the sizes of specified objects, in bytes, if the objects are directories or files Syntax query size [-d desktop] object... Description The query size command returns a list of the sizes of specified objects, in bytes, if the objects are directories or files. desktop uses the rules of the specified Desktop. If the object is a special file, the corresponding string is an empty string. Returned status [OK], or a special code query title returns a list of the titles of specified objects Syntax query title [-d desktop] object... Description The query title command returns a list of the titles of specified objects. desktop uses the rules of the specified Desktop. Returned status [OK], or a special code rdr see the removedynamicrule command rdt see the replaceenvironment command rdw Syntax rdw dir dir2 [-flags] Description This command is equivalent to the command: odw -flags dir dir2 The rdw command is retained for backwards compatibility only. readlink returns the contents of a link Syntax readlink pathname... Description The readlink command returns the contents of a link. If the argument is a symbolic link, the result is the uninterpreted contents of the link. Otherwise, it is the canonical form of the argument. relativepath returns the pathname relative to the user's home directory Syntax relativepath pathname... Description The relativepath returns the pathname relative to the user's home direc- tory. The argument is first converted to canonical form. If the result commences with the value of the HOME environment variable, that string is stripped off to find the result. Otherwise, the result is the canonical form of the argument. remove [rmi] removes files Syntax remove file... Description The remove command (abbreviated rmi) deletes the files named in the file argument from the filesystem and removes the corresponding icon(s) from the Desktop. Directories cannot be removed with this command. Returned status the number of files not removed remove_dynamic_rule [rdr] removes a dynamic rule Syntax removedynamicrule name ... Description The removedynamicrule command (abbreviated rdr) removes all dynamic rules identified by the name argument. Returned status the number of names that have no dynamic rules associated with them rename renames a file Syntax rename file [-b basename] [-d visibledesktop] Description The rename command renames a file specified by file. The basename of the specified file is changed. basename is the new basename for the file (any leading directory is stripped). If basename is not specified, an interactive prompt is invoked to generate the new name for the file. In this case, the icon used will be in the specified Desktop. If no Desktop is specified, it will be in the directory of the file (which must be open). Returned status [OK] if the command is successful, [CANCELED] if it was canceled by the user, or [ERROR] if any error occurred reorganize_desktop [tds] reorganizes specified Desktops Syntax reorganizedesktop [desktop ...] Description The reorganizedesktop command (abbreviated tds) moves each icon on the Desktop to a unique grid position so that the earliest grid positions are filled. reorganizedesktop is also recognized. Using the reorganizedesktop command produces the same results as putting back all of the icons with the putback command and then getting them all out with the getout command using the -F position code. Returned status the number of Desktops named that were not open replace_environment [rdt] Syntax replaceenvironment desktop [-d opendesktop] Description This command is equivalent to the sequence: opendesktop [opendesktop] desktop -d -n removedynamicrule null -string dynamicrule null -string -f desktop The replaceenvironment command (abbreviated rdt) is retained for back- ward compatibility only. report_status [report] displays a status report window Syntax report [-flags] [-p pic] [-t title] [-c canceltext or -C cancelpic] [-b book] [-h help] [text] where flags can be: a The window closes automatically at the end of the thread. and where: pic specifies the picture file to use for a general pictures title specifies text to put in the title bar canceltext specifies text for the cancel button cancelpic specifies the picture for the cancel button book specify the help book to be used by the help button help specify the help topic to be used by the help button Description The reportstatus command (abbreviated report) displays a status report window. This command is special because repeated use in a single Deskshell thread is different from use in several threads. This description applies to a single thread -- use of this command in one thread cannot affect its use in other threads. Each Deskshell thread has a single report window, which may be closed, open, or canceled. When a thread is created, the window is initially closed. It is opened and closed by this command, and canceled by the user pressing the cancel button (the window disappears when it is can- celed). The effect of the command depends both on the state of the win- dow and on whether a text argument is provided, as shown in the following table: _____________________________________________________________ Text provided Window state Effect _____________________________________________________________ no any The window is closed. yes closed The window is opened, with the text and pictures specified by the arguments. yes opened The text and picture in the window are changed to those specified by the arguments. yes canceled The window is closed. If the thread terminates while the window is still open, it remains there until canceled by the user. However, if the last use of the command in the thread specified the a flag, the window closes automatically when the thread terminates (this flag is set or reset on each use of the command). If a help facility is provided in the window, it causes the command: help topic [-b book] to be performed, with the default topic being ReportUserHelp. Returned value [WASCLOSED] if the window was previously closed, [WASOPEN] if the window was previously open, [CANCELED] if the window was previously canceled, or [ERROR] if any error occurs reset resets Desktop Syntax reset Description The reset command causes the Desktop to fully reset itself. Returned status [OK] if the command is successful, or [ERROR] if any error occurred resource_line [irl] modifies the Desktop resources Syntax resourceline string ... Description The resourceline command (abbreviated irl) modifies the Desktop resources. The arguments are catenated together and separated by single spaces. The resulting string is added to the resource database used by the Desktop. If a parsing error occurs, it is undefined whether the line has been installed. Returned status [OK] if the command is successful, and [ERROR] if any error occurred return returns from a function Syntax return Description The return command returns from a function. The currently executing function, if any, is exited as if control had reached its end. If no functions are currently executing, the effect is the same as the exit command. rgw see the showgreeting command rmi see the remove command save_environment see the copydesktop command select [sel] selects or unselects specified objects Syntax select [-flags] [objects ...] where flags can be: s select, canceling all existing selections (default) a add to selection list t toggle selection state u unselect Only one of the above can occur. A add all icons in all open Desktops to the selection list D add all the icons within the named objects U cancel all existing selections Description The select command (abbreviated sel) selects or unselects specified objects. The selection state for the icons for the named objects is altered according to the flags. If the D flag is specified, the objects must be directories or Desktops, and all the icons within the directory or Desktop are added to the selec- tion list. This flag may not occur together with any of the a, s, t or u flags. The U flag applies before any other change, and the A flag after any other change. However, an icon will not be selected, if it is on neither an open Desk- top nor an open directory window. If an icon is removed from a desktop, or a desktop or directory window is closed, all icons no longer fitting this description are unselected. Returned status the number of objects named that are not visible (or open for the D flag) sequence returns a sequence of numbers specified by the arguments Syntax sequence first [step] [-flag] limit or: sequence [-flags] [limit] where flags can be: > increments the sequence according to the step argument * limits the elements of the list Description The sequence command returns a sequence of numbers generated by the argu- ments. The result is a list of numbers (converted to strings). The first number (first), and the subsequent numbers differ by the value specified in step if flags is > or if flags is omitted. All elements of the list are less than (greater if step is negative) or equal to limit. If flags is *, the list contains exactly limit elements. It is possible for the list to contain no elements. Example The command: for x in '(sequence 1 1 $#dynamicargs) will execute the for loop for each value returned in the list generated by the command sequence 1 1 $#dynamicargs. The first 1 in the above command indicates that the list should start with 1. The second 1 in the above command indicates the number to incre- ment the list by. The final number, $#dynamicargs, indicates what value the list should end at. For example, if the $#dynamicargs variable (the number of dynamic argu- ments), is 3, the list generated by the command is (1 2 3). There will be 3 for loops executed, the first looping only once, the second twice, and the third will loop three times. set_global see the environ command shell_window [sh] [shell] executes a shell in a window Syntax shellwindow [-n name] [command [args ...]] Description The shellwindow command (abbreviated sh or shell) opens a new system shell window. If command is specified, then it is executed in a text window. Otherwise, an interactive shell, specified by a resource, is used. The first parameter word must be either the string -n followed by name (the name of the window) or the actual command. In the former case, the subsequent parameter words are the command. Returned status [OK] if the command is successful, or [ERROR] if any error occurred shf see the shuffle command show_greeting [rgw] redisplays the Desktop greeting Syntax showgreeting Description The showgreeting command (abbreviated rgw) redisplays the Desktop greet- ing window. This box is not automatically displayed on startup. Returned status [OK], or a special code sleep delays the next command Syntax sleep seconds [milliseconds] Description The sleep command delays the next command. The two durations are added (the millisecond value may be greater than 999), and the current thread is suspended for that length of time (plus any additional time before it is rescheduled). sli see the symlinkinto command split splits its argument into separate strings Syntax split string ... Description The split command splits its argument into separate strings. Each argu- ment is split at those characters that occur in the value of the first string in the variable ifs. (If this variable holds no strings, each argument is split at the three white space characters.) If the first string is `` '' (a space), it splits after every character. All empty strings are discarded, resulting in a list of the remaining strings. symlink_into [sli] symbolically links files into a directory Syntax symlinkinto dir file ... Description The symlinkinto command (abbreviated sli) symbolically links files specified in file into a directory specified by dir. The new symbolic links contain the exact file argument specified, without conversion to an absolute or relative pathname. The named files are sym- bolically linked into the named directory. Files are not linked if they are already in that directory, or if there exists a file in the directory with the same basename. Undefined behavior can result if two or more files with the same basename are specified. Returned status the number of files not linked tdg see the tidydesktop command tds see the reorganizedesktop command test tests an expression to generate a returned status value Syntax test predicate or: [ predicate ] Description The test command, depending on the predicate, tests an expression to gen- erate a returned status value. predicate can be any of the following: _________________________________________________________________________ Predicate Description _________________________________________________________________________ -eq number1 number2 Is number1 equal to number2? -ne number1 number2 Is number1 not equal to number2? -lt number1 number2 Is number1 less than number2? -le number1 number2 Is number1 less than or equal to number2? -gt number1 number2 Is number1 greater than number2? -ge number1 number2 Is number1 greater than or equal to number2? = string1 string2 Is string1 equal to string2? == string1 string2 Is string1 equal to string2? != string1 string2 Is string1 not equal to string2? -same name1 name2 Does variable name1 have exactly the same contents as variable name2? ! predicate Is predicate false? Returned status [YES] if the predicate is true, or [NO] if it is false text see the shellwindow command tidy_desktop [tdg] tidies icons on specified Desktops Syntax tidydesktop [desktop ...] Description The tidydesktop command (abbreviated tdg) moves each icon to the closest unique, visible grid position. Each icon in the named Desktops (or all open Desktops if none is speci- fied) is moved to the closest, unique, visible grid position. true returns the value true Syntax true Description The true command serves as the constant 0, and actually has no effect. It can be used in various Deskshell constructs and comparisons. Returned status [YES] unextended removes the extension of its argument Syntax unextended pathname ... Description The unextended command removes the extension, if any, of its argument. The argument is converted to canonical form, and its extension, if any, is then removed. Example The command: unextended /usr/michaelh/code.bin returns /usr/michaelh/code variables returns the contents of each of its arguments Syntax variables name ... Description The variables command returns the contents of each of its arguments (assumed to be variables). The result is the strings in the variables, in the order they are named in the arguments. variation_class [vclass] changes the variation class Syntax variationclass class object ... Description The variationclass command (abbreviated vclass) changes the variation class of an object. The variation class is used to record the state of an object. The variation class of the named objects will be changed to class, which must be a single digit. The icons for these objects will not be automat- ically updated. When the Desktop starts, all files and directories are given a variation class of 0. Returned status [OK], or a special code Example For example, the Trash directory can be given a variation class of 0 to indicate that it is empty or 1 to indicate that there is something in it. The variation class can then be read to determine which icon to display for the Trash (an empty trashcan or one with something sticking out of it). So, the command: variationclass 1 $HOME/trash sets the variation class for the user's trash directory to 1 to indicate that it is not empty, and the command: variationclass 0 $HOME/trash sets the variation class for the user's trash directory to 0 to indicate that it is empty again. vclass see the variationclass command xdtwait waits for the Return or Enter key Syntax xdtwait Description The xdtwait command waits for the Return or Enter key to be pressed before continuing with the Deskshell script. xdtwait is often inserted just before the end of a script so that the user can see what the script has done before it exits and closes any win- dows; the windows will not close until a Return or Enter has been pressed. yni displays a yes/no dialog Syntax yni [-p pic] [-t title] [-y texty or -Y picy] [-n textn or -N picn] [-b book] [-h help] [text] where: pic specifies the picture file to use for a general picture title specifies text to put in the title bar picy specify the pictures for the yes button picn specify the pictures for the no button texty specify the text for the yes button textn specify the text for the no button book specify the help book used by the help button help specify the help topic used by the help button Description The yni command displays a yes/no dialog where two buttons and the text are displayed in a window. If a help facility is provided in the window, this causes the command: help topic [-b book] to be performed, with the default topic being YniUserHelp. Returned status [YES] if the Yes button is pressed, [NO] if the No button is pressed, or [ERROR] if any error occurred See also deskshell(X), xdt3(X), tellxdt3(X)