home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga 13 / MA_Cover_13.bin / source / c / stefanb_src / dospath / dev / dospath.doc
Encoding:
Text File  |  1996-08-25  |  11.1 KB  |  323 lines
  1. TABLE OF CONTENTS
  2.  
  3. dospath.library/BuildPathListTagList
  4. dospath.library/CopyPathList
  5. dospath.library/CopyWorkbenchPathList
  6. dospath.library/FindFileInPathList
  7. dospath.library/FreePathList
  8. dospath.library/GetProcessPathList
  9. dospath.library/RemoveFromPathList
  10. dospath.library/SetProcessPathList
  11.  
  12. dospath.library/BuildPathListTagList      dospath.library/BuildPathListTagList
  13. dospath.library/BuildPathListTags             dospath.library/BuildPathListTags
  14.  
  15.    NAME
  16.         BuildPathListTagList -- Build a path list from directory names
  17.  
  18.    SYNOPSIS
  19.         head = BuildPathListTagList(anchor, tags)
  20.         D0                          A0      A1
  21.  
  22.         struct PathListEntry *BuildPathListTagList(struct PathListEntry **,
  23.                                                    struct TagItem *)
  24.  
  25.         head = BuildPathListTags(anchor, ...)
  26.  
  27.         struct PathListEntry *BuildPathListTags(struct PathListEntry **, ...)
  28.  
  29.    FUNCTION
  30.         This function builds an AmigaDOS CLI command path list from directory
  31.         names. The new path list can be chained to an already existing path
  32.         list if a pointer to the last entry of this list is supplied.
  33.  
  34.         The path list can be deallocated with FreePathList().
  35.  
  36.         You have to convert this pointer to a BPTR with the BADDR() macro
  37.         if you supply this path list to AmigaDOS.
  38.  
  39.         The following tags are currently supported:
  40.  
  41.          DOSPath_BuildFromArray  (const char **)
  42.  
  43.             Pointer to a NULL terminated array of directory names.
  44.  
  45.          DOSPath_BuildFromList   (struct List *)
  46.  
  47.             Pointer to an Exec list containing the directory names.
  48.  
  49.    INPUTS
  50.         anchor - Pointer to a pointer to the last entry of the list to which
  51.                  the new path list entries should be added. If you want to
  52.                  chain several lists together then you have to initialize
  53.                  anchor to NULL for the first list. You may supply NULL if
  54.                  you don't want to chain path lists.
  55.  
  56.         tags   - List of TagItems
  57.  
  58.    RESULTS
  59.         head   - Pointer to first entry in the new list or NULL if the list
  60.                  could not be created.
  61.  
  62.         anchor - Pointer to last entry in the new list. If the list could not
  63.                  be created then the contents of the variable to which anchor
  64.                  points are NOT changed!
  65.  
  66.    SEE ALSO
  67.         CopyPathList(), FreePathList()
  68.  
  69. dospath.library/CopyPathList                      dospath.library/CopyPathList
  70.  
  71.    NAME
  72.         CopyPathList -- Copy a path list
  73.  
  74.    SYNOPSIS
  75.         head = CopyPathList(orig, anchor)
  76.         D0                  A0    A1
  77.  
  78.         struct PathListEntry *CopyPathList(struct PathListEntry *,
  79.                                            struct PathListEntry **)
  80.  
  81.    FUNCTION
  82.         This function copies an AmigaDOS CLI command path list. The new path
  83.         list can be chained to an already existing path list if a pointer to
  84.         the last entry of this list is supplied.
  85.  
  86.         The path list can be deallocated with FreePathList().
  87.  
  88.         You have to convert this pointer to a BPTR with the BADDR() macro
  89.         if you supply this path list to AmigaDOS.
  90.  
  91.    INPUTS
  92.         orig   - Pointer to head of the original path list.
  93.                  Passing a NULL argument is harmless.
  94.  
  95.         anchor - Pointer to a pointer to the last entry of the list to which
  96.                  the new path list entries should be added. If you want to
  97.                  chain several lists together then you have to initialize
  98.                  anchor to NULL for the first list. You may supply NULL if
  99.                  you don't want to chain path lists.
  100.  
  101.    RESULTS
  102.         head   - Pointer to first entry in the new list or NULL if the list
  103.                  could not be copied.
  104.  
  105.         anchor - Pointer to last entry in the new list. If the list could not
  106.                  be created then the contents of the variable to which anchor
  107.                  points are NOT changed!
  108.  
  109.    SEE ALSO
  110.         BuildPathListTagList(), FreePathList()
  111.  
  112. dospath.library/CopyWorkbenchPathList    dospath.library/CopyWorkbenchPathList
  113.  
  114.    NAME
  115.         CopyWorkbenchPathList -- Copy path from Workbench process
  116.  
  117.    SYNOPSIS
  118.         head = CopyWorkbenchPathList(startup, anchor)
  119.         D0                           A0       A1
  120.  
  121.         struct PathListEntry *CopyWorkbenchPathList(struct WBStartup *,
  122.                                                     struct PathListEntry **)
  123.  
  124.    FUNCTION
  125.         This function tries to find the Workbench process and copies the
  126.         AmigaDOS command path list from this process. This is interesting for
  127.         processes which want to install the system default path for starting
  128.         new processes.
  129.  
  130.         Process started from the Workbench must supply their WBStartup message.
  131.         With this structure the function can safely discover the Workbench
  132.         process. If you supply NULL for the WBStartup message then it tries to
  133.         find a task called "Workbench" in the system.
  134.  
  135.         The path list can be deallocated with FreePathList().
  136.  
  137.         You have to convert this pointer to a BPTR with the BADDR() macro
  138.         if you supply this path list to AmigaDOS.
  139.  
  140.    INPUTS
  141.         startup - Pointer to the WBStartup message for process started from
  142.                   the Workbench. Other processes must supply NULL.
  143.  
  144.         anchor  - Pointer to a pointer to the last entry of the list to which
  145.                   the new path list entries should be added. If you want to
  146.                   chain several lists together then you have to initialize
  147.                   anchor to NULL for the first list. You may supply NULL if
  148.                   you don't want to chain path lists.
  149.  
  150.    RESULTS
  151.         head   - Pointer to first entry in the new list or  NULL  if  the  list
  152.                  could not be copied. NULL is also returned if the Workbench
  153.                  process could not be found or a process with this name was not
  154.                  a CLI process.
  155.  
  156.         anchor - Pointer to last entry in the new list. If the list could not
  157.                  be created then the contents of the variable to which anchor
  158.                  points are NOT changed!
  159.  
  160.    WARNING
  161.         If NULL is supplied for the WBStartup message then this function uses
  162.         FindTask() to find the Workbench process. There is no guarantee that
  163.         this is the process of the real Workbench. It also can't use Forbid()
  164.         to protect the FindTask() call and during the list copy. It will get
  165.         into big trouble if the Workbench process quits while it tries to copy
  166.         the path. You have been warned!
  167.  
  168.    SEE ALSO
  169.         BuildPathListTagList(), CopyPathList(), FreePathList()
  170.  
  171. dospath.library/FindFileInPathList          dospath.library/FindFileInPathList
  172.  
  173.    NAME
  174.         FindFileInPathList - Find a file in a path list
  175.  
  176.    SYNOPSIS
  177.         lock = FindFileInPathList(state, file)
  178.         D0                        A0     A1
  179.  
  180.         BPTR FindFileInPathList(struct PathListEntry **, const char *)
  181.  
  182.    FUNCTION
  183.         This function scans through the path list and tries to find the file in
  184.         each directory. It returns a lock to the directory where the file was
  185.         found.
  186.  
  187.         This function can be called several times in order to iterate through
  188.         the complete path list. So you are able to find all occurences of the
  189.         file.
  190.  
  191.    INPUTS
  192.         state -  Pointer to a pointer to a path list. The function stores the
  193.                  current position in the list after each invocation. It should
  194.                  be initialized to point to the head of the list before the
  195.                  first invocation.
  196.                  Passing a NULL argument is harmless.
  197.  
  198.         file   - File name.
  199.                  Passing a NULL argument is harmless.
  200.  
  201.    RESULTS
  202.         lock   - Lock of the directory where the file is located or NULL.
  203.                  Use DupLock() if you want to get a copy of this lock.
  204.  
  205. dospath.library/FreePathList                      dospath.library/FreePathList
  206.  
  207.    NAME
  208.         FreePathList -- Free a path list
  209.  
  210.    SYNOPSIS
  211.         FreePathList(head)
  212.                      A0
  213.  
  214.         void FreePathList(struct PathListEntry *)
  215.  
  216.    FUNCTION
  217.         Free an AmigaDOS CLI command path list created by
  218.         BuildPathListTagList(), CopyPathList() or CopyWorkbenchPathList().
  219.  
  220.    INPUTS
  221.         head - Pointer to head of the path list to be freed.
  222.                Passing a NULL argument is harmless.
  223.  
  224.    NOTE
  225.         This function should NOT be used to free path lists allocated by
  226.         AmigaDOS itself.
  227.  
  228.    SEE ALSO
  229.         BuildPathListTagList(), CopyPathList(), CopyWorkbenchPathList()
  230.  
  231. dospath.library/GetProcessPathList          dospath.library/GetProcessPathList
  232.  
  233.    NAME
  234.         GetProcessPathList -- Get the path list of a process
  235.  
  236.    SYNOPSIS
  237.         head = GetProcessPathList(process)
  238.         D0                        A0
  239.  
  240.         struct PathListEntry *GetProcessPathList(struct Process *)
  241.  
  242.    FUNCTION
  243.         Get a pointer to the AmigaDOS CLI command path list of a process.
  244.  
  245.    INPUTS
  246.         process - Pointer to the process
  247.  
  248.    RESULTS
  249.         head    - Pointer to head of the old path list. This might be NULL if
  250.                   the process is no CLI process.
  251.  
  252.    SEE ALSO
  253.         SetProcessPathList()
  254.  
  255. dospath.library/RemoveFromPathList          dospath.library/RemoveFromPathList
  256.  
  257.    NAME
  258.         RemoveFromPathList - Remove a directory from a path list
  259.  
  260.    SYNOPSIS
  261.         head = RemoveFromPathList(path, lock)
  262.         D0                        A0    A1
  263.  
  264.         struct PathListEntry *RemoveFromPathList(struct PathListEntry *, BPTR)
  265.  
  266.    FUNCTION
  267.         This function scans through the path list and deletes the first entry
  268.         which matches the directory lock.
  269.  
  270.    INPUTS
  271.         path - Pointer to head of the path list.
  272.                Passing a NULL argument is harmless.
  273.  
  274.         lock - Directory lock.
  275.                Passing a NULL argument is harmless.
  276.  
  277.    RESULTS
  278.         head - Pointer to head of the path list. This is different from the old
  279.                input path pointer if the head entry was removed.
  280.  
  281.    NOTE
  282.         This function should NOT be used on path lists allocated by AmigaDOS
  283.         itself.
  284.  
  285.    SEE ALSO
  286.         BuildPathListTagList(), CopyPathList()
  287.  
  288. dospath.library/SetProcessPathList          dospath.library/SetProcessPathList
  289.  
  290.    NAME
  291.         SetProcessPathList -- Set the path list of a process
  292.  
  293.    SYNOPSIS
  294.         old = SetProcessPathList(process, head)
  295.         D0                       A0       A1
  296.  
  297.         struct PathListEntry *SetProcessPathList(struct Process *,
  298.                                                  struct PathListEntry *)
  299.  
  300.    FUNCTION
  301.         Set the AmigaDOS CLI command path list of a process. A pointer to the
  302.         old path list is returned.
  303.  
  304.    INPUTS
  305.         process - Pointer to the process whose path list should be set.
  306.  
  307.         head    - Pointer to head of the new path list.
  308.                   Passing a NULL argument is harmless.
  309.  
  310.    RESULTS
  311.         old     - Pointer to head of the old path list. This is NULL if the
  312.                   process is no CLI process.
  313.  
  314.    NOTE
  315.        You should only use this function on your own process. Don't try to use
  316.        it on other processes which might be using their command path while you
  317.        are changing it!
  318.  
  319.    SEE ALSO
  320.         GetProcessPathList()
  321.  
  322.  
  323.