Thread: iTCL Reference
View Single Post
Old 03-24-2007, 12:51 AM  
Yil
Too much time...
 
Join Date: May 2005
Posts: 1,194
Default iTCL Reference

Maybe some kind admin type could move this to the Knowledge Base

This is what I've written up as part of my forthcoming release documenting the current ioFTPD specific extensions to TCL. I'm not a big TCL scripter so let me know if I got something wrong. Parts are cobbled together from ChangeLogs, posts on the forums, and the source code itself.

Code:
iTCL commands list reference by Yil
-----------------------------------

NOTE: All functions return 0 on success and non-zero on error unless noted.


* buffer: Get/Set the temporary output buffer
    Set <value>      : Sets temporary output buffer to <value>
    Get              : Returns current output buffer



* change: Change user or group settings.
    {userName|groupName} { AdminGroup | Credits | Flags | HomeDir | Logins |
                           Passwd | Ratio | SpeedLimit | Stats | TagLine |
                           VfsFile | GroupSlots | GroupVfsFile |
                           GroupDescription }
                         [parameters]

  AdminGroup <groups...>        : Set groups which user has admin rights for
  Credits [+-]<value> [section] : Modify user's credits for section (default=0)
  Flags [+-]<flags>             : Add / Set / Remove user Flags
  HomeDir <vpath>               : Change user's home directory
  Logins <numLogins> [service]  : Change max concurrent logins for user
  Passwd <password>             : Change user's password
  Ratio <ratio> [section]       : Change user's Up/Down ratio for section
                                  (default = 0)
  SpeedLimit <send> [receive]   : Change user's max bandwidth settings

  Stats: change various user values
    [Section <num>] { [ AllDn | AllUp | MonthDn | MonthUp | WkDn | WkUp | 
                        DayDn | DayUp ]
                      [ Files | Bytes | Time]
                      [+-]<num> }*
                    { [ Credits ] [+-]<num> }*

      Section <section #>  - Set the section for following commands to modify
                             Default = 0

      Credits    - Begin modifying user credits (default)
      AllDn      - Begin modifying user alltime download totals
      AllUp      - Begin modifying user alltime upload total
      MonthDn    - Begin modifying user monthly download total
      MonthUp    - Begin modifying user monthly upload total
      WkDn       - Begin modifying user weekly download total
      WkUp       - Begin modifying user weekly upload total
      DayDn      - Begin modifying user daily download total
      DayUp      - Begin modifying user daily upload total

      Files      - Begin modifying number of files transfered (default)
      Bytes      - Begin modifying number of bytes transfered
      Time       - Begin modifying transfer times

      +num       - Add num to existing value
      -num       - Subtract num from existing value
      num        - Set value

  TagLine                 : Change user's tagline
  VfsFile <file>          : Change user's VFS File

  GroupVfsFile <file>            : change group's VFS File
  GroupSlots <normal> [leech]    : Change number of slots for group
  GroupDescription <description> : Change group's description



* client: disconnect logged in users based on some criteria, or use Init to 
          specify which fields you want returned about currently logged in
          users.  Then call Fetch to actually retrieve the fields in the
          order you specified and suitable for use with lindex.
    Kill { UId | VirtualPath | RealPath | ClientId } <parameter>
    Who Init { UId | VirtualPath | VirtualDataPath | RealPath | RealDataPath |
               TransferSize | TransferSpeed | Status | LoginTime | TimeIdle |
               HostName | IP | Ident | CId | Action }
    Who Fetch  : Returns requested fields, or "" when no more users.

  UId - the user's ID
  VirtualPath     - The CWD of the client in the VFS
  VirtualDataPath - The path in the VFS to the file being transfered
  RealPath        - The CWD of the client in the local filesystem
  RealDataPath    - The local path to the file being transfered
  TransferSize    - Current position in file
  TransferSpeed   - Bytes transfered over current data connection so far
  Status          - 0 Inactive, 1 Upload, 2 Download, 3 List
  LoginTime       - 32bit time() when user logged in
  TimeIdle        - Number of seconds user considered idling
  HostName        - HostName client connected from
  IP              - IP address client connected from
  Ident           - Ident response received
  CId             - Unique connection ID (who init)
  ClientId        - Unique connection ID (kill)
  Action          - Last successful command client entered



* config: Change ioFTPD configuration file (usually ioFTPD.ini)
    Read <array> <variable>  : Return value on success and "" on error
    Reload                   : Reload configuration file
    Save                     : Save configuration file



* group: Create / Delete / Rename groups
    create <groupName>  : Creates new group and returns id (>= 0) on success
    delete <groupName>  : Deletes named group
    rename <groupName> <newGroupName>  : Renames group



* groupfile: Open / Read / Modify group file
    isopen              : Returns id of open groupfile, -1 on error
    open <groupName>    : Open named group, automatically closes and unlocks
                          the previously opened group if any.
    lock                : Locks groupfile for modifications
    unlock              : Unlocks groupfile
    bin2ascii           : Read groupfile and returns it in string form
    ascii2bin <string>  : Take string and write it to groupfile which must be
                          locked at this point.



* iputs: Output a string to the user.  Always returns "".
    [-nonewline] [-noprefix] [-nobuffer] <String>



* mountfile: Open specifed mountfile (vfs file) and use it for resolving paths
    Open <fileName>



* putlog: write string to ioFTPD.log (it's timestamped automatically)
    <string>



* resolve:
    PWD <pwd>   : Returns real path on success, "" on error
    UId <uid>   : Returns UserName on success, "" on error
    GId <gid>   : Returns GroupName on success, "" on error
    User <user> : Returns UId on success, -1 on error



* sha1: Returns sha1 hash for string
    <string>



* timer: Set an event to be run in the future
    <timeOut> <event>
  
  timeOut  : Number of milliseconds in the future to run event
  event    : command to execute in the same format as events in configuration
             file, i.e. "TCL ../scripts/timerproc.itcl"



* user: Create / Delete / Rename users
    Create <userName>  : Creates new user and returns id (>= 0) on success
    Delete <userName>  : Deletes named user
    Rename <userName> <NewUserName>  : Renames user



* userfile: Open / Read / Modify user file
    isopen              : Returns id of open userfile, -1 on error
    open <userName>     : Open named user, automatically closes and unlocks
                          the previously opened user if any.
    reload              : Reloads userfile
    lock                : Locks userfile for modifications
    unlock              : Unlocks userfile
    bin2ascii           : Read userfile.  Returns string containing user info
    ascii2bin <string>  : Take string and write it to userfile which must be
                          locked at this point.



* var: Get/Set/Unset user defined global variables which can be used to
       maintain state across TCL calls
    Get   <variable>
    Set   <variable> <value>
    Unset <variable>



* vfs: Get/Set file or directory owner/group/permissions in the VFS
    Read   <directory/file>             : Returns "Uid Gid Mode" or "" on error
    Write  <directory/file> <uid> <gid> <mode>  : Update owner/mode
    Chattr <directory/file> <0>          : Returns PRIVATE setting
    Chattr <directory/file> <0> <value>  : Sets PRIVATE setting
    Chattr <directory/file> <1>          : Returns SYMBOLIC LINK target
    Chattr <directory/file> <1> <target> : Creates SYMOBLIC LINK
    Flush  <directory>                   : Force cache update



* waitobject: Manipulate various locking primities.  These are real system
              level locks.
    Open <name> SpinLock        : Returns lockId of existing lock or creates
                                  a new spinlock.
    Open <name> Event [TRUE]    : Returns lockId of existing lock or creates
                                  a new autoresetting event unless TRUE is
                                  specified in which case it's manual reset.
    Open <name> Semaphore [max] : Returns lockId of existing lock or creates
                                  a new semaphore.  max specifies the
                                  max and initial semaphore count (default=1)
    Delete <lockId>             : Deletes and closes the specified lock
    Close  <lockId>             : Close local reference, but don't delete
    Set    <lockId> [count]     : Set object state to signaled, or to
                                : count (default=1) for semaphores.
    Reset  <lockId> [count]     : Set object state to non-signaled, or
                                : free up count (default=1) semaphore locks.
    Wait   <lockId> <timeout/spincount> [waitCount] : returns 0 on success
                                1 on timeout, -1 on error.  Acquire waitCount
                                (default=1) semaphore locks before returning.

NOTE: the namespace is shared by spinlocks/events/semaphores.
WARNING: Using invalid lockIds can result in server crashes.
Yil is offline   Reply With Quote