FileRunner ---------- (C) 1996-1998 Henrik Harmsen Table of contents ----------------------------------------------------------------------------- 1 Concepts And Basic Usage 2 The Main FileRunner Window - A Quick Tour 3 Reference 3.1 The Main Menu 3.2 The Status Line 3.3 The Directory Panels 3.3.1 The Directory Panel Menus 3.3.2 The Directory Panel Buttons 3.3.3 The Directory Entry 3.3.4 The File List 3.3.4.1 Mouse Buttons In The File List 3.3.4.2 Keyboard Support In The File List 3.4 The Command Button List 3.4.1 Synchronous vs. Asynchronous Command Execution 3.5 Command Line Arguments 4 The Classing Engine 5 The Internal Text Viewer And Editor 5.1 The Internal Text Viewer Menu 5.2 The Internal Text Editor Menu 6 Configuration 7 Home-made Buttons 8 FTP (File Transfer Protocol) 8.1 Anonymous FTP 8.2 FTP Through Proxy 8.3 Synchronous Or Asynchronous FTP Transfers 8.4 FTP Timeout 8.5 Closing FTP Connections 8.6 FTP Transfer Status 8.7 Temporary Storage For FTP Files 8.8 Using The Rule-based Configuration For FTP Logins 8.9 Batch FTP 8.10 FTP Transfer Speed (dropped characters with a buffered serial port??) 9 The Internal Shell Windows 10 Miscellaneous 10.1 Exported Selections 10.2 Files Used and Created By FileRunner 10.3 Choosing cursor color 10.4 HTTP download 11 Copying/Copyrights/Legal Stuff 12 Send Me A Postcard! 13 Bug Reports/Questions 14 Contacting The Author / The Announcement Mailing List 1. Concepts And Basic Usage ============================================================================= In the FileRunner window there are two file listing panels, side by side. They are equivalent in function, but one will act as "source" panel and the other "destination". To make one panel "source" panel, you just select files in a panel and that panel becomes "source". The opposite panel becomes "destination". The source and destination panels are then used in the commands. To copy a few files or directories, just select the files and directories in the left or the right panel and press the Copy button, the files/directories will then be copied into the opposite panel. Selecting files/directories is done by holding the left mouse button down on a file and drag the mouse to select a range of files. You can do an extended select by using the Ctrl-button + left mouse button. This will let you select more than just a range of consecutive files. Try it and you will see how it works. So, the left mouse button is a select-button and will also activate buttons and menus. The right mouse button is a "view" button. Press it over a directory and you will enter that directory. Press it over a text file and a text viewer will pop up. Press it over any file and FileRunner will try to guess what kind of file it is and view it some way or another. Double-clicking the left mouse-button will do the same thing as using the right mouse button. 2. The Main FileRunner Window - A Quick Tour ============================================================================= At the top, there is a menu (File, Configuration, Utilities and Help) that holds the main FileRunner menu. 'nuff said. Below the top menu, there is a status line that will show messages generated by the program. Most of these messages go into a log that can be viewed and saved later (File->View Log). Below the status line to the left and right are the directory panels, and in the middle are the command buttons. The directory panels contain buttons and menus that act on the directory list shown in that panel. More about this in the reference chapter below. 3. Reference ============================================================================= Here is the full reference to all commands and buttons and tricks you can do in FileRunner. 3.1 The Main Menu ============================================================================= File->About About FileRunner. File->View Log View the log that FileRunner keeps of everything that has been done. Most (important) messages to the status line end up in the log also. The log can be saved if you press the right mouse button in the viewer and select "Save As...". File->Quit Quit (will save the history to disk first). Configuration->Save Configuration Your configuration and preferences are saved in a file called "$HOME/.fr/config" (The .fr directory is created at first start automatically). This file is read every time FileRunner starts up. The config file is auto-generated when saved like this, so this operation will erase any edits you have done to the file. This is an operation you will want to do when you add stuff to the hotlist so it will be saved for next time, and also in the other cases when changes in the FileRunner menus affect the configuration file. Warning: If you have more than one FileRunner running and use both to save configuration they will overwrite each others configuration. Also note that per default, FileRunner will save its configuration upon exit (unless you set the configuration option config(save_conf_at_exit) to zero). Another good time to save your configuration like this is when you get a new version of FileRunner, so the config file will show the correct setting variables available for that version. Configuration->Edit Configuration This will launch a configuration browser. Click on the options in the left list to quickly jump to an option and edit the option in the text field to the right. When done, press OK. Configuration->Reread Configuration The config file ($HOME/.fr/config) is re-read. This can be used if you edit the config file with an external editor and you want the configuration to be read back into FileRunner. Configuration->Show All Files Determines whether files beginning with a dot (.) should be shown or not in the file lists. Configuration->Create Relative Links If set, the S-Link and S-LnAs buttons will create relative soft links. Otherwise, they create absolute soft links. Configuration->Run Pwd After CD If set, FileRunner will run "pwd" after cd'ing to a new directory to check where it ended up. Otherwise, it will not do this, but instead infer the new path from the old path. This makes a difference when cd'ing to a link that points to a directory. Configuration->Run Pwd After CD (FTP) Same as previous setting above, only that it affects FTP listings. Setting this to off will also yield slightly faster directory traversing in FTP. Configuration->Anonymous FTP Determines whether FTP connections should be done anonymously, i.e using "anonymous" as user login and your email address as password. If you turn this off, you will be asked for username and password whenever a new FTP link is set up. Configuration->Use FTP Proxy Determines whether the FTP proxy should be used when doing FTP. See more in the FTP chapter about this. Configuration->Sort ***** Determines which way the file lists will be sorted. Try it out and you will see how it works. Configuration->Edit xxx color Change various GUI colors. You have to save your configuration if you want them to survive to the next time you run FileRunner. These configuration (with their documentation) are in the configuration file also. Configuration->Edit xxx font Change various GUI fonts. You have to save your configuration if you want them to survive to the next time you run FileRunner. These configuration (with their documentation) are in the configuration file also. Configuration->Set Left Start Dir Configuration->Set Right Start Dir When you issue one of these commands for the left and right file list panels, respectively, you change the config(startpwd,[left,right]) variables so that the next time you start FileRunner it will start at that directory position. You have to save your configuration to store it to the config file. Another way of doing this is to edit the configuration file with Configuration->Edit Configuration and change those two variables. Configuration->Set Window Pos/Size When you issue this command, you change the config(geometry,main) variable so that the next time you start FileRunner it will start with the current size. You have to save your configuration to store it to the config file. Another way of doing this is to edit the configuration file with Configuration->Edit Configuration and change the config(geometry,main) variable. Utilities->Swap Windows Swap the current directories between the two file list panels. Utilities->View As Text View selected files as text files. This comes in handy when the file classification rules don't work. Like for example when you have a text file called foo.gif, FileRunner will think this is an image and launch the image viewer if you just right-mouse-button click on it. Utilities->What Is?... Select a file and choose this command to use the Unix "file" utility to try to figure out what kind of file it is. Utilities->Select On Contents... Lets say you have selected all the .h files with the Select command above and you want to narrow the selection to only the files that contain the string "MAXBUF". Choose this command and edit the grep command to "grep MAXBUF" and press return. The selection will now show only files containing the MAXBUF string. Utilities->Run Command... Select a few entries and choose this command and you will then get a popup asking you to enter a command that is to be run with the selected files as argument. The output of the command, if any, will show up in a text viewer. You can also use this to start programs. Just select the executable, press RunCmd, edit the command and press enter (add a "&" if you like to run it in the background). Utilities->Check Size Of Selected... This command counts the size of selected files and directories and shows the result in kilobytes. Note that this uses the du command and you might have to add the -k flag here to get the answer in kilobytes on some platforms (like Solaris 2.x). Do that in the Configuration->Edit Configuration command [config(cmd,du)]. Utilities->FTP Copy With Resume Use this menu choice instead of the Copy button if you want to copy files with FTP in "resume" mode. This means that if you have previously dropped an FTP transfer you can continue to download where you left off. The Stop button This tries to abort the current command. For normal file access commands (copy, move etc) it can only abort between two files, not in the middle of operating on a file (ex:in the middle of copying a file). For FTP, you can abort in the middle of a transfer. The FTP link will be closed when you do this, but reopened the next time you access an FTP file. You can The Clone button Start another instance of FileRunner at the same directory positions as the current one. In addition to the Stop button above, these two buttons are the only ones that can be pressed during execution of a long command (usually, not all commands accept this). This button is especially good if you start a long FTP transfer and you want to continue to browse during the transfer in another window. Username@Machine This is an indicator showing you the user FileRunner was started by and which machine it is executing on. The Clock You can get two different formats for this. Check the configuration file for config(dateformat). Help->**** Online help texts. 3.2 The Status Line ============================================================================= Various status messages will show up here. Important ones will also be logged to the internal message log that can be viewed and saved with "File->View Log". 3.3 The Directory Panels ============================================================================= At the top of each directory panel is a status line that tells the number of selected files out of the total number of files, the number of bytes in those selected files and also how much free space is left on the disk. 3.3.1 The Directory Panel Menus ============================================================================= [Tree image]->***** This is a very cool feature of FileRunner. Under this menu, you have your entire file system mapped in a cascaded hierarchical menu. Just go down into the menu and select a directory and you will swoosh over there. Don't worry, FileRunner does not map your entire file system at startup, it builds the menus as you traverse them (this is why it sometimes takes a while if you go into slow file systems). Hotlist->Add to hotlist Adds the currently shown directory to the hotlist. Hotlist->[directories] Choose a directory to go there. History->****** As you travel through the file system visiting various directories, there is a history to keep track of where you have been. Just select this menu to go back in time. Note that the history list is limited to 20 entries, to keep it from growing outside your screen. Etc->Find File... Let's you type in a fragment of a file name and search for this in the current directory. A panel with the search results will pop up and you can click on the file names to locate the file in the file list panel. Etc->Create Empty File... You'll figure it out... Etc->Add To Batch List... Add all selected files to the FTP batch list Etc->View Batch List... View the FTP batch list Etc->Clear Batch List Clear the FTP batch list. Etc->FTP Batch Receive... Download all files in the FTP batch list to the current directory. 3.3.2 The Directory Panel Buttons ============================================================================= [Left-Arrow] Use this to go back to previously visited directories. Works just like the back button in Netscape. This button is a little different than the history menu, since the history meny holds the history of the left and right visited directories merged together, while the back button is a "true" back button that really let's you travel backwards in each file list panels individually. [Two arrows in a circle] Press this to update the file list, in case you think it needs to. FileRunner will notice certain events by itself and will usually keep the list up-to-date automatically. [Up-Arrow] Press this to go upwards (cd ..) in the directory tree. [Image of the built-in shell window] Starts the built-in shell for the left or right panel. See chapter 10 for more info on this. [Image of a terminal window] Press this to start a terminal window at the current directory location. 3.3.3 The Directory Entry ============================================================================= This entry shows what directory is listed in the file list below. Edit this to go somewhere else. Sometimes it is also used as an input to commands. For example the MakeDir button will want the name of the new directory here before you press the button. To quickly clear the entry: Press Ctrl-A (to go to the start of the entry) and Ctrl-K to clear it. You can also press the right mouse button in the directory entry to pop up a requester where you can type in the new path. If you type in a directory that doesn't exist a requester pops up to ask you to correct your input. Here you can also press a Create button that creates the new directory and changes directory to it. This is a good way of creating new directories. When the new directory is created, all it's parent directories are created also if they don't already exist. 3.3.4 The File List ============================================================================= This panel shows the contents of the directory. You can scroll around using the scrollbars, or the middle mouse button. To the left are the file names. Files shown with a / appended to them are directories. Files with a @ appended are links. You can see where the link points to if you scroll the list to the far right. Next comes the size of the files, followed by the date of their last modification. The date format can be changed, do a "Configuration->Edit Configuration" and look for the config(dateformat) variable. After the date comes the standard Unix file mode flags. After this the owner (user/group) is shown. Last on the line comes an indication of where a soft link points to, if the file is a soft link, that is. If you activate a panel (by selecting a file in it) and press a key, the file list will adjust to show files starting with that character. This is handy to quickly search for a file you know starts with a certain character. At the bottom right of the file list panel, where the scrollbars meet, there is a button with the letter S in it. This is a select-all / select-none toggle button to quickly select all files or no file. 3.3.4.1 Mouse Buttons In The File List ============================================================================= This area is a little bit messy, so I'll try to clear it up with a simple table of available mouse operations. LMB = left mouse button MMB = middle mouse button RMB = right mouse button LMB - select/unselect (clears selection first) MMB - select/unselect (does not clear selection first) Ctrl-LMB - select/unselect (does not clear selection first) RMB - view things/cd to directory Double-LMB - view things/cd to directory Ctrl-RMB - View directories in opposite panel As you can see, some functions are on more than one button. This is as it should be. Which you use is a matter of convenience. When it says Ctrl-RMB that means you have to press Ctrl on the keyboard and hold it and then press RMB. Double-LMB is a normal doubleclick. As can be seen from the table, viewing stuff is done by pressing RMB on a file. Press it on a text file, you will view the text file. Press it on an image file, you will view the image. Press it on an archive and you will get a list of the contents of the archive. Etc.. You also change directory to a new directory by pressing RMB on the directory. If you press Ctrl with RMB on a directory, the directory will show up on the opposite panel, letting you easily browse a list of directories. Very handy! 3.3.4.2 Keyboard Support In The File List ============================================================================ If you set the config variable config(keyb_support) to 1, FileRunner activates keyboard support mode. Currently, this is not very extensive. This is what happens: The file list panels take focus when clicked and the selection can be adjusted with the up/down arrows. When the one of the file list panels are in focus: * Pressing tab changes focus to the opposite window * Up/Down arrows adjust select * PgUp/PgDown scrolls a whole page up and down * Left arrow goes one directory up (cd ..) * Right arrow views things (including directories) * The underlined characters in the middle command buttons can be pressed to start a command. (c : Copy, d : Delete etc.) I'm sorry FileRunner does not yet have better keyboard support, but it really was designed as a mouse-operated application from the ground up. 3.4 The Command Button List ============================================================================= At the top of the command button list there are two buttons with an up and a down arrow on them (ignore the sideways arrow for now). If you press these you will scroll through the whole list of command buttons. This is handy when the number of buttons grow beyond the size of the window. (You can add more buttons here yourself, see below). Below these two buttons comes the main command button list. Most of these buttons will do nothing if you do not first select something. If the command button supports asynchronous mode, this will be noted below. Also see chapter 3.4.1 below about asynchronous vs. synchronous command execution. [left-arrow] and [right-arrow] buttons Press these to "copy" the current directory from one panel to the other. Copy Copy files and directories. If you copy a link to a file, the file is copied (not the link). If you copy a link to a directory, the directory is copied (not the link). The only time links are copied is if they reside in a directory that is copied. Async operation support: Only for directories. Copy As Same as Copy, but this will let you choose a new name for the copy. Async operation support: Only for directories. Delete Deletes files and directories. Async operation support: Only for directories. Move Moving files around. This function is limited by the standard mv command in that it can usually not move directories across file systems. (You will get an error if you try) Async operation support: No Rename Rename stuff. Async operation support: No MakeDir Create new directories. You have to enter the name of the new directory in one of the directory entries and then press the MakeDir button to create a new directory. When the new directory is created, all it's parent directories are created also if they don't already exist. Async operation support: No S-Link (Soft-Link) Works the same way as Copy, but will not actually copy stuff, only create a soft link to pointing back to the original. Async operation support: No S-LnAs (Soft-Link with rename) Works the same way as S-Link, but will not actually copy stuff, only create a soft link to pointing back to the original. This version lets you rename the link before it's created. Async operation support: No Chmod (Change Mode == Change permissions) Lets you change permission flags on a file. You can set permissions, meaning you select exactly which permissions a file should have, you can also add or delete permissions, meaning you only add a few permission bits or delete a few bits and leave the rest unchanged. You can also set permissions recursively. A tip: Usually you only use the recurse mode with the add/delete actions and not the set action. For example if you want to add group read and write permissions to a whole tree of files, you chould use the add action and the recurse option. See the chmod man page for more info on Unix file permissions. Async operation support: Yes View Same as pressing the right mouse button on a file to view it with the exception when you view multiple files: When you do this, the viewer command will not be started once for every file you have selected, but instead it will be passed all your selected files as argument to the viewer, starting it only once. The first file selected will determine what kind of viewer will be opened for ALL the files. You can't select one text file and one image and press the view button. See the config file on how you can set up your own bindings so for example you start xv when you view .jpg files. Async operation support: Always async Edit Will start the editor of your choice (see configuration below) with the argument of all your selected files. Async operation support: Always async Q-Edit (Quick-Edit, the builtin editor) Select a few files and press Q-Edit to launch the editor. See below for a reference on the internal text editor. Async operation support: Always async Arc (Archive) If you select a directory, the Arc button will create an archive file that contains the contents of the directory tree. It will use the archiver you have configured. The archived file will be named the same name as the directory with an extension added to it. If you press it on a regular file, it will pack the file with the packer you have configured. The archived or packed files will be created in the same directory as the original sources. Async operation support: Yes UnArc (Unarchive) If you select an archive, FileRunner will try to guess what type of archive it is and then unarchive it into the OPPOSITE directory panel. If you want the archive unarchived into the same directory, you have to set the same directory in the left and right panels first. (This may sound weird, but it is actually quite handy since you often don't want to unarchive stuff in the same place as the archived file resides). Async operation support: Yes UnPack If you select a packed file, FileRunner will try to guess what type of packed file it is and unpack it in the same directory as the packed file. Async operation support: Yes Print Select a file and press print. FileRunner will invoke the print command you have configured. Async operation support: Always async Select This command is used to easily select, for instance, all .h-files. First you enter a select-pattern in one of the directory entries and then you press select. For example: Let's say your left directory panel shows /usr/src/foobar and you want to select all .h-files. Just edit the directory to /usr/src/foobar/*.h and press select. Diff Select two files or directories and press diff to see what the difference is between them. You can also select files in different panels just by clicking on one file in one panel and then selecting another in the other panel. You can configure what diff command to use. Async operation support: No 3.4.1 Synchronous vs. Asynchronous Command Execution ============================================================================= If you press the left mouse button on one of the command buttons, the file operation is executed synchronously, i.e FileRunner will wait for the command to finish before accepting another command to run. If you press the right mouse button the command will be executed asynchronously (in the background) letting FileRunner take more commands immediately while the first one is still running in the background. For some buttons, this is not implemented (where the operation is very fast anyway, like doing soft links). This IS implemented for FTP, which means you can mark 25 files and press the right mouse button over the Copy button and have 25 parallell transfers going to the same server simultaneously... Be careful with this, since it will load the ftp server and net connection badly! (Which is a naughty thing to do if you are a nice netizen :-) The drawback with asynchronous operations is that it won't tell you if things go wrong during a copy, etc (for some operations, though it will print this to the standard error output for FileRunner). It will also increase the risk that the file panels aren't showing correct information (you'll have to use the Update (two arrows in a circle) button). For ftp transfers, it will usually take longer since it has to start another ftp session for every file it copies (in parallell). 3.5 Command Line Arguments ============================================================================= Syntax: fr [-iconified] [left-start-dir] [right-start-dir] -iconfied Start up iconified left-start-dir Start by showing this directory in the left panel. right-start-dir Start by showing this directory in the right panel. 4. The Classing Engine. ============================================================================= [Chapter deleted, obsoleted by the unpacker/viewer config parameters] 5. The Internal Text Viewer And Editor ============================================================================= The internal text viewer pops up when you view text files and the internal text editor is used when you press the Q-Edit button. When you enter these programs, you just get a text view and a scrollbar. To activate any command you press the right mouse button in the text and use the pop-up menu. Note that this popup menu can be "torn off" by selecting the dashed line at the top. This will make the menu stay up after use, and is very handy if you want to press "Search Again" many times. The text viewer and editor are normal Tk text widgets and have the standard text widget bindings. Some interesting bindings are: * Position the cursor with the left mouse button. * Double click or triple click to select a whole word or line, respectively. * Drag with mouse button 1 to make a selection of text. * Click the middle mouse button to insert text from the selection. * Drag the middle mouse button to scroll the text (fast panning, very cool). * Ctrl-A and Ctrl-E moves the cursor the beginning and end of the line, respectively. * Ctrl-Home and Ctrl-End moves the cursor the start and end of the text, respectively. * Copy, Cut and Paste (F16, F20 and F18 or Meta-w, Ctrl-w and Ctrl-y) work as they are intended (Cutting, copying or pasting the selection). * Ctrl-k deletes a line. Take a look at the Tk "text" manual for more info on this. To quit the text editor and viewer you have no less than four choices: - The standard X11 "delete-window" command (accessed from your window manager, not FileRunner). - Press the little cross at the top right of the window. - Select the menu in the window with the right mouse button and choose quit. - Press the Escape button in the window. The text editor will check if it loses any characters when the file is converted to text. If this happens, you will get a warning. You cannot edit binary files. When reading MS-DOS text files on a Unix machine, any CR/LF tuples will be converted into LF's, but you will get a warning if this happens. 5.1 The Internal Text Viewer Menu ============================================================================= "------" "Tear off" the menu. Try it to see what happens. Search... Pops up a requester asking you to type in a string to search for in the text. Search Again Search for the same string again. Save As... Lets you save the contents of the text view to a file. If you have edited the text, the edits will be saved. (Yes, you can _edit_ in the text _viewer_ ....:-) Quit Quit the viewer. 5.2 The Internal Text Editor Menu ============================================================================= Same as the text viewer menu (above) except that it also has a command called "Save & Quit" which will immediately save the file that is edited and then quit. Also, the text editor has a "Save" command that just saves the current file to disk and does nothing more. 6. Configuration ============================================================================= The configuration is saved in a file called "config" which is located in a sub-directory called ".fr". This directory is created in your home directory the first time you start up. This is where all the configuration options are stored. Some options can only be changed in the config file but many options can also be changed in the Configuration menu. If you change anything, the changes are saved when you exit (unless you set the configuration option config(save_conf_at_exit) to zero). You can also manually save the change by doing a "Configuration->Save Configuration" in the menu. There is also a system-wide config file that you can edit to reflect some of the local configuration options at your site, so everyone will not have to edit these parameters themselves. Typically you enter stuff like the name of the ftp proxy server etc. The file should be called "config" and put in the FileRunner distribution directory (where all the .tcl files and the fr main script is located.) This file does not get auto-generated. Just enter the config parameters you want in this file, and they will override the default FileRunner configuration (but they won't override the individual user configuration). When you edit the configuration with "Configuration->Edit Configuration" and save the file, it is read back in by FileRunner to reflect the new configuration. When you save configuration with "Configuration->Save Configuration", the .fr/config file is auto-generated, so don't add anything to the configuration file you want to save... You can re-read the configuration file any time with the "Configuration->Reread Configuration" command. This is good if you edit the configuration with another editor other than the default "Configuration->Edit Configuration". Here comes an example of a config file with some added comments. Note that all the config options already have some documentation, so it will be easy to edit. Not all configuration options are listed in the example config file below, only the ones that need a more explicit explanation than what is already in the config file. To see a complete list of options, choose "Configuration->Save Configuration" and then "Configuration->Edit Configuration...". ---------------- Example config file ----------------------------------- # This is the configuration file for FileRunner. It will be read # everytime FileRunner starts up and also when you do a Save&Quit after # editing this file. Only edit values for variables that are listed. Do # not add or delete anything, since this file will be automatically # re-generated when you do a Save Configuration and those changes will be # lost. #----------------------------------------------------------------------- # This list is what will show up in your HotList menu. (Like "bookmarks" # in Netscape). Feel free to edit this list. set config(hotlist) { /home/harmsen /usr/src/linux } The above hotlist is in its most simple format. If you want to have more informative entries in the hotlist you can make aliases for the entries like this: set config(hotlist) { {{My Home} /home/harmsen} {{Home of Linux} /usr/src/linux} } This will make "My Home" show up in the hotlist entry, but you will still be going to /home/harmsen when you select it. Note the added braces. You can also have submenus like this: set config(hotlist) { { {-Cool homes} {{My Home} /home/harmsen} {{Home of Linux} /usr/src/linux} } {{Linux kernels} ftp://ftp.funet.fi/pub/Linux/PEOPLE/Linus} } This will make a submenu in the hotlist called "Cool homes" and under it will be "My Home" and "Home of Linux". Note the added "-" before "Cool Homes" (this is to identify this entry as the head of a submenu) and the extra braces. Currently, you can only have one nesting level here. At the end of this hotlist is an FTP-URL, they are treated as any path in the hotlist. Someday, I'll create a cool bookmarks-editor that can do this for you... #----------------------------------------------------------------------- # The print command you want to use to print files. set config(cmd,print) "lpr {%s}" If you, like me, are using the cool atp program, you can edit this to: set config(cmd,print) "atp {%s} | lpr -Phplj5" The | character is a normal shell-pipe symbol, so you can have those in here too. The print command will be launched in the background. #----------------------------------------------------------------------- # Sets how often FileRunner checks to see if it needs to update its windows. # Set this to 0 to disable. Value is in seconds. set config(autoupdate) "5" The updating is currently done by checking the modification time of the directories that are shown in the left and right panel. This will detect added or deleted files, but not modified files. ---------------- End of Example .fr file ------------------------------- (As mentioned above, do a Configuration->Edit Configuration to see all parameters) See also the FTP chapter 8.8 where the config(ftp,login) parameter is further explained. 7. Home-made Buttons ============================================================================= You can define your own buttons and your own commands to use with these. These are read at startup from a file called $HOME/.fr/cmds. These buttons now have a new interface in v2.0 compared to v1.2. Now they get the whole list of selected files at once and they can also get called with an empty list when there is no selection. New for v2.4: The commands will now receive an extra argument "mbutton" that says which mouse button was pressed. This is an example of how it should look: ---------------- Example .fr/cmds file ------------------------------- # This is an example of user-defined commands. This file should be named # $HOME/.fr/cmds. It will be read by FileRunner at startup. # This list should contain all user-defined commands formatted as: { { } {..} {..} } set config(usercommands) { { MyBut MyButton } { FindFile FindFile } } # This is an example of a command button that runs the "file" command on the selected files. # Arguments: # filelist - list of selected files under $srcdir, can be empty # srcdir - source directory # destdir - destination directory # mbutton - which mouse button was pressed (Values: 1:Left 2:Right 3:Middle) proc MyButton { filelist srcdir destdir mbutton } { cd $srcdir set l {} foreach f $filelist { set l "$l\n$f [exec file $f]" } ViewString "MyButton Output" l "" } # An example of using the find command in FileRunner # Note that you need to mark something in one of the directory panels # to set the srcdir directory, even if nothing from $filelist # is used. # Arguments: # filelist - list of selected files under $srcdir, can be empty # srcdir - source directory # destdir - destination directory # mbutton - which mouse button was pressed (1:Left 2:Right 3:Middle) proc FindFile { filelist srcdir destdir mbutton } { set findname [EntryDialog "Find..." "Please enter substring of filename to search for" ""] if {$findname == ""} return cd $srcdir set out [exec find . -name "*${findname}*" -print] ViewString "Output" out "" } ---------------- End of Example .fr/cmds file --------------------------- The prototype for the command is: proc MyButton { filelist srcdir destdir mbutton } { filelist - list of selected files under $srcdir, can be empty srcdir - source directory destdir - destination directory mbutton - which mouse button was pressed (Values: 1:Left 2:Right 3:Middle) You are welcome to use the following internal commands of FileRunner in your own buttons: Command Arguments Comment ------------------------------------------------------------------------- ViewText filename ViewString title string-variable filename (set filename to "") ViewImage filename EditText filename script-to-run-when-saved (set the last arg to "") EntryDialog title info-text start-entry (returns the entry-text or "" if aborted) PopInfo info-text PopWarn warn-text PopError error-text Log log-text And all normal Tcl/Tk stuff of course. 8. FTP (File Transfer Protocol) ============================================================================= You can also do FTP sessions with FileRunner. You can browse FTP sites just as if they were on your local file system. Just enter an FTP URL in the directory entry and you will be browsing an FTP site. For example: "ftp://ftp.funet.fi/pub". You can do most of the same things with an FTP listing as you can with a "normal" directory, like copying, deleting, renaming and viewing stuff etc. There are some things you cannot do on an FTP file/directory: - You can't make soft links to an FTP file. Wouldn't be useful... - You can't move things from or to FTP. Use copy and delete. - For the source/directory operations (copy, move, etc) you cannot have FTP on both sides at the same time. There are other things you can't do but FileRunner will tell you so if you try, so don't be afraid of trying. The hotlist can hold FTP sites as well as normal directories. Just do "HotList->Add to hotlist" and then probably you want to do a "Configuration->Save Configuration" to save it for later. If you want to FTP to an FTP site which is not at port 21 (the normal FTP port), you can add a port suffix to the FTP URL: ftp://:/ example: ftp://ftp.foo.com:8080/pub/bar 8.1 Anonymous FTP ============================================================================= Under the configuration menu, you can turn on or off anonymous FTP. If you turn it off, you will be prompted for username and password when you go to a new FTP site. 8.2 FTP Through Proxy ============================================================================= You can also do FTP through an FTP proxy site. Ask your administrator if you have an FTP proxy and what the name of it is and enter it into the config file in the config(ftp,proxy) variable. Currently, the FTP proxy functionality has only been tested in one of the proxy types where you have this kind of log-on sequence: ~> ftp proxy-host Connected to proxy-host. 220 You're now at the FTP gateway. Name (proxy-host:username): anonymous@ftp.funet.fi 331-(----GATEWAY CONNECTED TO ftp.funet.fi----) [more stuff] Password: [here I enter my password which is my email address, since this is an anonymous connection] 230- Finnish University and Research network FUNET [more stuff] ftp> As you can see, you enter the username and ftp site in the Name: prompt, and then your password as normal. Is there other kinds of proxys out there? Let me know! 8.3 Synchronous Or Asynchronous FTP Transfers ============================================================================= When you receive files from FTP, this is normally done synchronously, meaning FileRunner can not be used for other stuff during the transfer. If you want to continue to use the FTP session and have a long transfer run in the background, just use the right mouse button over when you click the Copy button. The transfer of will then take place in a separate window and will let you continue working. If you forgot to do this and still want to continue browsing the FTP site, press the clone button to fire up another copy of FileRunner to continue browsing there. 8.4 FTP Timeout ============================================================================= Usually, FTP connections time out after a while (900 seconds or so). When this happens, FileRunner will give you an error message the next time you access the FTP site. Just click OK on this popup and try the command again, and the FTP connection will automatically be reopened. 8.5 Closing FTP Connections ============================================================================= You don't have to close FTP connections explicitly. They are closed automatically when you go to another FTP site or to another Unix directory. The FTP connection will of course not close if it is still used in the opposite panel. 8.6 FTP Transfer Status ============================================================================= When you receive files through FTP you get status indication in the status line telling you how many bytes are left, how fast the transfer currently is and estimated time of arrival (ETA). The speed calculation and ETA calculation use speed measurements over the last 60 seconds averaged to calculate the current speed. Just using the current speed sample (measuring the time for one 4kB block) would give inaccurate results due to kernel buffering and various TCP tricks. At the end of the transfer you will be told how fast the download was in total (total number of bytes divided by the total time for the download). Note that the ETA is showed both in relative time (MM:SS) and absolute time (HH:MM). 8.7 Temporary Storage For FTP Files ============================================================================= When you view stuff with the view button or right button mouse the file is temporarily placed under /tmp/_fr_tmp. This directory is cleaned up when you exit FileRunner. 8.8 Using The Rule-based Configuration For FTP Logins ============================================================================= FileRunner contains a rule based configuration for FTP logins. For example: you can tell it to always log in with username X and password Y to sites matching *.Z.com etc. This is very convenient as you don't have to toggle back and forth in the Configuration menu for the anonymous and proxy configuration when jumping between FTP sites. Instead you decide once and for all what information to use when connecting to specific sites. Let's have a look at an example of the config(ftp,login) parameter. To change it you do a "Configuration->Edit Configuration" and edit the config(ftp,login) parameter in the FTP section. set config(ftp,login) { { *.foo.com { myusername mypassword } } { machine.bar.com { myotherusername XXX } proxy1.local.edu } { * { anonymous joe@mailbox.edu } proxy2.local.com } } The rule is a list of configurations. When you connect to a new site the list is scanned from beginning to end, to see if there is a match. If there is, the information in the list is used and the current settings under the Configuration menu are disregarderd (the anonymous and proxy configuration). The rules look like this: { ftp-site-pattern { username password } optional-proxy } First there is a pattern that is matched to the FTP site you want to connect to. You can use wildcards in this pattern. Next comes a list with username and password that is to be used when connecting to the FTP site. Last is the name of the proxy ftp site, if you need one. Leave this empty if you don't connect through a proxy. Taking the elements one by one from the example: { *.foo.com { myusername mypassword } } This line matches all FTP sites that match the pattern *.foo.com. It tells FileRunner to always use the username "myusername" and the password "mypassword" when connecting to these sites. This rule does not use a proxy. { machine.bar.com { myotherusername XXX } proxy1.local.edu } This line is used for doing FTP to a single machine only; "machine.bar.com". It says to use username "myotherusername". The password says "XXX", which means that FileRunner should prompt for the password when you connect to the site. This connection goes through an FTP proxy: "proxy1.local.edu". { * { anonymous joe@mailbox.edu } proxy2.local.com } This line matches all other sites and says you want to do anonymous FTP to these sites. As password you should insert your email address. For these connections the example says to use the FTP proxy "proxy2.local.com". Since these three rules will match anything (the rules are scanned from beginning to end and the "*" will match any site), you never have to bother with the Anonymous and Proxy settings under the Configuration menu. A note about security: As you can see above, it is possible to store passwords in this parameter but you can also insert XXX to have FileRunner prompt you for your password when you connect to a new site. As you've probably figured out, it is not very safe to have your passwords stored in your config file, accessible to anyone... Well if you are running a local machine (at home perhaps) and you deny everyone on the Internet access to the local machine (by not starting inetd, for example), you should be able to safely store your passwords in the config file since only you have access to your local machine anyway (as was assumed). On the other hand, if you are for example on a University network, you should be aware that even if you change permission on the config file to -rw-------, it's not really safe anyway since System Administrators and other scruffy people can read your file anyway, either through running as root or by using yet another Unix security bug. In general it is a Bad Thing (tm) to store your passwords in any file in a networked environment... Some will do it anyway, but PLEASE at least change the read permissions on the config file first! This is how you do this: > chmod go-rw ~/.fr/config You Have Been Warned... 8.9 Batch FTP ============================================================================= Batch FTP download is useful when you want to select a number of files for downloading when the files are not in the same directory or even on the same site. You can browse any FTP site, add the selected files to the batch list, then later start the batch download and go do something else while the files download. This is all done by using an FTP batch list. You can add, view and clear the batch list (Etc menu). When the batch list holds the files you want, select "Etc->FTP Batch Receive..." to download the files to the current directory. See the Etc menu. 8.10 FTP Transfer Speed (dropped characters with a buffered serial port??) ============================================================================= This chapter has nothing to do whatsoever with FileRunner, but I'd like to share this information anyway since it has a lot to do with FTP transfers. I have a Sportster 28800 modem and I've never (until recently) been able to achieve better than ca 2.2 kb/s on FTP transfers. This is on a 486/66 w 20MB RAM and a couple of IDE disks and a 165550A buffered serial port. The problem showed itself when I ran the program ifconfig, I always got several dropped packes which hurt performance a lot. It turned out the problem was the high latency of the IDE disk driver in the Linux kernel. The latency was so high the serial port dropped characters even though it is buffered. The solution to this was to 1: Switch to Linux kernel 2.0.22 and 2: run the hdparm v2.9 program in my rc.local file like this: hdparm -u 1 /dev/hda (actually my command looks like this "hdparm -q -u 1 -q -m 8 -q -W 1 /dev/hda", but it is the -u switch that counts here). This let's the IDE driver be interrupted by the serial IO driver and voila: No more dropped packets. FTP transfer went up to a steady 3.3kb/s with peaks of 8kb/s on text files!! Not a single dropped packet! In the hdparm manual it says the -u switch is dangerous, but as far as I can tell from the manpage it's not dangerous if you run kernel 2.0.22 or later. I have not had any problems with it anyway. You can get hdparm from: ftp://sunsite.unc.edu/pub/Linux/kernel/patches/diskdrives It's a great program. It also lets you turn on the IDE multi-block transfer mode (-m 8 above) and write caching (-W 1 above). Just make sure to read the manual first... Recent note: Some video card drivers will also generate dropped packets. Sometimes the driver is written to ignore checking the status of the graphics card and just continue to shuffle commands to the card even though it is working. This will usually result in the CPU hanging on the bus waiting for the graphics card and you will get lots of interrupts from the serial port that the CPU will miss. Better drivers will solve this. 9. The Internal Shell Windows ============================================================================= FileRunner has built-in shell windows that pop up when you press the little rectangular button to the right of the up-dir arrow button at the top of the file list panels. These windows behave much like an xterm window with a shell running in it, although the shell windows cannot handle interactive programs, they only allow output from the commands you run in them. Having a shell inside FileRunner gives you the flexibility to run simple commands without having to switch to a terminal window. These windows have a text area where the output of the command is sent. They have a scrollbar so you can see output from previous commands. There is also a small text string at the left side that shows the current directory for the shell, and a command entry where you type your commands. At the right of the command entry there is an "R". This turns red when commands execute so you know if they are finished or not. To the right of this, there are three "size" buttons (smaller, larger, maximum) that you can press to change the size of the window. There is one shell window for each of the left and right file panels, and they always show the same current directory as their respective file panels. If you travel around in the directory tree in the file list panels, the shell current directory will follow, and if you change directory in the shell, the file list panel will follow and update itself. Since directory traversing can be done very fast within FileRunner, this is a big time-saver (and the main reason there are built in shell windows in FileRunner in the first place). For the shell connected to the left file list panel, the scrollbar is on the left side of the command output area. For the right file list panel shell, the scrollbar is placed to the right. This is how you tell them apart. Running commands: To run a command, just type the command into the text entry and press enter. The command will be run in the background and you can immediately run more commands if you wish. A small "R" to the right of the command line will turn red as long as one or more commands are executing. If multiple commands produce output at the same time they might become intermixed. History: To retreive previous commands, you can press the up and down arrow keys to flip through the history. Type the command "history" and you will see all previously executed commands. Filename completion: The shell has built-in file name completion activated with the Tab button. If you type parts of a command verb or file name, FileRunner will search the directory and replace it with a full filename. For example, if you have a file called foo.bar and you type "rm fo"+tab, FileRunner will fill in "o.bar" and complete the filename. If there is more than one file matching (for example you type x+Tab and you have files called x1 x2 x3...), it will put in the first of these matched files (x1 in this example). If you then press Tab again it will cycle through all possible matches (x2, x3 etc). If you press Control-D, the shell will show you all possible matches to the completion request. Internal commands: cd [dir] - Change directory. Synchronized with the file panel. view [file] - Start the internal text viewer on the file specified. history - Show previously executed commands. Aliases: You can define aliases within the shell window. See the config file on how to do this. Tcl commands: You can also execute Tcl commands in the internal FileRunner context. Just prefix the command with a % and type in a normal Tcl command. This is of limited use to others than the author... See also the configuration file for more configuration on the shell, like command color and shell window sizes. 10. Miscellaneous ============================================================================= 10.1 Exported Selections ============================================================================= When you select files and directories in the file list panels and then "paste" this selection into an xterm, for example, by clicking the middle mouse button inside the xterm, you now get the list of files you have selected, fully qualified with paths. This is very handy when you are working inside FileRunner and you need to do something with a file in an external window. Can of course also be used inside the internal shell window. 10.2 Files Used and Created By FileRunner ============================================================================= ~/.fr Configuration directory ~/.fr/config Config file ~/.fr/cmds Your own button commands ~/.fr/ver Latest version of FileRunner run. ~/.fr/history Directory history saved to disk /tmp/$USER_fr_tmp/* Temporary files (created when viewing FTP files) 10.3 Choosing cursor color ============================================================================= You can actually change the shape and colors of the cursor if you for example choose a dark background with bright text and you have a hard time seeing the cursor. Put the following command in the ~/fr/cmds-file: . config -cursor {left_ptr Blue Red} This will give you a small blue and red arrow. You can see what other cursors are available from looking at the /usr/X11/include/X11/cursorfont.h file. Just strip the XC_ prefix and use one of the cursors defined. The colors defined are standard X11-colors. 10.4 HTTP Download ============================================================================= You can also use FileRunner to download HTTP files (HTML, binaries, whatever). The reason I've added this is that the download function in Netscape is so incredibly crappy: Nine times out of ten, it will stop downloading somewhere near the end of the file and not say a peep about the fact that the file you got was truncated and utterly useless... Anyway, this one works lots better of course :-) It warns you (if it can) if the file received was too short and it also uses a longer timeout than Netscape so you will (hopefully) get fewer aborted downloads. Use: Just choose "Etc->HTTP Download" and enter an URL to download. You don't have to bother with adding "http://" if you don't want to. Then choose a filename to save the download to. 11. Copying/Copyrights/Legal Stuff ============================================================================= The program and all associated files are Copyright (C) 1996-1998 by Henrik Harmsen. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 12. Send Me A Postcard! ============================================================================= If you like FileRunner, please send me a cool postcard so I can fill the front of my fridge! :-) 13. Bug Reports/Questions ============================================================================= Before sending me bug reports or questions, please have a look at the FAQ file and the README file to see if your problem is already answered there. Sometimes FileRunner will pop up a window saying you've found a bug. That means something really serious just happened and FileRunner will not continue executing. You then have the option of preparing a bug report you can send to me. Please do. But please check the FAQ to see if this bug is described there already (it'll save both you and me time). 14. Contacting The Author / The Announcement Mailing List ============================================================================= You are very welcome to mail me suggestions for improvement or bug reports or questions or whatever. I might not have time to answer them all, though. Email: hch@cd.chalmers.se (preferred) or Henrik.Harmsen@erv.ericsson.se Snail-mail: Henrik Harmsen Kungälvsgatan 5A S-416 69 Göteborg SWEDEN If you have trouble contacting me, try search the web for "FiLeRuNnEr" (this exact string) and you should be able to find my new address. Currently you will find the webpage at http://www.cd.chalmers.se/~hch/filerunner.html There is a mailing list with announcements for FileRunner. Mail me and tell me if you're interested to be on it.