home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / CBMDevKit1.dms / CBMDevKit1.adf / autodocs.lha / doc / dos.doc < prev    next >
Encoding:
Text File  |  1993-10-15  |  170.6 KB  |  5,780 lines

  1. TABLE OF CONTENTS
  2.  
  3. dos.library/AbortPkt
  4. dos.library/AddBuffers
  5. dos.library/AddDosEntry
  6. dos.library/AddPart
  7. dos.library/AddSegment
  8. dos.library/AllocDosObject
  9. dos.library/AssignAdd
  10. dos.library/AssignLate
  11. dos.library/AssignLock
  12. dos.library/AssignPath
  13. dos.library/AttemptLockDosList
  14. dos.library/ChangeMode
  15. dos.library/CheckSignal
  16. dos.library/Cli
  17. dos.library/CliInitNewcli
  18. dos.library/CliInitRun
  19. dos.library/Close
  20. dos.library/CompareDates
  21. dos.library/CreateDir
  22. dos.library/CreateNewProc
  23. dos.library/CreateProc
  24. dos.library/CurrentDir
  25. dos.library/DateStamp
  26. dos.library/DateToStr
  27. dos.library/Delay
  28. dos.library/DeleteFile
  29. dos.library/DeleteVar
  30. dos.library/DeviceProc
  31. dos.library/DoPkt
  32. dos.library/DupLock
  33. dos.library/DupLockFromFH
  34. dos.library/EndNotify
  35. dos.library/ErrorReport
  36. dos.library/ExAll
  37. dos.library/ExAllEnd
  38. dos.library/Examine
  39. dos.library/ExamineFH
  40. dos.library/Execute
  41. dos.library/Exit
  42. dos.library/ExNext
  43. dos.library/Fault
  44. dos.library/FGetC
  45. dos.library/FGets
  46. dos.library/FilePart
  47. dos.library/FindArg
  48. dos.library/FindCliProc
  49. dos.library/FindDosEntry
  50. dos.library/FindSegment
  51. dos.library/FindVar
  52. dos.library/Flush
  53. dos.library/Format
  54. dos.library/FPutC
  55. dos.library/FPuts
  56. dos.library/FRead
  57. dos.library/FreeArgs
  58. dos.library/FreeDeviceProc
  59. dos.library/FreeDosEntry
  60. dos.library/FreeDosObject
  61. dos.library/FWrite
  62. dos.library/GetArgStr
  63. dos.library/GetConsoleTask
  64. dos.library/GetCurrentDirName
  65. dos.library/GetDeviceProc
  66. dos.library/GetFileSysTask
  67. dos.library/GetProgramDir
  68. dos.library/GetProgramName
  69. dos.library/GetPrompt
  70. dos.library/GetVar
  71. dos.library/Info
  72. dos.library/Inhibit
  73. dos.library/Input
  74. dos.library/InternalLoadSeg
  75. dos.library/InternalUnLoadSeg
  76. dos.library/IoErr
  77. dos.library/IsFileSystem
  78. dos.library/IsInteractive
  79. dos.library/LoadSeg
  80. dos.library/Lock
  81. dos.library/LockDosList
  82. dos.library/LockRecord
  83. dos.library/LockRecords
  84. dos.library/MakeDosEntry
  85. dos.library/MakeLink
  86. dos.library/MatchEnd
  87. dos.library/MatchFirst
  88. dos.library/MatchNext
  89. dos.library/MatchPattern
  90. dos.library/MatchPatternNoCase
  91. dos.library/MaxCli
  92. dos.library/NameFromFH
  93. dos.library/NameFromLock
  94. dos.library/NewLoadSeg
  95. dos.library/NextDosEntry
  96. dos.library/Open
  97. dos.library/OpenFromLock
  98. dos.library/Output
  99. dos.library/ParentDir
  100. dos.library/ParentOfFH
  101. dos.library/ParsePattern
  102. dos.library/ParsePatternNoCase
  103. dos.library/PathPart
  104. dos.library/PrintFault
  105. dos.library/PutStr
  106. dos.library/Read
  107. dos.library/ReadArgs
  108. dos.library/ReadItem
  109. dos.library/ReadLink
  110. dos.library/Relabel
  111. dos.library/RemAssignList
  112. dos.library/RemDosEntry
  113. dos.library/RemSegment
  114. dos.library/Rename
  115. dos.library/ReplyPkt
  116. dos.library/RunCommand
  117. dos.library/SameDevice
  118. dos.library/SameLock
  119. dos.library/Seek
  120. dos.library/SelectInput
  121. dos.library/SelectOutput
  122. dos.library/SendPkt
  123. dos.library/SetArgStr
  124. dos.library/SetComment
  125. dos.library/SetConsoleTask
  126. dos.library/SetCurrentDirName
  127. dos.library/SetFileDate
  128. dos.library/SetFileSize
  129. dos.library/SetFileSysTask
  130. dos.library/SetIoErr
  131. dos.library/SetMode
  132. dos.library/SetOwner
  133. dos.library/SetProgramDir
  134. dos.library/SetProgramName
  135. dos.library/SetPrompt
  136. dos.library/SetProtection
  137. dos.library/SetVar
  138. dos.library/SetVBuf
  139. dos.library/SplitName
  140. dos.library/StartNotify
  141. dos.library/StrToDate
  142. dos.library/StrToLong
  143. dos.library/SystemTagList
  144. dos.library/UnGetC
  145. dos.library/UnLoadSeg
  146. dos.library/UnLock
  147. dos.library/UnLockDosList
  148. dos.library/UnLockRecord
  149. dos.library/UnLockRecords
  150. dos.library/VFPrintf
  151. dos.library/VFWritef
  152. dos.library/VPrintf
  153. dos.library/WaitForChar
  154. dos.library/WaitPkt
  155. dos.library/Write
  156. dos.library/WriteChars
  157. dos.library/AbortPkt                                     dos.library/AbortPkt
  158.  
  159.    NAME
  160.     AbortPkt -- Aborts an asynchronous packet, if possible. (V36)
  161.  
  162.    SYNOPSIS
  163.     AbortPkt(port, pkt)
  164.           D1    D2
  165.  
  166.     void AbortPkt(struct MsgPort *, struct DosPacket *)
  167.  
  168.    FUNCTION
  169.     This attempts to abort a packet sent earlier with SendPkt to a
  170.     handler.  There is no guarantee that any given handler will allow
  171.     a packet to be aborted, or if it is aborted whether function
  172.     requested completed first or completely.  After calling AbortPkt(),
  173.     you must wait for the packet to return before reusing it or
  174.     deallocating it.
  175.  
  176.    INPUTS
  177.     port - port the packet was sent to
  178.     pkt  - the packet you wish aborted
  179.  
  180.    BUGS
  181.     As of V37, this function does nothing.
  182.  
  183.    SEE ALSO
  184.     SendPkt(), DoPkt(), WaitPkt()
  185.  
  186. dos.library/AddBuffers                                 dos.library/AddBuffers
  187.  
  188.    NAME
  189.     AddBuffers -- Changes the number of buffers for a filesystem (V36)
  190.  
  191.    SYNOPSIS
  192.     success = AddBuffers(filesystem, number)
  193.     D0               D1          D2
  194.  
  195.     BOOL AddBuffers(STRPTR, LONG)
  196.  
  197.    FUNCTION
  198.     Adds buffers to a filesystem.  If it succeeds, the number of current
  199.     buffers is returned in IoErr().  Note that "number" may be negative.
  200.     The amount of memory used per buffer, and any limits on the number of
  201.     buffers, are dependant on the filesystem in question.
  202.     If the call succeeds, the number of buffers in use on the filesystem
  203.     will be returned by IoErr().
  204.  
  205.    INPUTS
  206.     filesystem - Name of device to add buffers to (with ':').
  207.     number     - Number of buffers to add.  May be negative.
  208.  
  209.    RESULT
  210.     success    - Success or failure of command.
  211.  
  212.    BUGS
  213.     The V36 ROM filesystem (FFS/OFS) doesn't return the right number of
  214.     buffers unless preceded by an AddBuffers(fs,-1) (in-use buffers aren't
  215.     counted).  This is fixed in V37.
  216.  
  217.     The V37 and before ROM filesystem doesn't return success, it returns
  218.     the number of buffers.  The best way to test for this is to consider
  219.     0 (FALSE) failure, -1 (DOSTRUE) to mean that IoErr() will have the
  220.     number of buffers, and any other positive value to be the number of
  221.     buffers.  It may be fixed in some future ROM revision.
  222.  
  223.    SEE ALSO
  224.     IoErr()
  225.  
  226. dos.library/AddDosEntry                               dos.library/AddDosEntry
  227.  
  228.    NAME
  229.     AddDosEntry -- Add a Dos List entry to the lists (V36)
  230.  
  231.    SYNOPSIS
  232.     success = AddDosEntry(dlist)
  233.     D0                     D1
  234.  
  235.     LONG AddDosEntry(struct DosList *)
  236.  
  237.    FUNCTION
  238.     Adds a device, volume or assign to the dos devicelist.  Can fail if it 
  239.     conflicts with an existing entry (such as another assign to the same
  240.     name or another device of the same name).  Volume nodes with different
  241.     dates and the same name CAN be added, or with names that conflict with
  242.     devices or assigns.  Note: the dos list does NOT have to be locked to
  243.     call this.  Do not access dlist after adding unless you have locked the
  244.     Dos Device list.
  245.  
  246.     An additional note concerning calling this from within a handler:
  247.     in order to avoid deadlocks, your handler must either be multi-
  248.     threaded, or it must attempt to lock the list before calling this
  249.     function.  The code would look something like this:
  250.  
  251.     if (AttemptLockDosList(LDF_xxx|LDF_WRITE))
  252.     {
  253.         rc = AddDosEntry(...);
  254.         UnLockDosList(LDF_xxx|LDF_WRITE);
  255.     }
  256.  
  257.     If AttemptLockDosList() fails (i.e. it's locked already), check for
  258.     messages at your filesystem port (don't wait!) and try the
  259.     AttemptLockDosList() again.
  260.  
  261.    INPUTS
  262.     dlist   - Device list entry to be added.
  263.  
  264.    RESULT
  265.     success - Success/Failure indicator
  266.  
  267.    SEE ALSO
  268.     RemDosEntry(), FindDosEntry(), NextDosEntry(), LockDosList(),
  269.     MakeDosEntry(), FreeDosEntry(), AttemptLockDosList()
  270.  
  271. dos.library/AddPart                                       dos.library/AddPart
  272.  
  273.    NAME
  274.     AddPart -- Appends a file/dir to the end of a path (V36)
  275.  
  276.    SYNOPSIS
  277.     success = AddPart( dirname, filename, size )
  278.     D0                   D1        D2      D3
  279.  
  280.     BOOL AddPart( STRPTR, STRPTR, ULONG )
  281.  
  282.    FUNCTION
  283.     This function adds a file, directory, or subpath name to a directory
  284.     path name taking into account any required separator characters.  If
  285.     filename is a fully-qualified path it will totally replace the current
  286.     value of dirname.
  287.  
  288.    INPUTS
  289.     dirname  - the path to add a file/directory name to.
  290.     filename - the filename or directory name to add.  May be a relative
  291.            pathname from the current directory (example: foo/bar).
  292.            Can deal with leading '/'(s), indicating one directory up
  293.            per '/', or with a ':', indicating it's relative to the
  294.            root of the appropriate volume.
  295.     size     - size in bytes of the space allocated for dirname.  Must
  296.            not be 0.
  297.  
  298.    RESULT
  299.     success - non-zero for ok, FALSE if the buffer would have overflowed.
  300.           If an overflow would have occured, dirname will not be
  301.           changed.
  302.  
  303.    BUGS
  304.     Doesn't check if a subpath is legal (i.e. doesn't check for ':'s) and
  305.     doesn't handle leading '/'s in 2.0 through 2.02 (V36).  V37 fixes
  306.     this, allowing filename to be any path, including absolute.
  307.  
  308.    SEE ALSO
  309.     Filepart(), PathPart()
  310.  
  311. dos.library/AddSegment                                 dos.library/AddSegment
  312.  
  313.    NAME
  314.     AddSegment - Adds a resident segment to the resident list (V36)
  315.  
  316.    SYNOPSIS
  317.     success = AddSegment(name, seglist, type)
  318.     D0              D1     D2      D3
  319.  
  320.     BOOL AddSegment(STRPTR, BPTR, LONG)
  321.  
  322.    FUNCTION
  323.     Adds a segment to the Dos resident list, with the specified Seglist
  324.     and type (stored in seg_UC - normally 0).  NOTE: currently unused
  325.     types may cause it to interpret other registers (d4-?) as additional
  326.     parameters in the future.
  327.  
  328.     Do NOT build Segment structures yourself!
  329.  
  330.    INPUTS
  331.     name    - name for the segment
  332.     seglist - Dos seglist of code for segment
  333.     type    - initial usecount, normally 0
  334.  
  335.    RESULT
  336.     success - success or failure
  337.  
  338.    SEE ALSO
  339.     FindSegment(), RemSegment(), LoadSeg()
  340.  
  341. dos.library/AllocDosObject                         dos.library/AllocDosObject
  342.  
  343.    NAME
  344.     AllocDosObject -- Creates a dos object (V36)
  345.  
  346.    SYNOPSIS
  347.     ptr = AllocDosObject(type, tags)
  348.     D0                    D1    D2
  349.  
  350.     void *AllocDosObject(ULONG, struct TagItem *)
  351.  
  352.     ptr = AllocDosObjectTagList(type, tags)
  353.     D0                          D1    D2
  354.  
  355.     void *AllocDosObjectTagList(ULONG, struct TagItem *)
  356.  
  357.     ptr = AllocDosObjectTags(type, Tag1, ...)
  358.  
  359.     void *AllocDosObjectTags(ULONG, ULONG, ...)
  360.  
  361.    FUNCTION
  362.     Create one of several dos objects, initializes it, and returns it
  363.     to you.  Note the DOS_STDPKT returns a pointer to the sp_Pkt of the
  364.     structure.
  365.  
  366.     This function may be called by a task for all types and tags defined
  367.     in the V37 includes (DOS_FILEHANDLE through DOS_RDARGS and ADO_FH_Mode
  368.     through ADO_PromptLen, respectively).  Any future types or tags
  369.     will be documented as to whether a task may use them.
  370.  
  371.    INPUTS
  372.     type - type of object requested
  373.     tags - pointer to taglist with additional information
  374.  
  375.    RESULT
  376.     packet - pointer to the object or NULL
  377.  
  378.    BUGS
  379.     Before V39, DOS_CLI should be used with care since FreeDosObject()
  380.     can't free it.
  381.  
  382.    SEE ALSO
  383.     FreeDosObject(), <dos/dostags.h>, <dos/dos.h>
  384.  
  385. dos.library/AssignAdd                                   dos.library/AssignAdd
  386.  
  387.    NAME
  388.     AssignAdd -- Adds a lock to an assign for multi-directory assigns (V36)
  389.  
  390.    SYNOPSIS
  391.     success = AssignAdd(name,lock)
  392.     D0                   D1   D2
  393.  
  394.     BOOL AssignAdd(STRPTR,BPTR)
  395.  
  396.    FUNCTION
  397.     Adds a lock to an assign, making or adding to a multi-directory
  398.     assign.  Note that this only will succeed on an assign created with
  399.     AssignLock(), or an assign created with AssignLate() which has been
  400.     resolved (converted into a AssignLock()-assign).
  401.  
  402.     NOTE: you should not use the lock in any way after making this call
  403.     successfully.  It becomes the part of the assign, and will be unlocked
  404.     by the system when the assign is removed.  If you need to keep the
  405.     lock, pass a lock from DupLock() to AssignLock().
  406.  
  407.    INPUTS
  408.     name - Name of device to assign lock to (without trailing ':')
  409.     lock - Lock associated with the assigned name
  410.  
  411.    RESULT
  412.     success - Success/failure indicator.  On failure, the lock is not
  413.           unlocked.
  414.  
  415.    SEE ALSO
  416.     Lock(), AssignLock(), AssignPath(), AssignLate(), DupLock(),
  417.     RemAssignList()
  418.  
  419. dos.library/AssignLate                                 dos.library/AssignLate
  420.  
  421.    NAME
  422.     AssignLate -- Creates an assignment to a specified path later (V36)
  423.  
  424.    SYNOPSIS
  425.     success = AssignLate(name,path)
  426.     D0                    D1   D2
  427.  
  428.     BOOL AssignLate(STRPTR,STRPTR)
  429.  
  430.    FUNCTION
  431.     Sets up a assignment that is expanded upon the FIRST reference to the
  432.     name.  The path (a string) would be attached to the node.  When
  433.     the name is referenced (Open("FOO:xyzzy"...), the string will be used
  434.     to determine where to set the assign to, and if the directory can be
  435.     locked, the assign will act from that point on as if it had been
  436.     created by AssignLock().
  437.  
  438.     A major advantage is assigning things to unmounted volumes, which
  439.     will be requested upon access (useful in startup sequences).
  440.  
  441.    INPUTS
  442.     name - Name of device to be assigned (without trailing ':')
  443.     path - Name of late assignment to be resolved on the first reference.
  444.  
  445.    RESULT
  446.     success - Success/failure indicator of the operation
  447.  
  448.    SEE ALSO
  449.     Lock(), AssignAdd(), AssignPath(), AssignLock(),
  450.  
  451. dos.library/AssignLock                                 dos.library/AssignLock
  452.  
  453.    NAME
  454.     AssignLock -- Creates an assignment to a locked object (V36)
  455.  
  456.    SYNOPSIS
  457.     success = AssignLock(name,lock)
  458.     D0                    D1   D2
  459.  
  460.     BOOL AssignLock(STRPTR,BPTR)
  461.  
  462.    FUNCTION
  463.     Sets up an assign of a name to a given lock.  Passing NULL for a lock 
  464.     cancels any outstanding assign to that name.  If an assign entry of
  465.     that name is already on the list, this routine replaces that entry.  If
  466.     an entry is on the list that conflicts with the new assign, then a
  467.     failure code is returned.
  468.  
  469.     NOTE: you should not use the lock in any way after making this call
  470.     successfully.  It becomes the assign, and will be unlocked by the
  471.     system when the assign is removed.  If you need to keep the lock,
  472.     pass a lock from DupLock() to AssignLock().
  473.  
  474.    INPUTS
  475.     name - Name of device to assign lock to (without trailing ':')
  476.     lock - Lock associated with the assigned name
  477.  
  478.    RESULT
  479.     success - Success/failure indicator.  On failure, the lock is not
  480.           unlocked.
  481.  
  482.    SEE ALSO
  483.     Lock(), AssignAdd(), AssignPath(), AssignLate(), DupLock(),
  484.     RemAssignList()
  485.  
  486. dos.library/AssignPath                                 dos.library/AssignPath
  487.  
  488.    NAME
  489.     AssignPath -- Creates an assignment to a specified path (V36)
  490.  
  491.    SYNOPSIS
  492.     success = AssignPath(name,path)
  493.     D0                    D1   D2
  494.  
  495.     BOOL AssignPath(STRPTR,STRPTR)
  496.  
  497.    FUNCTION
  498.     Sets up a assignment that is expanded upon EACH reference to the name.
  499.     This is implemented through a new device list type (DLT_ASSIGNPATH, or
  500.     some such).  The path (a string) would be attached to the node.  When
  501.     the name is referenced (Open("FOO:xyzzy"...), the string will be used
  502.     to determine where to do the open.  No permanent lock will be part of
  503.     it.  For example, you could AssignPath() c2: to df2:c, and references
  504.     to c2: would go to df2:c, even if you change disks.
  505.  
  506.     The other major advantage is assigning things to unmounted volumes,
  507.     which will be requested upon access (useful in startup sequences).
  508.  
  509.    INPUTS
  510.     name - Name of device to be assigned (without trailing ':')
  511.     path - Name of late assignment to be resolved at each reference
  512.  
  513.    RESULT
  514.     success - Success/failure indicator of the operation
  515.  
  516.    SEE ALSO
  517.     AssignAdd(), AssignLock(), AssignLate(), Open()
  518.  
  519. dos.library/AttemptLockDosList                 dos.library/AttemptLockDosList
  520.  
  521.    NAME
  522.     AttemptLockDosList -- Attempt to lock the Dos Lists for use (V36)
  523.  
  524.    SYNOPSIS
  525.     dlist = AttemptLockDosList(flags)
  526.     D0                D1
  527.  
  528.     struct DosList *AttemptLockDosList(ULONG)
  529.  
  530.    FUNCTION
  531.     Locks the dos device list in preparation to walk the list.  If the
  532.     list is 'busy' then this routine will return NULL.  See LockDosList()
  533.     for more information.
  534.  
  535.    INPUTS
  536.     flags - Flags stating which types of nodes you want to lock.
  537.  
  538.    RESULT
  539.     dlist - Pointer to the beginning of the list or NULL.  Not a valid
  540.         node!
  541.  
  542.    BUGS
  543.     In V36 through V39.23 dos, this would return NULL or 0x00000001 for
  544.     failure.  Fixed in V39.24 dos (after kickstart 39.106).
  545.  
  546.    SEE ALSO
  547.     LockDosList(), UnLockDosList(), Forbid(), NextDosEntry()
  548.  
  549. dos.library/ChangeMode                                 dos.library/ChangeMode
  550.  
  551.    NAME
  552.     ChangeMode - Change the current mode of a lock or filehandle (V36)
  553.  
  554.    SYNOPSIS
  555.     success = ChangeMode(type, object, newmode)
  556.     D0                    D1     D2      D3
  557.  
  558.     BOOL ChangeMode(ULONG, BPTR, ULONG)
  559.  
  560.    FUNCTION
  561.     This allows you to attempt to change the mode in use by a lock or
  562.     filehandle.  For example, you could attempt to turn a shared lock
  563.     into an exclusive lock.  The handler may well reject this request.
  564.     Warning: if you use the wrong type for the object, the system may
  565.     crash.
  566.  
  567.    INPUTS
  568.     type    - Either CHANGE_FH or CHANGE_LOCK
  569.     object  - A lock or filehandle
  570.     newmode - The new mode you want
  571.  
  572.    RESULT
  573.     success - Boolean
  574.  
  575.    BUGS
  576.     Did not work in 2.02 or before (V36).  Works in V37.  In the
  577.     earlier versions, it can crash the machine.
  578.  
  579.    SEE ALSO
  580.     Lock(), Open()
  581.  
  582. dos.library/CheckSignal                               dos.library/CheckSignal
  583.  
  584.    NAME
  585.     CheckSignal -- Checks for break signals (V36)
  586.  
  587.    SYNOPSIS
  588.     signals = CheckSignal(mask)
  589.     D0              D1
  590.  
  591.     ULONG CheckSignal(ULONG)
  592.  
  593.    FUNCTION
  594.     This function checks to see if any signals specified in the mask have
  595.     been set and if so, returns them.  Otherwise it returns FALSE.
  596.     All signals specified in mask will be cleared.
  597.  
  598.    INPUTS
  599.     mask    - Signals to check for.
  600.  
  601.    RESULT
  602.     signals - Signals specified in mask that were set.
  603.  
  604.    SEE ALSO
  605.  
  606. dos.library/Cli                                               dos.library/Cli
  607.  
  608.    NAME
  609.     Cli -- Returns a pointer to the CLI structure of the process (V36)
  610.  
  611.    SYNOPSIS
  612.     cli_ptr = Cli()
  613.     D0
  614.  
  615.     struct CommandLineInterface *Cli(void)
  616.  
  617.    FUNCTION
  618.     Returns a pointer to the CLI structure of the current process, or NULL
  619.     if the process has no CLI structure.
  620.  
  621.    RESULT
  622.     cli_ptr - pointer to the CLI structure, or NULL.
  623.  
  624.    SEE ALSO
  625.  
  626. dos.library/CliInitNewcli                           dos.library/CliInitNewcli
  627.  
  628.    NAME
  629.     CliInitNewcli -- Set up a process to be a shell from initial packet
  630.  
  631.    SYNOPSIS
  632.     flags = CliInitNewcli( packet )
  633.     D0                 A0
  634.  
  635.     LONG CliInitNewcli( struct DosPacket * )
  636.  
  637.    FUNCTION
  638.     This function initializes a process and CLI structure for a new
  639.     shell, from parameters in an initial packet passed by the system
  640.     (NewShell or NewCLI, etc).  The format of the data in the packet
  641.     is purposely not defined.  The setup includes all the normal fields
  642.     in the structures that are required for proper operation (current
  643.     directory, paths, input streams, etc).
  644.  
  645.     It returns a set of flags containing information about what type
  646.     of shell invocation this is.
  647.  
  648.     Definitions for the values of fn:
  649.         Bit 31     Set to indicate flags are valid
  650.         Bit  3     Set to indicate asynch system call
  651.         Bit  2     Set if this is a System() call
  652.         Bit  1     Set if user provided input stream
  653.         Bit  0     Set if RUN provided output stream
  654.  
  655.     If Bit 31 is 0, then you must check IoErr() to determine if an error
  656.     occurred.  If IoErr() returns a pointer to your process, there has
  657.     been an error, and you should clean up and exit.  The packet will
  658.     have already been returned by CliInitNewcli().  If it isn't a pointer
  659.     to your process and Bit 31 is 0, reply the packet immediately.
  660.     (Note: this is different from what you do for CliInitRun().)
  661.  
  662.     This function is very similar to CliInitRun().
  663.  
  664.    INPUTS
  665.     packet - the initial packet sent to your process MsgPort
  666.  
  667.    RESULT
  668.     fn - flags or a pointer
  669.  
  670.    SEE ALSO
  671.     CliInitRun(), ReplyPkt(), WaitPkt(), IoErr()
  672.  
  673. dos.library/CliInitRun                                 dos.library/CliInitRun
  674.  
  675.    NAME
  676.     CliInitRun -- Set up a process to be a shell from initial packet
  677.  
  678.    SYNOPSIS
  679.     flags = CliInitRun( packet )
  680.     D0              A0
  681.  
  682.     LONG CliInitRun( struct DosPacket * )
  683.  
  684.    FUNCTION
  685.     This function initializes a process and CLI structure for a new
  686.     shell, from parameters in an initial packet passed by the system
  687.     (Run, System(), Execute()).  The format of the data in the packet
  688.     is purposely not defined.  The setup includes all the normal fields
  689.     in the structures that are required for proper operation (current
  690.     directory, paths, input streams, etc).
  691.  
  692.     It returns a set of flags containing information about what type
  693.     of shell invocation this is.
  694.  
  695.     Definitions for the values of fn:
  696.         Bit 31     Set to indicate flags are valid
  697.         Bit  3     Set to indicate asynch system call
  698.         Bit  2     Set if this is a System() call
  699.         Bit  1     Set if user provided input stream
  700.         Bit  0     Set if RUN provided output stream
  701.  
  702.     If Bit 31 is 0, then you must check IoErr() to determine if an error
  703.     occurred.  If IoErr() returns a pointer to your process, there has
  704.     been an error, and you should clean up and exit.  The packet will
  705.     have already been returned by CliInitNewcli().  If it isn't a pointer
  706.     to your process and Bit 31 is 0, you should wait before replying
  707.     the packet until after you've loaded the first command (or when you
  708.     exit).  This helps avoid disk "gronking" with the Run command.
  709.     (Note: this is different from what you do for CliInitNewcli().)
  710.  
  711.     If Bit 31 is 1, then if Bit 3 is one, ReplyPkt() the packet
  712.     immediately (Asynch System()), otherwise wait until your shell exits
  713.     (Sync System(), Execute()).
  714.     (Note: this is different from what you do for CliInitNewcli().)
  715.     
  716.     This function is very similar to CliInitNewcli().
  717.  
  718.    INPUTS
  719.     packet - the initial packet sent to your process MsgPort
  720.  
  721.    RESULT
  722.     fn - flags or a pointer
  723.  
  724.    SEE ALSO
  725.     CliInitNewcli(), ReplyPkt(), WaitPkt(), System(), Execute(), IoErr()
  726.  
  727. dos.library/Close                                           dos.library/Close
  728.  
  729.     NAME
  730.     Close -- Close an open file
  731.  
  732.     SYNOPSIS
  733.     success = Close( file )
  734.        D0             D1
  735.  
  736.     BOOL Close(BPTR)
  737.  
  738.     FUNCTION
  739.     The file specified by the file handle is closed. You must close all
  740.     files you explicitly opened, but you must not close inherited file
  741.     handles that are passed to you (each filehandle must be closed once
  742.     and ONLY once).  If Close() fails, the file handle is still
  743.     deallocated and should not be used.
  744.  
  745.     INPUTS
  746.     file - BCPL pointer to a file handle
  747.  
  748.     RESULTS
  749.     success - returns if Close() succeeded.  Note that it might fail
  750.           depending on buffering and whatever IO must be done to
  751.           close a file being written to.  NOTE: this return value
  752.           did not exist before V36! 
  753.  
  754.     SEE ALSO
  755.     Open(), OpenFromLock()
  756.  
  757. dos.library/CompareDates                             dos.library/CompareDates
  758.  
  759.    NAME
  760.     CompareDates -- Compares two datestamps (V36)
  761.  
  762.    SYNOPSIS
  763.     result = CompareDates(date1,date2)
  764.     D0                     D1     D2
  765.  
  766.     LONG CompareDates(struct DateStamp *,struct DateStamp *)
  767.  
  768.    FUNCTION
  769.     Compares two times for relative magnitide.  <0 is returned if date1 is
  770.     later than date2, 0 if they are equal, or >0 if date2 is later than
  771.     date1.  NOTE: this is NOT the same ordering as strcmp!
  772.  
  773.    INPUTS
  774.     date1, date2 - DateStamps to compare
  775.  
  776.    RESULT
  777.     result -  <0, 0, or >0 based on comparison of two date stamps
  778.  
  779.    SEE ALSO
  780.     DateStamp(), DateToStr(), StrToDate()
  781.  
  782. dos.library/CreateDir                                   dos.library/CreateDir
  783.  
  784.     NAME
  785.     CreateDir -- Create a new directory
  786.  
  787.     SYNOPSIS
  788.     lock = CreateDir( name )
  789.     D0          D1
  790.  
  791.     BPTR CreateDir(STRPTR)
  792.  
  793.     FUNCTION
  794.     CreateDir creates a new directory with the specified name. An error
  795.     is returned if it fails.  Directories can only be created on
  796.     devices which support them, e.g. disks.  CreateDir returns an
  797.     exclusive lock on the new directory if it succeeds.
  798.  
  799.     INPUTS
  800.     name - pointer to a null-terminated string
  801.  
  802.     RESULTS
  803.     lock - BCPL pointer to a lock or NULL for failure.
  804.  
  805.     SEE ALSO
  806.     Lock(), UnLock()
  807.  
  808. dos.library/CreateNewProc                           dos.library/CreateNewProc
  809.  
  810.    NAME
  811.     CreateNewProc -- Create a new process (V36)
  812.  
  813.    SYNOPSIS
  814.     process = CreateNewProc(tags)
  815.     D0                       D1
  816.  
  817.     struct Process *CreateNewProc(struct TagItem *)
  818.  
  819.     process = CreateNewProcTagList(tags)
  820.     D0                           D1
  821.  
  822.     struct Process *CreateNewProcTagList(struct TagItem *)
  823.  
  824.     process = CreateNewProcTags(Tag1, ...)
  825.  
  826.     struct Process *CreateNewProcTags(ULONG, ...)
  827.  
  828.    FUNCTION
  829.     This creates a new process according to the tags passed in.  See
  830.     dos/dostags.h for the tags.
  831.  
  832.     You must specify one of NP_Seglist or NP_Entry.  NP_Seglist takes a
  833.     seglist (as returned by LoadSeg()).  NP_Entry takes a function
  834.     pointer for the routine to call.
  835.  
  836.     There are many options, as you can see by examining dos/dostags.h.
  837.     The defaults are for a non-CLI process, with copies of your
  838.     CurrentDir, HomeDir (used for PROGDIR:), priority, consoletask,
  839.     windowptr, and variables.  The input and output filehandles default
  840.     to opens of NIL:, stack to 4000, and others as shown in dostags.h.
  841.     This is a fairly reasonable default setting for creating threads,
  842.     though you may wish to modify it (for example, to give a descriptive
  843.     name to the process.)
  844.  
  845.     CreateNewProc() is callable from a task, though any actions that
  846.     require doing Dos I/O (DupLock() of currentdir, for example) will not
  847.     occur.
  848.  
  849.     NOTE: if you call CreateNewProc() with both NP_Arguments, you must
  850.     not specify an NP_Input of NULL.  When NP_Arguments is specified, it
  851.     needs to modify the input filehandle to make ReadArgs() work properly.
  852.  
  853.    INPUTS
  854.     tags - a pointer to a TagItem array.
  855.  
  856.    RESULT
  857.     process - The created process, or NULL.  Note that if it returns
  858.           NULL, you must free any items that were passed in via
  859.           tags, such as if you passed in a new current directory
  860.           with NP_CurrentDir.
  861.  
  862.    BUGS
  863.     In V36, NP_Arguments was broken in a number of ways, and probably
  864.     should be avoided (instead you should start a small piece of your
  865.     own code, which calls RunCommand() to run the actual code you wish
  866.     to run).  In V37, NP_Arguments works, though see the note above.
  867.  
  868.    SEE ALSO
  869.     LoadSeg(), CreateProc(), ReadArgs(), RunCommand(), <dos/dostags.h>
  870.  
  871. dos.library/CreateProc                                 dos.library/CreateProc
  872.  
  873.     NAME
  874.  
  875.     CreateProc -- Create a new process
  876.  
  877.     SYNOPSIS
  878.     process = CreateProc( name, pri, seglist, stackSize )
  879.     D0              D1    D2     D3      D4
  880.  
  881.     struct MsgPort *CreateProc(STRPTR, LONG, BPTR, LONG)
  882.  
  883.     FUNCTION
  884.     CreateProc() creates a new AmigaDOS process of name 'name'.  AmigaDOS
  885.     processes are a superset of exec tasks.
  886.  
  887.     A seglist, as returned by LoadSeg(), is passed as 'seglist'.
  888.     This represents a section of code which is to be run as a new
  889.     process. The code is entered at the first hunk in the segment list,
  890.     which should contain suitable initialization code or a jump to
  891.     such.  A process control structure is allocated from memory and
  892.     initialized.  If you wish to fake a seglist (that will never
  893.     have DOS UnLoadSeg() called on it), use this code:
  894.  
  895.             DS.L    0    ;Align to longword
  896.             DC.L    16    ;Segment "length" (faked)
  897.             DC.L    0    ;Pointer to next segment
  898.             ...start of code...
  899.  
  900.     The size of the root stack upon activation is passed as
  901.     'stackSize'.  'pri' specifies the required priority of the new
  902.     process.  The result will be the process msgport address of the new
  903.     process, or zero if the routine failed.  The argument 'name'
  904.     specifies the new process name.  A zero return code indicates
  905.     error.
  906.  
  907.     The seglist passed to CreateProc() is not freed when it exits; it
  908.     is up to the parent process to free it, or for the code to unload
  909.     itself.
  910.  
  911.     Under V36 and later, you probably should use CreateNewProc() instead.
  912.  
  913.     INPUTS
  914.     name      - pointer to a null-terminated string
  915.     pri       - signed long (range -128 to +127)
  916.     seglist   - BCPL pointer to a seglist
  917.     stackSize - integer (must be a multiple of 4 bytes)
  918.  
  919.     RESULTS
  920.     process   - pointer to new process msgport
  921.  
  922.     SEE ALSO
  923.     CreateNewProc(), LoadSeg(), UnLoadSeg()
  924.  
  925. dos.library/CurrentDir                                 dos.library/CurrentDir
  926.  
  927.     NAME
  928.     CurrentDir -- Make a directory lock the current directory
  929.  
  930.     SYNOPSIS
  931.     oldLock = CurrentDir( lock )
  932.     D0              D1
  933.  
  934.     BPTR CurrentDir(BPTR)
  935.  
  936.     FUNCTION
  937.     CurrentDir() causes a directory associated with a lock to be made
  938.     the current directory.    The old current directory lock is returned.
  939.  
  940.     A value of zero is a valid result here, this 0 lock represents the
  941.     root of file system that you booted from.
  942.  
  943.     Any call that has to Open() or Lock() files (etc) requires that
  944.     the current directory be a valid lock or 0.
  945.  
  946.     INPUTS
  947.     lock - BCPL pointer to a lock
  948.  
  949.     RESULTS
  950.     oldLock - BCPL pointer to a lock
  951.  
  952.     SEE ALSO
  953.     Lock(), UnLock(), Open(), DupLock()
  954.  
  955. dos.library/DateStamp                                   dos.library/DateStamp
  956.  
  957.     NAME
  958.     DateStamp -- Obtain the date and time in internal format
  959.  
  960.     SYNOPSIS
  961.     ds = DateStamp( ds );
  962.     D0        D1
  963.  
  964.     struct DateStamp *DateStamp(struct DateStamp *)
  965.  
  966.     FUNCTION
  967.     DateStamp() takes a structure of three longwords that is set to the
  968.     current time.  The first element in the vector is a count of the
  969.     number of days.  The second element is the number of minutes elapsed
  970.     in the day.  The third is the number of ticks elapsed in the current
  971.     minute.  A tick happens 50 times a second.  DateStamp() ensures that
  972.     the day and minute are consistent.  All three elements are zero if
  973.     the date is unset. DateStamp() currently only returns even
  974.     multiples of 50 ticks.  Therefore the time you get is always an even
  975.     number of ticks.
  976.  
  977.     Time is measured from Jan 1, 1978.
  978.  
  979.     INPUTS
  980.     ds - pointer a struct DateStamp
  981.  
  982.     RESULTS
  983.     The array is filled as described and returned (for pre-V36 
  984.     compabability).
  985.  
  986.     SEE ALSO
  987.     DateToStr(), StrToDate(), SetFileDate(), CompareDates()
  988.  
  989. dos.library/DateToStr                                   dos.library/DateToStr
  990.  
  991.    NAME
  992.     DateToStr -- Converts a DateStamp to a string (V36)
  993.  
  994.    SYNOPSIS
  995.     success = DateToStr( datetime )
  996.     D0                      D1
  997.  
  998.     BOOL DateToStr(struct DateTime *)
  999.  
  1000.    FUNCTION
  1001.     StamptoStr converts an AmigaDOS DateStamp to a human
  1002.     readable ASCII string as requested by your settings in the
  1003.     DateTime structure.
  1004.  
  1005.    INPUTS
  1006.     DateTime - a pointer to an initialized DateTime structure.
  1007.  
  1008.     The DateTime structure should be initialized as follows:
  1009.  
  1010.     dat_Stamp - a copy of the datestamp you wish to convert to
  1011.           ascii.
  1012.  
  1013.     dat_Format - a format    byte which specifies the format    of the
  1014.           dat_StrDate.    This can be any    of the following
  1015.           (note: If value used is something other than those
  1016.           below, the default of    FORMAT_DOS is used):
  1017.  
  1018.           FORMAT_DOS:      AmigaDOS format (dd-mmm-yy).
  1019.  
  1020.           FORMAT_INT:      International    format (yy-mmm-dd).
  1021.  
  1022.           FORMAT_USA:      American format (mm-dd-yy).
  1023.  
  1024.           FORMAT_CDN:      Canadian format (dd-mm-yy).
  1025.  
  1026.           FORMAT_DEF:      default format for locale.
  1027.  
  1028.     dat_Flags - a    flags byte.  The only flag which affects this
  1029.           function is:
  1030.  
  1031.           DTF_SUBST:      If set, a string such    as Today,
  1032.                   Monday, etc.,    will be    used instead
  1033.                   of the dat_Format specification if
  1034.                   possible.
  1035.           DTF_FUTURE:      Ignored by this function.
  1036.  
  1037.     dat_StrDay - pointer to a buffer to receive the day of the
  1038.           week string.    (Monday, Tuesday, etc.). If null, this
  1039.           string will not be generated.
  1040.  
  1041.     dat_StrDate -    pointer    to a buffer to receive the date
  1042.           string, in the format    requested by dat_Format,
  1043.           subject to possible modifications by DTF_SUBST.  If
  1044.           null,    this string will not be    generated.
  1045.  
  1046.     dat_StrTime -    pointer    to a buffer to receive the time    of day
  1047.           string. If NULL, this    will not be generated.
  1048.  
  1049.    RESULT
  1050.     success    - a zero return indicates that the DateStamp was
  1051.           invalid, and could not be converted.    Non-zero
  1052.           indicates that the call succeeded.
  1053.  
  1054.    SEE ALSO
  1055.     DateStamp(), StrtoDate(), <dos/datetime.h>
  1056.  
  1057. dos.library/Delay                                           dos.library/Delay
  1058.  
  1059.     NAME
  1060.     Delay -- Delay a process for a specified time
  1061.  
  1062.     SYNOPSIS
  1063.     Delay( ticks )
  1064.            D1
  1065.  
  1066.     void Delay(ULONG)
  1067.  
  1068.     FUNCTION
  1069.     The argument 'ticks' specifies how many ticks (50 per second) to
  1070.     wait before returning control.
  1071.  
  1072.     INPUTS
  1073.     ticks - integer
  1074.  
  1075.     BUGS
  1076.     Due to a bug in the timer.device in V1.2/V1.3, specifying a timeout
  1077.     of zero for Delay() can cause the unreliable timer & floppy disk
  1078.     operation.  This is fixed in V36 and later.
  1079.  
  1080.     SEE ALSO
  1081.  
  1082. dos.library/DeleteFile                                 dos.library/DeleteFile
  1083.  
  1084.     NAME
  1085.     DeleteFile -- Delete a file or directory
  1086.  
  1087.     SYNOPSIS
  1088.     success = DeleteFile( name )
  1089.     D0              D1
  1090.  
  1091.     BOOL DeleteFile(STRPTR)
  1092.  
  1093.     FUNCTION
  1094.     This attempts to delete the file or directory specified by 'name'.
  1095.     An error is returned if the deletion fails. Note that all the files
  1096.     within a directory must be deleted before the directory itself can
  1097.     be deleted.
  1098.  
  1099.     INPUTS
  1100.     name - pointer to a null-terminated string
  1101.  
  1102.     RESULTS
  1103.     success - boolean
  1104.  
  1105.     SEE ALSO
  1106.  
  1107. dos.library/DeleteVar                                   dos.library/DeleteVar
  1108.  
  1109.    NAME
  1110.     DeleteVar -- Deletes a local or environment variable (V36)
  1111.  
  1112.    SYNOPSIS
  1113.     success = DeleteVar( name, flags ) 
  1114.     D0              D1    D2
  1115.  
  1116.     BOOL DeleteVar(STRPTR, ULONG ) 
  1117.  
  1118.    FUNCTION
  1119.     Deletes a local or environment variable.
  1120.  
  1121.    INPUTS
  1122.     name   - pointer to an variable name.  Note variable names follow
  1123.          filesystem syntax and semantics.
  1124.     flags  - combination of type of var to delete (low 8 bits), and
  1125.          flags to control the behavior of this routine.  Currently
  1126.          defined flags include:
  1127.  
  1128.          GVF_LOCAL_ONLY  - delete a local (to your process) variable.
  1129.          GVF_GLOBAL_ONLY - delete a global environment variable.
  1130.  
  1131.          The default is to delete a local variable if found, otherwise
  1132.          a global environment variable if found (only for LV_VAR).
  1133.  
  1134.    RESULT
  1135.     success - If non-zero, the variable was sucessfully deleted, FALSE
  1136.           indicates failure.
  1137.  
  1138.    BUGS
  1139.     LV_VAR is the only type that can be global
  1140.  
  1141.    SEE ALSO
  1142.     GetVar(), SetVar(), FindVar(), DeleteFile(), <dos/var.h>
  1143.  
  1144. dos.library/DeviceProc                                 dos.library/DeviceProc
  1145.  
  1146.     NAME
  1147.     DeviceProc -- Return the process MsgPort of specific I/O handler
  1148.  
  1149.     SYNOPSIS
  1150.     process = DeviceProc( name )
  1151.     D0              D1
  1152.  
  1153.     struct MsgPort *DeviceProc (STRPTR)
  1154.  
  1155.     FUNCTION
  1156.     DeviceProc() returns the process identifier of the process which
  1157.     handles the device associated with the specified name. If no
  1158.     process handler can be found then the result is zero. If the name
  1159.     refers to an assign then a directory lock is returned in IoErr().
  1160.     This lock should not be UnLock()ed or Examine()ed (if you wish to do
  1161.     so, DupLock() it first).
  1162.  
  1163.     BUGS
  1164.     In V36, if you try to DeviceProc() something relative to an assign
  1165.     made with AssignPath(), it will fail.  This is because there's no
  1166.     way to know when to unlock the lock.  If you're writing code for
  1167.     V36 or later, it is highly advised you use GetDeviceProc() instead,
  1168.     or make your code conditional on V36 to use GetDeviceProc()/
  1169.     FreeDeviceProc().
  1170.  
  1171.     SEE ALSO
  1172.     GetDeviceProc(), FreeDeviceProc(), DupLock(), UnLock(), Examine()
  1173.  
  1174. dos.library/DoPkt                                           dos.library/DoPkt
  1175.  
  1176.    NAME
  1177.     DoPkt -- Send a dos packet and wait for reply (V36)
  1178.  
  1179.    SYNOPSIS
  1180.     result1 = DoPkt(port,action,arg1,arg2,arg3,arg4,arg5)
  1181.     D0               D1    D2    D3   D4   D5   D6   D7
  1182.  
  1183.     LONG DoPkt(struct MsgPort *,LONG,LONG,LONG,LONG,LONG,LONG)
  1184.  
  1185.    FUNCTION
  1186.     Sends a packet to a handler and waits for it to return.  Any secondary
  1187.     return will be available in D1 AND from IoErr().  DoPkt() will work
  1188.     even if the caller is an exec task and not a process; however it will
  1189.     be slower, and may fail for some additional reasons, such as being
  1190.     unable to allocate a signal.  DoPkt() uses your pr_MsgPort for the
  1191.     reply, and will call pr_PktWait.  (See BUGS regarding tasks, though).
  1192.  
  1193.     Only allows 5 arguments to be specified.  For more arguments (packets
  1194.     support a maximum of 7) create a packet and use SendPkt()/WaitPkt().
  1195.  
  1196.    INPUTS
  1197.     port    - pr_MsgPort of the handler process to send to.
  1198.     action  - the action requested of the filesystem/handler
  1199.     arg1, arg2, arg3, arg4,arg5 - arguments, depend on the action, may not
  1200.            be required.
  1201.  
  1202.    RESULT
  1203.     result1 - the value returned in dp_Res1, or FALSE if there was some
  1204.           problem in sending the packet or recieving it.
  1205.     result2 - Available from IoErr() AND in register D1.
  1206.  
  1207.    BUGS
  1208.     Using DoPkt() from tasks doesn't work in V36. Use AllocDosObject(),
  1209.     PutMsg(), and WaitPort()/GetMsg() for a workaround, or you can call
  1210.     CreateNewProc() to start a process to do Dos I/O for you.  In V37,
  1211.     DoPkt() will allocate, use, and free the MsgPort required.
  1212.  
  1213.    NOTES
  1214.     Callable from a task (under V37 and above).
  1215.  
  1216.    SEE ALSO
  1217.     AllocDosObject(), FreeDosObject(), SendPkt(), WaitPkt(),
  1218.     CreateNewProc(), AbortPkt()
  1219.  
  1220. dos.library/DupLock                                       dos.library/DupLock
  1221.  
  1222.     NAME
  1223.     DupLock -- Duplicate a lock
  1224.  
  1225.     SYNOPSIS
  1226.     lock = DupLock( lock )
  1227.     D0        D1
  1228.  
  1229.     BPTR DupLock(BPTR)
  1230.  
  1231.     FUNCTION
  1232.     DupLock() is passed a shared filing system lock.  This is the ONLY
  1233.     way to obtain a duplicate of a lock... simply copying is not
  1234.     allowed.
  1235.  
  1236.     Another lock to the same object is then returned.  It is not
  1237.     possible to create a copy of a exclusive lock.
  1238.  
  1239.     A zero return indicates failure.
  1240.  
  1241.     INPUTS
  1242.     lock - BCPL pointer to a lock
  1243.  
  1244.     RESULTS
  1245.     newLock - BCPL pointer to a lock
  1246.  
  1247.     SEE ALSO
  1248.     Lock(), UnLock(), DupLockFromFH(), ParentOfFH()
  1249.  
  1250. dos.library/DupLockFromFH                           dos.library/DupLockFromFH
  1251.  
  1252.    NAME
  1253.     DupLockFromFH -- Gets a lock on an open file (V36)
  1254.  
  1255.    SYNOPSIS
  1256.     lock = DupLockFromFH(fh)
  1257.     D0                   D1
  1258.  
  1259.     BPTR DupLockFromFH(BPTR)
  1260.  
  1261.    FUNCTION
  1262.     Obtain a lock on the object associated with fh.  Only works if the
  1263.     file was opened using a non-exclusive mode.  Other restrictions may be
  1264.     placed on success by the filesystem.
  1265.  
  1266.    INPUTS
  1267.     fh   - Opened file for which to obtain the lock
  1268.  
  1269.    RESULT
  1270.     lock - Obtained lock or NULL for failure
  1271.  
  1272.    SEE ALSO
  1273.     DupLock(), Lock(), UnLock()
  1274.  
  1275. dos.library/EndNotify                                   dos.library/EndNotify
  1276.  
  1277.    NAME
  1278.     EndNotify -- Ends a notification request (V36)
  1279.  
  1280.    SYNOPSIS
  1281.     EndNotify(notifystructure)
  1282.             D1
  1283.  
  1284.     VOID EndNotify(struct NotifyRequest *)
  1285.  
  1286.    FUNCTION
  1287.     Removes a notification request.  Safe to call even if StartNotify()
  1288.     failed.  For NRF_SEND_MESSAGE, it searches your port for any messages
  1289.     about the object in question and removes and replies them before
  1290.     returning.
  1291.  
  1292.    INPUTS
  1293.     notifystructure - a structure passed to StartNotify()
  1294.  
  1295.    SEE ALSO
  1296.     StartNotify(), <dos/notify.h>
  1297.  
  1298. dos.library/ErrorReport                               dos.library/ErrorReport
  1299.  
  1300.    NAME
  1301.     ErrorReport -- Displays a Retry/Cancel requester for an error (V36)
  1302.  
  1303.    SYNOPSIS
  1304.     status = ErrorReport(code, type, arg1, device)
  1305.     D0                    D1    D2    D3     D4
  1306.  
  1307.     BOOL ErrorReport(LONG, LONG, ULONG, struct MsgPort *)
  1308.  
  1309.    FUNCTION
  1310.     Based on the request type, this routine formats the appropriate
  1311.     requester to be displayed.  If the code is not understood, it returns
  1312.     DOS_TRUE immediately.  Returns DOS_TRUE if the user selects CANCEL or
  1313.     if the attempt to put up the requester fails, or if the process
  1314.     pr_WindowPtr is -1.  Returns FALSE if the user selects Retry.  The
  1315.     routine will retry on DISKINSERTED for appropriate error codes.
  1316.     These return values are the opposite of what AutoRequest returns.
  1317.  
  1318.     Note: this routine sets IoErr() to code before returning.
  1319.  
  1320.    INPUTS
  1321.     code   - Error code to put a requester up for.
  1322.        Current valid error codes are:
  1323.         ERROR_DISK_NOT_VALIDATED
  1324.         ERROR_DISK_WRITE_PROTECTED
  1325.         ERROR_DISK_FULL
  1326.         ERROR_DEVICE_NOT_MOUNTED
  1327.         ERROR_NOT_A_DOS_DISK
  1328.         ERROR_NO_DISK
  1329.         ABORT_DISK_ERROR    /* read/write error */
  1330.         ABORT_BUSY        /* you MUST replace... */
  1331.     type   - Request type:
  1332.                        REPORT_LOCK   - arg1 is a lock (BPTR).
  1333.                        REPORT_FH     - arg1 is a filehandle (BPTR).
  1334.             REPORT_VOLUME - arg1 is a volumenode (C pointer).
  1335.             REPORT_INSERT - arg1 is the string for the volumename
  1336.                     (will be split on a ':').
  1337.                     With ERROR_DEVICE_NOT_MOUNTED puts
  1338.                     up the "Please insert..." requester.
  1339.     arg1   - variable parameter (see type)
  1340.     device - (Optional) Address of handler task for which report is to be 
  1341.                 made.  Only required for REPORT_LOCK, and only if arg1==NULL.
  1342.  
  1343.    RESULT
  1344.     status - Cancel/Retry indicator (0 means Retry)
  1345.  
  1346.    SEE ALSO
  1347.     Fault(), IoErr()
  1348.  
  1349. dos.library/ExAll                                           dos.library/ExAll
  1350.  
  1351.    NAME
  1352.     ExAll -- Examine an entire directory (V36)
  1353.  
  1354.    SYNOPSIS
  1355.     continue = ExAll(lock, buffer, size, type, control)
  1356.     D0               D1     D2     D3    D4     D5
  1357.  
  1358.     BOOL ExAll(BPTR,STRPTR,LONG,LONG,struct ExAllControl *)
  1359.  
  1360.    FUNCTION
  1361.     Examines an entire directory.  
  1362.  
  1363.  Lock must be on a directory.  Size is the size of the buffer supplied.
  1364.  The buffer will be filled with (partial) ExAllData structures, as
  1365.  specified by the type field.
  1366.  
  1367.  Type is a value from those shown below that determines which information is
  1368.  to be stored in the buffer.  Each higher value adds a new thing to the list
  1369.  as described in the table below:-
  1370.  
  1371.     ED_NAME        FileName
  1372.     ED_TYPE        Type
  1373.     ED_SIZE        Size in bytes
  1374.     ED_PROTECTION    Protection bits
  1375.     ED_DATE        3 longwords of date
  1376.     ED_COMMENT    Comment (will be NULL if no comment)
  1377.             Note: the V37 ROM/disk filesystem returns this
  1378.             incorrectly as a BSTR.  See BUGS for a workaround.
  1379.     ED_OWNER    owner user-id and group-id (if supported)  (V39)
  1380.  
  1381.  Thus, ED_NAME gives only filenames, and ED_OWNER gives everything.
  1382.  
  1383.  NOTE: V37 dos.library, when doing ExAll() emulation, and RAM: filesystem
  1384.  will return an error if passed ED_OWNER.  If you get ERROR_BAD_NUMBER,
  1385.  retry with ED_COMMENT to get everything but owner info.  All filesystems
  1386.  supporting ExAll() must support through ED_COMMENT, and must check Type
  1387.  and return ERROR_BAD_NUMBER if they don't support the type.
  1388.  
  1389.  The V37 ROM/disk filesystem doesn't fill in the comment field correctly
  1390.  if you specify ED_OWNER.  See BUGS for a workaround if you need to use
  1391.  ED_OWNER.
  1392.  
  1393.  The ead_Next entry gives a pointer to the next entry in the buffer.  The
  1394.  last entry will have NULL in ead_Next.
  1395.  
  1396.  The control structure is required so that FFS can keep track if more than
  1397.  one call to ExAll is required.  This happens when there are more names in
  1398.  a directory than will fit into the buffer.  The format of the control
  1399.  structure is as follows:-
  1400.  
  1401.  NOTE: the control structure MUST be allocated by AllocDosObject!!!
  1402.  
  1403.  Entries:  This field tells the calling application how many entries are
  1404.         in the buffer after calling ExAll.  Note: make sure your code
  1405.         handles the 0 entries case, including 0 entries with continue
  1406.         non-zero.
  1407.  
  1408.  LastKey:  This field ABSOLUTELY MUST be initialised to 0 before calling
  1409.         ExAll for the first time.  Any other value will cause nasty
  1410.         things to happen.  If ExAll returns non-zero, then this field
  1411.         should not be touched before making the second and subsequent
  1412.         calls to ExAll.  Whenever ExAll returns non-zero, there are more
  1413.         calls required before all names have been received.
  1414.  
  1415.         As soon as a FALSE return is received then ExAll has completed
  1416.         (if IoErr() returns ERROR_NO_MORE_ENTRIES - otherwise it returns
  1417.         the error that occured, similar to ExNext.)
  1418.  
  1419.  MatchString
  1420.         If this field is NULL then all filenames will be returned.  If
  1421.         this field is non-null then it is interpreted as a pointer to
  1422.         a string that is used to pattern match all file names before
  1423.         accepting them and putting them into the buffer.  The default
  1424.         AmigaDOS caseless pattern match routine is used.  This string
  1425.         MUST have been parsed by ParsePatternNoCase()!
  1426.  
  1427.  MatchFunc: 
  1428.         Contains a pointer to a hook for a routine to decide if the entry
  1429.         will be included in the returned list of entries.  The entry is
  1430.         filled out first, and then passed to the hook.  If no MatchFunc is
  1431.         to be called then this entry should be NULL.  The hook is
  1432.         called with the following parameters (as is standard for hooks):
  1433.  
  1434.         BOOL = MatchFunc( hookptr, data, typeptr )
  1435.                 a0    a1    a2
  1436.         (a0 = ptr to hook, a1 = ptr to filled in ExAllData, a2 = ptr
  1437.          to longword of type).
  1438.  
  1439.         MatchFunc should return FALSE if the entry is not to be
  1440.         accepted, otherwise return TRUE.
  1441.  
  1442.     Note that Dos will emulate ExAll() using Examine() and ExNext()
  1443.     if the handler in question doesn't support the ExAll() packet.
  1444.  
  1445.    INPUTS
  1446.     lock    - Lock on directory to be examined.
  1447.     buffer  - Buffer for data returned (MUST be at least word-aligned,
  1448.           preferably long-word aligned).
  1449.     size    - Size in bytes of 'buffer'.
  1450.     type    - Type of data to be returned.
  1451.     control - Control data structure (see notes above).  MUST have been
  1452.           allocated by AllocDosObject!
  1453.  
  1454.    RESULT
  1455.     continue - Whether or not ExAll is done.  If FALSE is returned, either
  1456.            ExAll has completed (IoErr() == ERROR_NO_MORE_ENTRIES), or
  1457.            an error occurred (check IoErr()).  If non-zero is returned,
  1458.            you MUST call ExAll again until it returns FALSE.
  1459.  
  1460.    EXAMPLE
  1461.  
  1462.    eac = AllocDosObject(DOS_EXALLCONTROL,NULL);
  1463.    if (!eac) ...
  1464.    ...
  1465.    eac->eac_LastKey = 0;
  1466.    do {
  1467.        more = ExAll(lock, EAData, sizeof(EAData), ED_FOO, eac);
  1468.        if ((!more) && (IoErr() != ERROR_NO_MORE_ENTRIES)) {
  1469.            \* ExAll failed abnormally *\
  1470.            break;
  1471.        }
  1472.        if (eac->eac_Entries == 0) {
  1473.            \* ExAll failed normally with no entries *\
  1474.            continue;                   \* ("more" is *usually* zero) *\
  1475.        }
  1476.        ead = (struct ExAllData *) EAData;
  1477.        do {
  1478.            \* use ead here *\
  1479.            ...
  1480.            \* get next ead *\
  1481.            ead = ead->ed_Next;
  1482.        } while (ead);
  1483.  
  1484.    } while (more);
  1485.    ...
  1486.    FreeDosObject(DOS_EXALLCONTROL,eac);
  1487.  
  1488.    BUGS
  1489.     In V36, there were problems with ExAll (particularily with
  1490.     eac_MatchString, and ed_Next with the ramdisk and the emulation
  1491.     of it in Dos for handlers that do not support the packet.  It is
  1492.     advised you only use this under V37 and later.
  1493.  
  1494.     The V37 ROM/disk filesystem incorrectly returned comments as BSTR's
  1495.     (length plus characters) instead of CSTR's (null-terminated).  See
  1496.     the next bug for a way to determine if the filesystem is a V37
  1497.     ROM/disk filesystem.  Fixed in V39.
  1498.  
  1499.     The V37 ROM/disk filesystem incorrectly handled values greater than
  1500.     ED_COMMENT.  Because of this, ExAll() information is trashed if
  1501.     ED_OWNER is passed to it.  Fixed in V39.  To work around this, use
  1502.     the following code to identify if a filesystem is a V37 ROM/disk
  1503.     filesystem:
  1504.  
  1505.  // return TRUE if this is a V37 ROM filesystem, which doesn't (really)
  1506.  // support ED_OWNER safely
  1507.  
  1508.  BOOL CheckV37(BPTR lock)
  1509.  {
  1510.      struct FileLock *l = BADDR(lock);
  1511.      struct Resident *resident;
  1512.      struct DosList *dl;
  1513.      BOOL result = FALSE;
  1514.  
  1515.      dl = LockDosList(LDF_READ|LDF_DEVICES);
  1516.  
  1517.      // if the lock has a volume and no device, we won't find it,
  1518.     // so we know it's not a V37 ROM/disk filesystem
  1519.      do {
  1520.          dl = NextDosEntry(dl,LDF_READ|LDF_DEVICES);
  1521.          if (dl && (dl->dol_Task == l->fl_Task))
  1522.          {
  1523.          // found the filesystem - test isn't actually required,
  1524.         // but we know the filesystem we're looking for will always
  1525.         // have a startup msg.  If we needed to examine the message,
  1526.         // we would need a _bunch_ of checks to make sure it's not
  1527.         // either a small value (like port-handler uses) or a BSTR.
  1528.          if (dl->dol_misc.dol_handler.dol_Startup)
  1529.          {
  1530.              // try to make sure it's the ROM fs or l:FastFileSystem
  1531.              if (resident =
  1532.                  FindRomTag(dl->dol_misc.dol_handler.dol_SegList))
  1533.              {
  1534.                  if (resident->rt_Version < 39 &&
  1535.                      (strncmp(resident->rt_IdString,"fs 37.",
  1536.                           strlen("fs 37.")) == 0 ||
  1537.                       strncmp(resident->rt_Name,"ffs 37.",
  1538.                           strlen("ffs 37.")) == 0))
  1539.                  {
  1540.                      result = TRUE;
  1541.                  }
  1542.              }
  1543.          }
  1544.          break;
  1545.          }
  1546.      } while (dl);
  1547.  
  1548.      UnLockDosList(LDF_READ|LDF_DEVICES);
  1549.  
  1550.      return result;
  1551.  }
  1552.  
  1553.  
  1554.    SEE ALSO
  1555.     Examine(), ExNext(), ExamineFH(), MatchPatternNoCase(),
  1556.     ParsePatternNoCase(), AllocDosObject(), ExAllEnd()
  1557.  
  1558. dos.library/ExAllEnd                                     dos.library/ExAllEnd
  1559.  
  1560.    NAME
  1561.     ExAllEnd -- Stop an ExAll() (V39)
  1562.  
  1563.    SYNOPSIS
  1564.     ExAllEnd(lock, buffer, size, type, control)
  1565.               D1     D2     D3    D4     D5
  1566.  
  1567.     ExAllEnd(BPTR,STRPTR,LONG,LONG,struct ExAllControl *)
  1568.  
  1569.    FUNCTION
  1570.     Stops an ExAll() on a directory before it hits NO_MORE_ENTRIES.
  1571.     The full set of arguments that had been passed to ExAll() must be
  1572.     passed to ExAllEnd(), so it can handle filesystems that can't abort
  1573.     an ExAll() directly.
  1574.  
  1575.    INPUTS
  1576.     lock    - Lock on directory to be examined.
  1577.     buffer  - Buffer for data returned (MUST be at least word-aligned,
  1578.           preferably long-word aligned).
  1579.     size    - Size in bytes of 'buffer'.
  1580.     type    - Type of data to be returned.
  1581.     control - Control data structure (see notes above).  MUST have been
  1582.           allocated by AllocDosObject!
  1583.  
  1584.    SEE ALSO
  1585.     ExAll(), AllocDosObject()
  1586.  
  1587. dos.library/Examine                                       dos.library/Examine
  1588.  
  1589.     NAME
  1590.     Examine -- Examine a directory or file associated with a lock
  1591.  
  1592.     SYNOPSIS
  1593.     success = Examine( lock, FileInfoBlock )
  1594.     D0            D1          D2
  1595.  
  1596.     BOOL Examine(BPTR,struct FileInfoBlock *)
  1597.  
  1598.     FUNCTION
  1599.     Examine() fills in information in the FileInfoBlock concerning the
  1600.     file or directory associated with the lock. This information
  1601.     includes the name, size, creation date and whether it is a file or
  1602.     directory.  FileInfoBlock must be longword aligned.  Examine() gives
  1603.     a return code of zero if it fails.
  1604.  
  1605.     You may make a local copy of the FileInfoBlock, as long as it is
  1606.     never passed to ExNext().
  1607.  
  1608.     INPUTS
  1609.     lock      - BCPL pointer to a lock
  1610.     infoBlock - pointer to a FileInfoBlock (MUST be longword aligned)
  1611.  
  1612.     RESULTS
  1613.     success - boolean
  1614.  
  1615.     SPECIAL NOTE
  1616.     FileInfoBlock must be longword-aligned.  AllocDosObject() will
  1617.     allocate them correctly for you.
  1618.  
  1619.     SEE ALSO
  1620.     Lock(), UnLock(), ExNext(), ExamineFH(), <dos/dos.h>, AllocDosObject(),
  1621.     ExAll()
  1622.  
  1623. dos.library/ExamineFH                                   dos.library/ExamineFH
  1624.  
  1625.    NAME
  1626.     ExamineFH -- Gets information on an open file (V36)
  1627.  
  1628.    SYNOPSIS
  1629.     success = ExamineFH(fh, fib)
  1630.     D0                  D1  D2
  1631.  
  1632.     BOOL ExamineFH(BPTR, struct FileInfoBlock *)
  1633.  
  1634.    FUNCTION
  1635.     Examines a filehandle and returns information about the file in the
  1636.     FileInfoBlock.  There are no guarantees as to whether the fib_Size
  1637.     field will reflect any changes made to the file size it was opened,
  1638.     though filesystems should attempt to provide up-to-date information
  1639.     for it.
  1640.  
  1641.    INPUTS
  1642.     fh  - Filehandle you wish to examine
  1643.     fib - FileInfoBlock, must be longword aligned.
  1644.  
  1645.    RESULT
  1646.     success - Success/failure indication
  1647.  
  1648.    SEE ALSO
  1649.     Examine(), ExNext(), ExAll(), Open(), AllocDosObject()
  1650.  
  1651. dos.library/Execute                                       dos.library/Execute
  1652.  
  1653.     NAME
  1654.     Execute -- Execute a CLI command
  1655.  
  1656.     SYNOPSIS
  1657.     success = Execute( commandString, input, output )
  1658.     D0           D1          D2     D3
  1659.  
  1660.     BOOL Execute(STRPTR, BPTR, BPTR)
  1661.  
  1662.     FUNCTION
  1663.     This function attempts to execute the string commandString as a
  1664.     Shell command and arguments. The string can contain any valid input
  1665.     that you could type directly in a Shell, including input and output
  1666.     redirection using < and >.  Note that Execute() doesn't return until
  1667.     the command(s) in commandstring have returned.
  1668.  
  1669.     The input file handle will normally be zero, and in this case
  1670.     Execute() will perform whatever was requested in the commandString
  1671.     and then return. If the input file handle is nonzero then after the
  1672.     (possibly empty) commandString is performed subsequent input is read
  1673.     from the specified input file handle until end of that file is
  1674.     reached.
  1675.  
  1676.     In most cases the output file handle must be provided, and is used
  1677.     by the Shell commands as their output stream unless output
  1678.     redirection was specified. If the output file handle is set to zero
  1679.     then the current window, normally specified as *, is used. Note
  1680.     that programs running under the Workbench do not normally have a
  1681.     current window.
  1682.  
  1683.     Execute() may also be used to create a new interactive Shell process
  1684.     just like those created with the NewShell command. In order to do
  1685.     this you would call Execute() with an empty commandString, and pass
  1686.     a file handle relating to a new window as the input file handle.
  1687.     The output file handle would be set to zero. The Shell will read
  1688.     commands from the new window, and will use the same window for
  1689.     output. This new Shell window can only be terminated by using the
  1690.     EndCLI command.
  1691.  
  1692.     Under V37, if an input filehandle is passed, and it's either
  1693.     interactive or a NIL: filehandle, the pr_ConsoleTask of the new
  1694.     process will be set to that filehandle's process (the same applies
  1695.     to SystemTagList()).
  1696.  
  1697.     For this command to work the program Run must be present in C: in
  1698.     versions before V36 (except that in 1.3.2 and any later 1.3 versions,
  1699.     the system first checks the resident list for Run).
  1700.  
  1701.     INPUTS
  1702.     commandString - pointer to a null-terminated string
  1703.     input          - BCPL pointer to a file handle
  1704.     output          - BCPL pointer to a file handle
  1705.  
  1706.     RESULTS
  1707.     success - BOOLEAN indicating whether Execute was successful
  1708.           in finding and starting the specified program.  Note this
  1709.           is NOT the return code of the command(s).
  1710.     SEE ALSO
  1711.     SystemTagList(), NewShell, EndCLI, Run
  1712.  
  1713. dos.library/Exit                                             dos.library/Exit
  1714.  
  1715.     NAME
  1716.     Exit -- Exit from a program
  1717.  
  1718.     SYNOPSIS
  1719.     Exit( returnCode )
  1720.           D1
  1721.  
  1722.     void Exit(LONG)
  1723.  
  1724.     FUNCTION
  1725.     Exit() is currently for use with programs written as if they
  1726.     were BCPL programs.  This function is not normally useful for
  1727.     other purposes.
  1728.  
  1729.     In general, therefore, please DO NOT CALL THIS FUNCTION!
  1730.  
  1731.     In order to exit, C programs should use the C language exit()
  1732.     function (note the lower case letter "e").  Assembly programs should
  1733.     place a return code in D0, and execute an RTS instruction with
  1734.     their original stack ptr.
  1735.  
  1736.     IMPLEMENTATION
  1737.     The action of Exit() depends on whether the program which called it
  1738.     is running as a command under a CLI or not. If the program is
  1739.     running under the CLI the command finishes and control reverts to
  1740.     the CLI. In this case, returnCode is interpreted as the return code
  1741.     from the program.
  1742.  
  1743.     If the program is running as a distinct process, Exit() deletes the
  1744.     process and release the space associated with the stack, segment
  1745.     list and process structure.
  1746.  
  1747.     INPUTS
  1748.     returnCode - integer
  1749.  
  1750.     SEE ALSO
  1751.     CreateProc(), CreateNewProc()
  1752.  
  1753. dos.library/ExNext                                         dos.library/ExNext
  1754.  
  1755.     NAME
  1756.     ExNext -- Examine the next entry in a directory
  1757.  
  1758.     SYNOPSIS
  1759.     success = ExNext( lock, FileInfoBlock )
  1760.     D0           D1         D2
  1761.  
  1762.     BOOL ExNext(BPTR, struct FileInfoBlock *)
  1763.  
  1764.     FUNCTION
  1765.     This routine is passed a directory lock and a FileInfoBlock that
  1766.     have been initialized by a previous call to Examine(), or updated
  1767.     by a previous call to ExNext().  ExNext() gives a return code of zero
  1768.     on failure.  The most common cause of failure is reaching the end
  1769.     of the list of files in the owning directory.  In this case, IoErr
  1770.     will return ERROR_NO_MORE_ENTRIES and a good exit is appropriate.
  1771.  
  1772.     So, follow these steps to examine a directory:
  1773.     1) Pass a Lock and a FileInfoBlock to Examine().  The lock must
  1774.        be on the directory you wish to examine.
  1775.     2) Pass ExNext() the same lock and FileInfoBlock.
  1776.     3) Do something with the information returned in the FileInfoBlock.
  1777.        Note that the fib_DirEntryType field is positive for directories,
  1778.        negative for files.
  1779.     4) Keep calling ExNext() until it returns FALSE.  Check IoErr()
  1780.        to ensure that the reason for failure was ERROR_NO_MORE_ENTRIES.
  1781.  
  1782.     Note: if you wish to recursively scan the file tree and you find
  1783.     another directory while ExNext()ing you must Lock that directory and
  1784.     Examine() it using a new FileInfoBlock.  Use of the same
  1785.     FileInfoBlock to enter a directory would lose important state
  1786.     information such that it will be impossible to continue scanning
  1787.     the parent directory.  While it is permissible to UnLock() and Lock()
  1788.     the parent directory between ExNext() calls, this is NOT recommended.
  1789.     Important state information is associated with the parent lock, so
  1790.     if it is freed between ExNext() calls this information has to be
  1791.     rebuilt on each new ExNext() call, and will significantly slow down
  1792.     directory scanning.
  1793.  
  1794.     It is NOT legal to Examine() a file, and then to ExNext() from that
  1795.     FileInfoBlock.    You may make a local copy of the FileInfoBlock, as
  1796.     long as it is never passed back to the operating system.
  1797.  
  1798.     INPUTS
  1799.     lock - BCPL pointer to a lock originally used for the Examine() call
  1800.     infoBlock - pointer to a FileInfoBlock used on the previous Examine()
  1801.             or ExNext() call.
  1802.  
  1803.     RESULTS
  1804.     success - boolean
  1805.  
  1806.     SPECIAL NOTE
  1807.     FileInfoBlock must be longword-aligned.  AllocDosObject() will
  1808.     allocate them correctly for you.
  1809.  
  1810.     SEE ALSO
  1811.     Examine(), Lock(), UnLock(), IoErr(), ExamineFH(), AllocDosObject(),
  1812.     ExAll()
  1813.  
  1814. dos.library/Fault                                           dos.library/Fault
  1815.  
  1816.    NAME
  1817.     Fault -- Returns the text associated with a DOS error code (V36)
  1818.  
  1819.    SYNOPSIS
  1820.     len = Fault(code, header, buffer, len)
  1821.     D0           D1     D2      D3    D4
  1822.  
  1823.     LONG Fault(LONG, STRPTR, STRPTR, LONG)
  1824.  
  1825.    FUNCTION
  1826.     This routine obtains the error message text for the given error code.
  1827.     The header is prepended to the text of the error message, followed
  1828.     by a colon.  Puts a null-terminated string for the error message into
  1829.     the buffer.  By convention, error messages should be no longer than 80
  1830.     characters (+1 for termination), and preferably no more than 60.
  1831.     The value returned by IoErr() is set to the code passed in.  If there
  1832.     is no message for the error code, the message will be "Error code
  1833.     <number>\n".
  1834.  
  1835.     The number of characters put into the buffer is returned, which will
  1836.     be 0 if the code passed in was 0.
  1837.  
  1838.    INPUTS
  1839.     code   - Error code
  1840.     header - header to output before error text
  1841.     buffer - Buffer to receive error message.
  1842.     len    - Length of the buffer.
  1843.  
  1844.    RESULT
  1845.     len    - number of characters put into buffer (may be 0)
  1846.  
  1847.    SEE ALSO
  1848.     IoErr(), SetIoErr(), PrintFault()
  1849.  
  1850.    BUGS
  1851.     In older documentation, the return was shown as BOOL success.  This
  1852.     was incorrect, it has always returned the length.
  1853.  
  1854. dos.library/FGetC                                           dos.library/FGetC
  1855.  
  1856.    NAME
  1857.     FGetC -- Read a character from the specified input (buffered) (V36)
  1858.  
  1859.    SYNOPSIS
  1860.     char = FGetC(fh)
  1861.     D0         D1
  1862.  
  1863.     LONG FGetC(BPTR)
  1864.  
  1865.    FUNCTION
  1866.     Reads the next character from the input stream.  A -1 is
  1867.     returned when EOF or an error is encountered.  This call is buffered.
  1868.     Use Flush() between buffered and unbuffered I/O on a filehandle.
  1869.  
  1870.    INPUTS
  1871.     fh - filehandle to use for buffered I/O
  1872.  
  1873.    RESULT
  1874.     char - character read (0-255) or -1
  1875.  
  1876.    BUGS
  1877.     In V36, after an EOF was read, EOF would always be returned from
  1878.     FGetC() from then on.  Starting in V37, it tries to read from the
  1879.     handler again each time (unless UnGetC(fh,-1) was called).
  1880.  
  1881.    SEE ALSO
  1882.     FPutC(), UnGetC(), Flush()
  1883.  
  1884. dos.library/FGets                                           dos.library/FGets
  1885.  
  1886.    NAME
  1887.     FGets -- Reads a line from the specified input (buffered) (V36)
  1888.  
  1889.    SYNOPSIS
  1890.     buffer = FGets(fh, buf, len)
  1891.     D0             D1  D2   D3
  1892.  
  1893.     STRPTR FGets(BPTR, STRPTR, ULONG)
  1894.  
  1895.    FUNCTION
  1896.     This routine reads in a single line from the specified input stopping
  1897.     at a NEWLINE character or EOF.  In either event, UP TO the number of
  1898.     len specified bytes minus 1 will be copied into the buffer.  Hence if
  1899.     a length of 50 is passed and the input line is longer than 49 bytes,
  1900.     it will return 49 characters.  It returns the buffer pointer normally,
  1901.     or NULL if EOF is the first thing read.
  1902.  
  1903.     If terminated by a newline, the newline WILL be the last character in
  1904.     the buffer.  This is a buffered read routine.  The string read in IS
  1905.     null-terminated.
  1906.  
  1907.    INPUTS
  1908.     fh  - filehandle to use for buffered I/O
  1909.     buf - Area to read bytes into.
  1910.     len - Number of bytes to read, must be > 0.
  1911.  
  1912.    RESULT
  1913.     buffer - Pointer to buffer passed in, or NULL for immediate EOF or for
  1914.          an error.  If NULL is returnd for an EOF, IoErr() will return
  1915.          0.
  1916.  
  1917.    BUGS
  1918.     In V36 and V37, it copies one more byte than it should if it doesn't
  1919.     hit an EOF or newline.  In the example above, it would copy 50 bytes
  1920.     and put a null in the 51st.  This is fixed in dos V39.  Workaround
  1921.     for V36/V37: pass in buffersize-1.
  1922.  
  1923.    SEE ALSO
  1924.     FRead(), FPuts(), FGetC()
  1925.  
  1926. dos.library/FilePart                                     dos.library/FilePart
  1927.  
  1928.    NAME
  1929.     FilePart -- Returns the last component of a path (V36)
  1930.  
  1931.    SYNOPSIS
  1932.     fileptr = FilePart( path )
  1933.     D0             D1
  1934.  
  1935.     STRPTR FilePart( STRPTR )
  1936.  
  1937.    FUNCTION
  1938.     This function returns a pointer to the last component of a string path
  1939.     specification, which will normally be the file name.  If there is only
  1940.     one component, it returns a pointer to the beginning of the string.
  1941.  
  1942.    INPUTS
  1943.     path - pointer to an path string.  May be relative to the current
  1944.            directory or the current disk.
  1945.  
  1946.    RESULT
  1947.     fileptr - pointer to the last component of the path.
  1948.  
  1949.    EXAMPLE
  1950.     FilePart("xxx:yyy/zzz/qqq") would return a pointer to the first 'q'.
  1951.     FilePart("xxx:yyy") would return a pointer to the first 'y').
  1952.  
  1953.    SEE ALSO
  1954.     PathPart(), AddPart()
  1955.  
  1956. dos.library/FindArg                                       dos.library/FindArg
  1957.  
  1958.    NAME
  1959.     FindArg - find a keyword in a template (V36)
  1960.  
  1961.    SYNOPSIS
  1962.     index = FindArg(template, keyword)
  1963.     D0                D1        D2
  1964.  
  1965.     LONG FindArg(STRPTR, STRPTR)
  1966.  
  1967.    FUNCTION
  1968.     Returns the argument number of the keyword, or -1 if it is not a
  1969.     keyword for the template.  Abbreviations are handled.
  1970.  
  1971.    INPUTS
  1972.     keyword  - keyword to search for in template
  1973.     template - template string to search
  1974.  
  1975.    RESULT
  1976.     index - number of entry in template, or -1 if not found
  1977.  
  1978.    BUGS
  1979.     In earlier published versions of the autodoc, keyword and template
  1980.     were backwards.
  1981.  
  1982.    SEE ALSO
  1983.     ReadArgs(), ReadItem(), FreeArgs()
  1984.  
  1985. dos.library/FindCliProc                               dos.library/FindCliProc
  1986.  
  1987.    NAME
  1988.     FindCliProc -- returns a pointer to the requested CLI process (V36)
  1989.  
  1990.    SYNOPSIS
  1991.     proc = FindCliProc(num)
  1992.     D0             D1
  1993.  
  1994.     struct Process *FindCliProc(ULONG)
  1995.  
  1996.    FUNCTION
  1997.     This routine returns a pointer to the CLI process associated with the 
  1998.     given CLI number.  If the process isn't an active CLI process, NULL is
  1999.     returned.  NOTE: should normally be called inside a Forbid(), if you
  2000.     must use this function at all.
  2001.  
  2002.    INPUTS
  2003.     num  - Task number of CLI process (range 1-N)
  2004.  
  2005.    RESULT
  2006.     proc - Pointer to given CLI process
  2007.  
  2008.    SEE ALSO
  2009.     Cli(), Forbid(), MaxCli()
  2010.  
  2011. dos.library/FindDosEntry                             dos.library/FindDosEntry
  2012.  
  2013.    NAME
  2014.     FindDosEntry -- Finds a specific Dos List entry (V36)
  2015.  
  2016.    SYNOPSIS
  2017.     newdlist = FindDosEntry(dlist,name,flags)
  2018.     D0                       D1    D2   D3
  2019.  
  2020.     struct DosList *FindDosEntry(struct DosList *,STRPTR,ULONG)
  2021.  
  2022.    FUNCTION
  2023.     Locates an entry on the device list.  Starts with the entry dlist.
  2024.     NOTE: must be called with the device list locked, no references may be
  2025.     made to dlist after unlocking.
  2026.  
  2027.    INPUTS
  2028.     dlist    - The device entry to start with.
  2029.     name     - Name of device entry (without ':') to locate.
  2030.     flags    - Search control flags.  Use the flags you passed to
  2031.            LockDosList, or a subset of them.  LDF_READ/LDF_WRITE are
  2032.            not required for this call.
  2033.  
  2034.    RESULT
  2035.     newdlist - The device entry or NULL
  2036.  
  2037.    SEE ALSO
  2038.     AddDosEntry(), RemDosEntry(), NextDosEntry(), LockDosList(),
  2039.     MakeDosEntry(), FreeDosEntry()
  2040.  
  2041. dos.library/FindSegment                               dos.library/FindSegment
  2042.  
  2043.    NAME
  2044.     FindSegment - Finds a segment on the resident list (V36)
  2045.  
  2046.    SYNOPSIS
  2047.     segment = FindSegment(name, start, system)
  2048.     D0               D1     D2     D3
  2049.  
  2050.     struct Segment *FindSegment(STRPTR, struct Segment *, LONG)
  2051.  
  2052.    FUNCTION
  2053.     Finds a segment on the Dos resident list by name and type, starting
  2054.     at the segment AFTER 'start', or at the beginning if start is NULL.
  2055.     If system is zero, it will only return nodes with a seg_UC of 0
  2056.     or more.  It does NOT increment the seg_UC, and it does NOT do any
  2057.     locking of the list.  You must Forbid() lock the list to use this
  2058.     call.
  2059.  
  2060.     To use an entry you have found, you must: if the seg_UC is 0 or more,
  2061.     increment it, and decrement it (under Forbid()!) when you're done
  2062.     the the seglist.
  2063.  
  2064.     The other values for seg_UC are:
  2065.         -1   - system module, such as a filesystem or shell
  2066.         -2   - resident shell command
  2067.         -999 - disabled internal command, ignore
  2068.     Negative values should never be modified.  All other negative
  2069.     values between 0 and -32767 are reserved to AmigaDos and should not
  2070.     be used.
  2071.  
  2072.    INPUTS
  2073.     name   - name of segment to find
  2074.     start  - segment to start the search after
  2075.     system - true for system segment, false for normal segments
  2076.  
  2077.    RESULT
  2078.     segment - the segment found or NULL
  2079.  
  2080.    SEE ALSO
  2081.     AddSegment(), RemSegment(), Forbid()
  2082.  
  2083. dos.library/FindVar                                       dos.library/FindVar
  2084.  
  2085.    NAME
  2086.     FindVar -- Finds a local variable (V36)
  2087.  
  2088.    SYNOPSIS
  2089.     var = FindVar( name, type ) 
  2090.     D0        D1    D2
  2091.  
  2092.     struct LocalVar * FindVar(STRPTR, ULONG ) 
  2093.  
  2094.    FUNCTION
  2095.     Finds a local variable structure.
  2096.  
  2097.    INPUTS
  2098.     name - pointer to an variable name.  Note variable names follow
  2099.            filesystem syntax and semantics.
  2100.  
  2101.     type - type of variable to be found (see <dos/var.h>)
  2102.  
  2103.    RESULT
  2104.  
  2105.     var  - pointer to a LocalVar structure or NULL
  2106.  
  2107.    SEE ALSO
  2108.     GetVar(), SetVar(), DeleteVar(), <dos/var.h>
  2109.  
  2110. dos.library/Flush                                           dos.library/Flush
  2111.  
  2112.    NAME
  2113.     Flush -- Flushes buffers for a buffered filehandle (V36)
  2114.  
  2115.    SYNOPSIS
  2116.     success = Flush(fh)
  2117.     D0        D1
  2118.  
  2119.     LONG Flush(BPTR)
  2120.  
  2121.    FUNCTION
  2122.     Flushes any pending buffered writes to the filehandle.  All buffered
  2123.     writes will also be flushed on Close().  If the filehandle was being
  2124.     used for input, it drops the buffer, and tries to Seek() back to the
  2125.     last read position  (so subsequent reads or writes will occur at the
  2126.     expected position in the file).
  2127.  
  2128.    INPUTS
  2129.     fh    - Filehandle to flush.
  2130.  
  2131.    RESULT
  2132.     success - Success or failure.
  2133.  
  2134.    BUGS
  2135.     Before V37 release, Flush() returned a random value.  As of V37,
  2136.     it always returns success (this will be fixed in some future
  2137.     release).
  2138.  
  2139.     The V36 and V37 releases didn't properly flush filehandles which
  2140.     have never had a buffered IO done on them.  This commonly occurs
  2141.     on redirection of input of a command, or when opening a file for
  2142.     input and then calling CreateNewProc() with NP_Arguments, or when
  2143.     using a new filehandle with SelectInput() and then calling
  2144.     RunCommand().  This is fixed in V39.  A workaround would be to
  2145.     do FGetC(), then UnGetC(), then Flush().
  2146.  
  2147.    SEE ALSO
  2148.     FputC(), FGetC(), UnGetC(), Seek(), Close(), CreateNewProc(),
  2149.     SelectInput(), RunCommand()
  2150.  
  2151. dos.library/Format                                         dos.library/Format
  2152.  
  2153.    NAME
  2154.     Format -- Causes a filesystem to initialize itself (V36)
  2155.  
  2156.    SYNOPSIS
  2157.     success = Format(filesystem, volumename, dostype)
  2158.     D0                   D1          D2         D3
  2159.  
  2160.     BOOL Format(STRPTR, STRPTR, ULONG)
  2161.  
  2162.    FUNCTION
  2163.     Interface for initializing new media on a device.  This causes the
  2164.     filesystem to write out an empty disk structure to the media, which
  2165.     should then be ready for use.  This assumes the media has been low-
  2166.     level formatted and verified already.
  2167.  
  2168.     The filesystem should be inhibited before calling Format() to make
  2169.     sure you don't get an ERROR_OBJECT_IN_USE.
  2170.  
  2171.    INPUTS
  2172.     filesystem - Name of device to be formatted.  ':' must be supplied.
  2173.     volumename - Name for volume (if supported).  No ':'.
  2174.     dostype    - Type of format, if filesystem supports multiple types.
  2175.  
  2176.    RESULT
  2177.     success - Success/failure indicator.
  2178.  
  2179.    BUGS
  2180.     Existed, but was non-functional in V36 dos.  (The volumename wasn't
  2181.     converted to a BSTR.)  Workaround: require V37, or under V36
  2182.     convert volumename to a BPTR to a BSTR before calling Format().
  2183.     Note: a number of printed packet docs for ACTION_FORMAT are wrong
  2184.     as to the arguments.
  2185.  
  2186.    SEE ALSO
  2187.  
  2188. dos.library/FPutC                                           dos.library/FPutC
  2189.  
  2190.    NAME
  2191.     FPutC -- Write a character to the specified output (buffered) (V36)
  2192.  
  2193.    SYNOPSIS
  2194.     char = FPutC(fh, char)
  2195.     D0           D1   D2
  2196.  
  2197.     LONG FPutC(BPTR, LONG)
  2198.  
  2199.    FUNCTION
  2200.     Writes a single character to the output stream.  This call is
  2201.     buffered.  Use Flush() between buffered and unbuffered I/O on a
  2202.     filehandle.  Interactive filehandles are flushed automatically
  2203.     on a newline, return, '\0', or line feed.
  2204.  
  2205.    INPUTS
  2206.     fh   - filehandle to use for buffered I/O
  2207.     char - character to write
  2208.  
  2209.    RESULT
  2210.     char - either the character written, or EOF for an error.
  2211.  
  2212.    BUGS
  2213.     Older autodocs indicated that you should pass a UBYTE.  The
  2214.     correct usage is to pass a LONG in the range 0-255.
  2215.  
  2216.    SEE ALSO
  2217.     FGetC(), UnGetC(), Flush()
  2218.  
  2219. dos.library/FPuts                                           dos.library/FPuts
  2220.  
  2221.    NAME
  2222.     FPuts -- Writes a string the the specified output (buffered) (V36)
  2223.  
  2224.    SYNOPSIS
  2225.     error = FPuts(fh, str)
  2226.     D0            D1  D2
  2227.  
  2228.     LONG FPuts(BPTR, STRPTR)
  2229.  
  2230.    FUNCTION
  2231.     This routine writes an unformatted string to the filehandle.  No 
  2232.     newline is appended to the string.  This routine is buffered.
  2233.  
  2234.    INPUTS
  2235.     fh    - filehandle to use for buffered I/O
  2236.     str   - Null-terminated string to be written to default output
  2237.  
  2238.    RESULT
  2239.     error - 0 normally, otherwise -1.  Note that this is opposite of
  2240.         most other Dos functions, which return success.
  2241.  
  2242.    SEE ALSO
  2243.     FGets(), FPutC(), FWrite(), PutStr()
  2244.  
  2245. dos.library/FRead                                           dos.library/FRead
  2246.  
  2247.    NAME
  2248.     FRead -- Reads a number of blocks from an input (buffered) (V36)
  2249.  
  2250.    SYNOPSIS
  2251.     count = FRead(fh, buf, blocklen, blocks)
  2252.     D0          D1  D2     D3        D4
  2253.  
  2254.     LONG FRead(BPTR, STRPTR, ULONG, ULONG)
  2255.  
  2256.    FUNCTION
  2257.     Attempts to read a number of blocks, each blocklen long, into the
  2258.     specified buffer from the input stream.  May return less than
  2259.     the number of blocks requested, either due to EOF or read errors.
  2260.     This call is buffered.
  2261.  
  2262.    INPUTS
  2263.     fh     - filehandle to use for buffered I/O
  2264.     buf      - Area to read bytes into.
  2265.     blocklen - number of bytes per block.  Must be > 0.
  2266.     blocks     - number of blocks to read.  Must be > 0.
  2267.  
  2268.    RESULT
  2269.     count - Number of _blocks_ read, or 0 for EOF.  On an error, the
  2270.         number of blocks actually read is returned.
  2271.  
  2272.    BUGS
  2273.     Doesn't clear IoErr() before starting.  If you want to find out
  2274.     about errors, use SetIoErr(0L) before calling.
  2275.  
  2276.    SEE ALSO
  2277.     FGetC(), FWrite(), FGets()
  2278.  
  2279. dos.library/FreeArgs                                     dos.library/FreeArgs
  2280.  
  2281.    NAME
  2282.     FreeArgs - Free allocated memory after ReadArgs() (V36)
  2283.  
  2284.    SYNOPSIS
  2285.     FreeArgs(rdargs)
  2286.                D1
  2287.  
  2288.     void FreeArgs(struct RDArgs *)
  2289.  
  2290.    FUNCTION
  2291.     Frees memory allocated to return arguments in from ReadArgs().  If
  2292.     ReadArgs allocated the RDArgs structure it will be freed.  If NULL
  2293.     is passed in this function does nothing.
  2294.  
  2295.    INPUTS
  2296.     rdargs - structure returned from ReadArgs() or NULL.
  2297.  
  2298.    SEE ALSO
  2299.     ReadArgs(), ReadItem(), FindArg()
  2300.  
  2301. dos.library/FreeDeviceProc                         dos.library/FreeDeviceProc
  2302.  
  2303.    NAME
  2304.     FreeDeviceProc -- Releases port returned by GetDeviceProc() (V36)
  2305.  
  2306.    SYNOPSIS
  2307.     FreeDeviceProc(devproc)
  2308.              D1
  2309.  
  2310.     void FreeDeviceProc(struct DevProc *)
  2311.  
  2312.    FUNCTION
  2313.     Frees up the structure created by GetDeviceProc(), and any associated
  2314.     temporary locks.
  2315.  
  2316.     Decrements the counter incremented by GetDeviceProc().  The counter
  2317.     is in an extension to the 1.3 process structure.  After calling
  2318.     FreeDeviceProc(), do not use the port or lock again!  It is safe to
  2319.     call FreeDeviceProc(NULL).
  2320.  
  2321.    INPUTS
  2322.     devproc - A value returned by GetDeviceProc()
  2323.  
  2324.    BUGS
  2325.     Counter not currently active in 2.0.
  2326.  
  2327.    SEE ALSO
  2328.     GetDeviceProc(), DeviceProc(), AssignLock(), AssignLate(),
  2329.     AssignPath()
  2330.  
  2331. dos.library/FreeDosEntry                             dos.library/FreeDosEntry
  2332.  
  2333.    NAME
  2334.     FreeDosEntry -- Frees an entry created by MakeDosEntry (V36)
  2335.  
  2336.    SYNOPSIS
  2337.     FreeDosEntry(dlist)
  2338.                    D1
  2339.  
  2340.     void FreeDosEntry(struct DosList *)
  2341.  
  2342.    FUNCTION
  2343.     Frees an entry created by MakeDosEntry().  This routine should be
  2344.     eliminated and replaced by a value passed to FreeDosObject()!
  2345.  
  2346.    INPUTS
  2347.     dlist - DosList to free.
  2348.  
  2349.    SEE ALSO
  2350.     AddDosEntry(), RemDosEntry(), FindDosEntry(), LockDosList(),
  2351.     NextDosEntry(), MakeDosEntry()
  2352.  
  2353. dos.library/FreeDosObject                           dos.library/FreeDosObject
  2354.  
  2355.    NAME
  2356.     FreeDosObject -- Frees an object allocated by AllocDosObject() (V36)
  2357.  
  2358.    SYNOPSIS
  2359.     FreeDosObject(type, ptr)
  2360.                D1   D2
  2361.  
  2362.     void FreeDosObject(ULONG, void *)
  2363.  
  2364.    FUNCTION
  2365.     Frees an object allocated by AllocDosObject().  Do NOT call for
  2366.     objects allocated in any other way.
  2367.  
  2368.    INPUTS
  2369.     type - type passed to AllocDosObject()
  2370.     ptr  - ptr returned by AllocDosObject()
  2371.  
  2372.    BUGS
  2373.     Before V39, DOS_CLI objects will only have the struct
  2374.     CommandLineInterface freed, not the strings it points to.  This
  2375.     is fixed in V39 dos.  Before V39, you can workaround this bug by
  2376.     using FreeVec() on cli_SetName, cli_CommandFile, cli_CommandName,
  2377.     and cli_Prompt, and then setting them all to NULL.  In V39 or
  2378.     above, do NOT use the workaround.
  2379.  
  2380.    SEE ALSO
  2381.     AllocDosObject(), FreeVec(), <dos/dos.h>
  2382.  
  2383. dos.library/FWrite                                         dos.library/FWrite
  2384.  
  2385.    NAME
  2386.     FWrite -- Writes a number of blocks to an output (buffered) (V36)
  2387.  
  2388.    SYNOPSIS
  2389.     count = FWrite(fh, buf, blocklen, blocks)
  2390.     D0           D1  D2     D3        D4
  2391.  
  2392.     LONG FWrite(BPTR, STRPTR, ULONG, ULONG)
  2393.  
  2394.    FUNCTION
  2395.     Attempts to write a number of blocks, each blocklen long, from the
  2396.     specified buffer to the output stream.  May return less than the
  2397.     number of blocks requested, if there is some error such as a full
  2398.     disk or r/w error.  This call is buffered.
  2399.  
  2400.    INPUTS
  2401.     fh     - filehandle to use for buffered I/O
  2402.     buf      - Area to write bytes from.
  2403.     blocklen - number of bytes per block.  Must be > 0.
  2404.     blocks     - number of blocks to write.  Must be > 0.
  2405.  
  2406.    RESULT
  2407.     count - Number of _blocks_ written.  On an error, the number of
  2408.         blocks actually written is returned.
  2409.  
  2410.    BUGS
  2411.     Doesn't clear IoErr() before starting.  If you want to find out
  2412.     about errors, use SetIoErr(0L) before calling.
  2413.  
  2414.    SEE ALSO
  2415.     FPutC(), FRead(), FPuts()
  2416.  
  2417. dos.library/GetArgStr                                   dos.library/GetArgStr
  2418.  
  2419.    NAME
  2420.     GetArgStr -- Returns the arguments for the process (V36)
  2421.  
  2422.    SYNOPSIS
  2423.     ptr = GetArgStr()
  2424.     D0
  2425.  
  2426.     STRPTR GetArgStr(void)
  2427.  
  2428.    FUNCTION
  2429.     Returns a pointer to the (null-terminated) arguments for the program
  2430.     (process).  This is the same string passed in a0 on startup from CLI.
  2431.  
  2432.    RESULT
  2433.     ptr - pointer to arguments
  2434.  
  2435.    SEE ALSO
  2436.     SetArgStr(), RunCommand()
  2437.  
  2438. dos.library/GetConsoleTask                         dos.library/GetConsoleTask
  2439.  
  2440.    NAME
  2441.     GetConsoleTask -- Returns the default console for the process (V36)
  2442.  
  2443.    SYNOPSIS
  2444.     port = GetConsoleTask()
  2445.     D0
  2446.  
  2447.     struct MsgPort *GetConsoleTask(void)
  2448.  
  2449.    FUNCTION
  2450.     Returns the default console task's port (pr_ConsoleTask) for the
  2451.     current process.
  2452.  
  2453.    RESULT
  2454.     port - The pr_MsgPort of the console handler, or NULL.
  2455.  
  2456.    SEE ALSO
  2457.     SetConsoleTask(), Open()
  2458.  
  2459. dos.library/GetCurrentDirName                   dos.library/GetCurrentDirName
  2460.  
  2461.    NAME
  2462.     GetCurrentDirName -- returns the current directory name (V36)
  2463.  
  2464.    SYNOPSIS
  2465.     success = GetCurrentDirName(buf, len)
  2466.     D0                          D1   D2
  2467.  
  2468.     BOOL GetCurrentDirName(STRPTR, LONG)
  2469.  
  2470.    FUNCTION
  2471.     Extracts the current directory name from the CLI structure and puts it 
  2472.     into the buffer.  If the buffer is too small, the name is truncated 
  2473.     appropriately and a failure code returned.  If no CLI structure is 
  2474.     present, a null string is returned in the buffer, and failure from
  2475.     the call (with IoErr() == ERROR_OBJECT_WRONG_TYPE);
  2476.  
  2477.    INPUTS
  2478.     buf     - Buffer to hold extracted name
  2479.     len     - Number of bytes of space in buffer
  2480.  
  2481.    RESULT
  2482.     success - Success/failure indicator
  2483.  
  2484.    BUGS
  2485.     In V36, this routine didn't handle 0-length buffers correctly.
  2486.  
  2487.    SEE ALSO
  2488.     SetCurrentDirName()
  2489.  
  2490. dos.library/GetDeviceProc                           dos.library/GetDeviceProc
  2491.  
  2492.    NAME
  2493.     GetDeviceProc -- Finds a handler to send a message to (V36)
  2494.  
  2495.    SYNOPSIS
  2496.     devproc = GetDeviceProc(name, devproc)
  2497.       D0             D1     D2
  2498.  
  2499.     struct DevProc *GetDeviceProc(STRPTR, struct DevProc *)
  2500.  
  2501.    FUNCTION
  2502.     Finds the handler/filesystem to send packets regarding 'name' to.
  2503.     This may involve getting temporary locks.  It returns a structure
  2504.     that includes a lock and msgport to send to to attempt your operation.
  2505.     It also includes information on how to handle multiple-directory
  2506.     assigns (by passing the DevProc back to GetDeviceProc() until it
  2507.     returns NULL).
  2508.  
  2509.     The initial call to GetDeviceProc() should pass NULL for devproc.  If
  2510.     after using the returned DevProc, you get an ERROR_OBJECT_NOT_FOUND,
  2511.     and (devproc->dvp_Flags & DVPF_ASSIGN) is true, you should call
  2512.     GetDeviceProc() again, passing it the devproc structure.  It will
  2513.     either return a modified devproc structure, or NULL (with
  2514.     ERROR_NO_MORE_ENTRIES in IoErr()).  Continue until it returns NULL.
  2515.  
  2516.     This call also increments the counter that locks a handler/fs into
  2517.     memory.  After calling FreeDeviceProc(), do not use the port or lock
  2518.     again!
  2519.  
  2520.    INPUTS
  2521.     name    - name of the object you wish to access.  This can be a
  2522.           relative path ("foo/bar"), relative to the current volume
  2523.           (":foo/bar"), or relative to a device/volume/assign
  2524.           ("foo:bar").
  2525.     devproc - A value returned by GetDeviceProc() before, or NULL
  2526.  
  2527.    RESULT
  2528.     devproc - a pointer to a DevProc structure or NULL
  2529.  
  2530.    BUGS
  2531.     Counter not currently active in 2.0.
  2532.     In 2.0 and 2.01, you HAD to check DVPF_ASSIGN before calling it again.
  2533.     This was fixed for the 2.02 release of V36.
  2534.  
  2535.    SEE ALSO
  2536.     FreeDeviceProc(), DeviceProc(), AssignLock(), AssignLate(),
  2537.     AssignPath()
  2538.  
  2539. dos.library/GetFileSysTask                         dos.library/GetFileSysTask
  2540.  
  2541.    NAME
  2542.     GetFileSysTask -- Returns the default filesystem for the process (V36)
  2543.  
  2544.    SYNOPSIS
  2545.     port = GetFileSysTask()
  2546.     D0
  2547.  
  2548.     struct MsgPort *GetFileSysTask(void)
  2549.  
  2550.    FUNCTION
  2551.     Returns the default filesystem task's port (pr_FileSystemTask) for the
  2552.     current process.
  2553.  
  2554.    RESULT
  2555.     port - The pr_MsgPort of the filesystem, or NULL.
  2556.  
  2557.    SEE ALSO
  2558.     SetFileSysTask(), Open()
  2559.  
  2560. dos.library/GetProgramDir                           dos.library/GetProgramDir
  2561.  
  2562.    NAME
  2563.     GetProgramDir -- Returns a lock on the directory the program was loaded
  2564.              from (V36)
  2565.  
  2566.    SYNOPSIS
  2567.     lock = GetProgramDir()
  2568.     D0
  2569.  
  2570.     BPTR GetProgramDir(void)
  2571.  
  2572.    FUNCTION
  2573.     Returns a shared lock on the directory the program was loaded from.
  2574.     This can be used for a program to find data files, etc, that are stored
  2575.     with the program, or to find the program file itself.  NULL returns are
  2576.     valid, and may occur, for example, when running a program from the
  2577.     resident list.  You should NOT unlock the lock.
  2578.  
  2579.    RESULT
  2580.     lock - A lock on the directory the current program was loaded from,
  2581.            or NULL if loaded from resident list, etc.
  2582.  
  2583.    BUGS
  2584.     Should return a lock for things loaded via resident.  Perhaps should
  2585.     return currentdir if NULL.
  2586.  
  2587.    SEE ALSO
  2588.     SetProgramDir(), Open()
  2589.  
  2590. dos.library/GetProgramName                         dos.library/GetProgramName
  2591.  
  2592.    NAME
  2593.     GetProgramName -- Returns the current program name (V36)
  2594.  
  2595.    SYNOPSIS
  2596.     success = GetProgramName(buf, len)
  2597.     D0                       D1   D2
  2598.  
  2599.     BOOL GetProgramName(STRPTR, LONG)
  2600.  
  2601.    FUNCTION
  2602.     Extracts the program name from the CLI structure and puts it 
  2603.     into the buffer.  If the buffer is too small, the name is truncated.
  2604.     If no CLI structure is present, a null string is returned in the
  2605.     buffer, and failure from the call (with IoErr() ==
  2606.     ERROR_OBJECT_WRONG_TYPE);
  2607.  
  2608.    INPUTS
  2609.     buf     - Buffer to hold extracted name
  2610.     len     - Number of bytes of space in buffer
  2611.  
  2612.    RESULT
  2613.     success - Success/failure indicator
  2614.  
  2615.    SEE ALSO
  2616.     SetProgramName()
  2617.  
  2618. dos.library/GetPrompt                                   dos.library/GetPrompt
  2619.  
  2620.    NAME
  2621.     GetPrompt -- Returns the prompt for the current process (V36)
  2622.  
  2623.    SYNOPSIS
  2624.     success = GetPrompt(buf, len)
  2625.     D0                  D1   D2
  2626.  
  2627.     BOOL GetPrompt(STRPTR, LONG)
  2628.  
  2629.    FUNCTION
  2630.     Extracts the prompt string from the CLI structure and puts it 
  2631.     into the buffer.  If the buffer is too small, the string is truncated 
  2632.     appropriately and a failure code returned.  If no CLI structure is 
  2633.     present, a null string is returned in the buffer, and failure from
  2634.     the call (with IoErr() == ERROR_OBJECT_WRONG_TYPE);
  2635.  
  2636.    INPUTS
  2637.     buf     - Buffer to hold extracted prompt
  2638.     len     - Number of bytes of space in buffer
  2639.  
  2640.    RESULT
  2641.     success - Success/failure indicator
  2642.  
  2643.    SEE ALSO
  2644.     SetPrompt()
  2645.  
  2646. dos.library/GetVar                                         dos.library/GetVar
  2647.  
  2648.    NAME
  2649.     GetVar -- Returns the value of a local or global variable (V36)
  2650.  
  2651.    SYNOPSIS
  2652.     len = GetVar( name, buffer, size, flags ) 
  2653.     D0           D1     D2     D3    D4
  2654.  
  2655.     LONG GetVar( STRPTR, STRPTR, LONG, ULONG ) 
  2656.  
  2657.    FUNCTION
  2658.     Gets the value of a local or environment variable.  It is advised to
  2659.      only use ASCII strings inside variables, but not required.  This stops
  2660.     putting characters into the destination when a \n is hit, unless
  2661.     GVF_BINARY_VAR is specified.  (The \n is not stored in the buffer.)
  2662.  
  2663.    INPUTS
  2664.     name   - pointer to a variable name.
  2665.     buffer - a user allocated area which will be used to store
  2666.          the value associated with the variable.
  2667.     size   - length of the buffer region in bytes.
  2668.     flags  - combination of type of var to get value of (low 8 bits), and
  2669.          flags to control the behavior of this routine.  Currently
  2670.          defined flags include:
  2671.  
  2672.             GVF_GLOBAL_ONLY - tries to get a global env variable.
  2673.             GVF_LOCAL_ONLY  - tries to get a local variable.
  2674.             GVF_BINARY_VAR  - don't stop at \n
  2675.             GVF_DONT_NULL_TERM - no null termination (only valid
  2676.                       for binary variables). (V37)
  2677.  
  2678.          The default is to try to get a local variable first, then
  2679.          to try to get a global environment variable.
  2680.  
  2681.    RESULT
  2682.     len -   Size of environment variable.  -1 indicates that the
  2683.         variable was not defined (if IoErr() returns
  2684.         ERROR_OBJECT_NOT_FOUND - it returns ERROR_BAD_NUMBER if
  2685.         you specify a size of 0).  If the value would overflow
  2686.         the user buffer, the buffer is truncated.  The buffer
  2687.         returned is null-terminated (even if GVF_BINARY_VAR is
  2688.         used, unless GVF_DONT_NULL_TERM is in effect).  If it
  2689.         succeeds, len is the number of characters put in the buffer
  2690.         (not including null termination), and IoErr() will return the
  2691.         the size of the variable (regardless of buffer size).
  2692.  
  2693.    BUGS
  2694.     LV_VAR is the only type that can be global.
  2695.     Under V36, we documented (and it returned) the size of the variable,
  2696.     not the number of characters transferred.  For V37 this was changed
  2697.     to the number of characters put in the buffer, and the total size
  2698.     of the variable is put in IoErr().
  2699.     GVF_DONT_NULL_TERM only works for local variables under V37.  For
  2700.     V39, it also works for globals.
  2701.  
  2702.    SEE ALSO
  2703.     SetVar(), DeleteVar(), FindVar(), <dos/var.h>
  2704.  
  2705. dos.library/Info                                             dos.library/Info
  2706.  
  2707.     NAME
  2708.     Info -- Returns information about the disk
  2709.  
  2710.     SYNOPSIS
  2711.     success = Info( lock, parameterBlock )
  2712.     D0        D1    D2
  2713.  
  2714.     BOOL Info(BPTR, struct InfoData *)
  2715.  
  2716.     FUNCTION
  2717.     Info() can be used to find information about any disk in use.
  2718.     'lock' refers to the disk, or any file on the disk. The parameter
  2719.     block is returned with information about the size of the disk,
  2720.     number of free blocks and any soft errors.
  2721.  
  2722.     INPUTS
  2723.     lock           - BCPL pointer to a lock
  2724.     parameterBlock - pointer to an InfoData structure
  2725.              (longword aligned)
  2726.  
  2727.     RESULTS
  2728.     success - boolean
  2729.  
  2730.     SPECIAL NOTE:
  2731.     Note that InfoData structure must be longword aligned.
  2732.  
  2733. dos.library/Inhibit                                       dos.library/Inhibit
  2734.  
  2735.    NAME
  2736.     Inhibit -- Inhibits access to a filesystem (V36)
  2737.  
  2738.    SYNOPSIS
  2739.     success = Inhibit(filesystem, flag)
  2740.     D0                    D1       D2
  2741.  
  2742.     BOOL Inhibit(STRPTR,LONG)
  2743.  
  2744.    FUNCTION
  2745.     Sends an ACTION_INHIBIT packet to the indicated handler.  This stops
  2746.     all activity by the handler until uninhibited.  When uninhibited,
  2747.     anything may have happened to the disk in the drive, or there may no
  2748.     longer be one.
  2749.  
  2750.    INPUTS
  2751.     filesystem - Name of device to inhibit (with ':')
  2752.     flag       - New status.  DOSTRUE = inhibited, FALSE = uninhibited
  2753.  
  2754.    RESULT
  2755.     success    - Success/failure indicator
  2756.  
  2757.    SEE ALSO
  2758.  
  2759. dos.library/Input                                           dos.library/Input
  2760.  
  2761.     NAME
  2762.     Input -- Identify the program's initial input file handle
  2763.  
  2764.     SYNOPSIS
  2765.     file = Input()
  2766.     D0
  2767.  
  2768.     BPTR Input(void)
  2769.  
  2770.     FUNCTION
  2771.     Input() is used to identify the initial input stream allocated when
  2772.     the program was initiated.  Never close the filehandle returned by
  2773.     Input!
  2774.  
  2775.     RESULTS
  2776.     file - BCPL pointer to a file handle
  2777.  
  2778.     SEE ALSO
  2779.     Output(), SelectInput()
  2780.  
  2781. dos.library/InternalLoadSeg                       dos.library/InternalLoadSeg
  2782.  
  2783.    NAME
  2784.     InternalLoadSeg -- Low-level load routine (V36)
  2785.  
  2786.    SYNOPSIS
  2787.     seglist = InternalLoadSeg(fh,table,functionarray,stack)
  2788.     D0              D0  A0        A1      A2
  2789.  
  2790.     BPTR InternalLoadSeg(BPTR,BPTR,LONG *,LONG *)
  2791.  
  2792.    FUNCTION
  2793.     Loads from fh.  Table is used when loading an overlay, otherwise
  2794.     should be NULL.  Functionarray is a pointer to an array of functions.
  2795.     Note that the current Seek position after loading may be at any point
  2796.     after the last hunk loaded.  The filehandle will not be closed.  If a
  2797.     stacksize is encoded in the file, the size will be stuffed in the
  2798.     LONG pointed to by stack.  This LONG should be initialized to your
  2799.     default value: InternalLoadSeg() will not change it if no stacksize
  2800.     is found. Clears unused portions of Code and Data hunks (as well as
  2801.     BSS hunks).  (This also applies to LoadSeg() and NewLoadSeg()).
  2802.  
  2803.     If the file being loaded is an overlaid file, this will return
  2804.     -(seglist).  All other results will be positive.
  2805.  
  2806.     NOTE to overlay users: InternalLoadSeg() does NOT return seglist in
  2807.     both D0 and D1, as LoadSeg does.  The current ovs.asm uses LoadSeg(),
  2808.     and assumes returns are in D1.  We will support this for LoadSeg()
  2809.     ONLY.
  2810.  
  2811.    INPUTS
  2812.     fh          - Filehandle to load from.
  2813.     table          - When loading an overlay, otherwise ignored.
  2814.     functionarray - Array of function to be used for read, alloc, and free.
  2815.        FuncTable[0] ->  Actual = ReadFunc(readhandle,buffer,length),DOSBase
  2816.                     D0                D1         A0     D0      A6
  2817.        FuncTable[1] ->  Memory = AllocFunc(size,flags), Execbase
  2818.                     D0                 D0   D1      a6
  2819.        FuncTable[2] ->  FreeFunc(memory,size), Execbase
  2820.                              A1     D0     a6
  2821.     stack         - Pointer to storage (ULONG) for stacksize.
  2822.  
  2823.    RESULT
  2824.     seglist          - Seglist loaded or NULL.  NOT returned in D1!
  2825.  
  2826.    BUGS
  2827.     Really should use tags.
  2828.  
  2829.    SEE ALSO
  2830.     LoadSeg(), UnLoadSeg(), NewLoadSeg(), InternalUnLoadSeg()
  2831.  
  2832. dos.library/InternalUnLoadSeg                   dos.library/InternalUnLoadSeg
  2833.  
  2834.    NAME
  2835.     InternalUnLoadSeg -- Unloads a seglist loaded with InternalLoadSeg() (V36)
  2836.  
  2837.    SYNOPSIS
  2838.     success = InternalUnLoadSeg(seglist,FreeFunc)
  2839.       D0                  D1       A1
  2840.  
  2841.     BOOL InternalUnLoadSeg(BPTR,void (*)(STRPTR,ULONG))
  2842.  
  2843.    FUNCTION
  2844.     Unloads a seglist using freefunc to free segments.  Freefunc is called
  2845.     as for InternalLoadSeg.  NOTE: will call Close() for overlaid
  2846.     seglists.
  2847.  
  2848.    INPUTS
  2849.     seglist  - Seglist to be unloaded
  2850.     FreeFunc - Function called to free memory
  2851.  
  2852.    RESULT
  2853.     success - returns whether everything went OK (since this may close
  2854.           files).  Also returns FALSE if seglist was NULL.
  2855.  
  2856.    BUGS
  2857.     Really should use tags
  2858.  
  2859.    SEE ALSO
  2860.     LoadSeg(), UnLoadSeg(), InternalLoadSeg(), NewUnLoadSeg(), Close()
  2861.  
  2862. dos.library/IoErr                                           dos.library/IoErr
  2863.  
  2864.     NAME
  2865.     IoErr -- Return extra information from the system
  2866.  
  2867.     SYNOPSIS
  2868.     error = IoErr()
  2869.       D0
  2870.  
  2871.     LONG IoErr(void)
  2872.  
  2873.     FUNCTION
  2874.     Most I/O routines return zero to indicate an error. When this 
  2875.     happens (or whatever the defined error return for the routine)
  2876.     this routine may be called to determine more information. It is
  2877.     also used in some routines to pass back a secondary result.
  2878.  
  2879.     Note: there is no guarantee as to the value returned from IoErr()
  2880.     after a successful operation, unless to specified by the routine.
  2881.  
  2882.     RESULTS
  2883.     error - integer
  2884.  
  2885.     SEE ALSO
  2886.     Fault(), PrintFault(), SetIoErr()
  2887.  
  2888. dos.library/IsFileSystem                             dos.library/IsFileSystem
  2889.  
  2890.    NAME
  2891.     IsFileSystem -- returns whether a Dos handler is a filesystem (V36)
  2892.  
  2893.    SYNOPSIS
  2894.     result = IsFileSystem(name)
  2895.     D0                     D1
  2896.  
  2897.     BOOL IsFileSystem(STRPTR)
  2898.  
  2899.    FUNCTION
  2900.     Returns whether the device is a filesystem or not.  A filesystem
  2901.     supports seperate files storing information.  It may also support
  2902.     sub-directories, but is not required to.  If the filesystem doesn't
  2903.     support this new packet, IsFileSystem() will use Lock(":",...) as
  2904.     an indicator.
  2905.  
  2906.    INPUTS
  2907.     name   - Name of device in question, with trailing ':'.
  2908.  
  2909.    RESULT
  2910.     result - Flag to indicate if device is a file system
  2911.  
  2912.    SEE ALSO
  2913.     Lock()
  2914.  
  2915. dos.library/IsInteractive                           dos.library/IsInteractive
  2916.  
  2917.     NAME
  2918.     IsInteractive -- Discover whether a file is "interactive"
  2919.  
  2920.     SYNOPSIS
  2921.     status = IsInteractive( file )
  2922.     D0            D1
  2923.  
  2924.     BOOL IsInteractive(BPTR)
  2925.  
  2926.     FUNCTION
  2927.     The return value 'status' indicates whether the file associated
  2928.     with the file handle 'file' is connected to a virtual terminal.
  2929.  
  2930.     INPUTS
  2931.     file - BCPL pointer to a file handle
  2932.  
  2933.     RESULTS
  2934.     status - boolean
  2935.  
  2936.     SEE ALSO
  2937.  
  2938. dos.library/LoadSeg                                       dos.library/LoadSeg
  2939.  
  2940.     NAME
  2941.     LoadSeg -- Scatterload a loadable file into memory
  2942.  
  2943.     SYNOPSIS
  2944.     seglist = LoadSeg( name )
  2945.     D0           D1
  2946.  
  2947.     BPTR LoadSeg(STRPTR)
  2948.  
  2949.     FUNCTION
  2950.     The file 'name' should be a load module produced by the linker.
  2951.     LoadSeg() scatterloads the CODE, DATA and BSS segments into memory,
  2952.     chaining together the segments with BPTR's on their first words.
  2953.     The end of the chain is indicated by a zero.  There can be any number
  2954.     of segments in a file.  All necessary relocation is handled by
  2955.     LoadSeg().
  2956.  
  2957.     In the event of an error any blocks loaded will be unloaded and a
  2958.     NULL result returned.
  2959.  
  2960.     If the module is correctly loaded then the output will be a pointer
  2961.     at the beginning of the list of blocks. Loaded code is unloaded via
  2962.     a call to UnLoadSeg().
  2963.  
  2964.     INPUTS
  2965.     name - pointer to a null-terminated string
  2966.  
  2967.     RESULTS
  2968.     seglist - BCPL pointer to a seglist
  2969.  
  2970.     SEE ALSO
  2971.     UnLoadSeg(), InternalLoadSeg(), InternalUnLoadSeg(), CreateProc(),
  2972.     CreateNewProc(), NewLoadSeg().
  2973.  
  2974. dos.library/Lock                                             dos.library/Lock
  2975.  
  2976.     NAME
  2977.     Lock -- Lock a directory or file
  2978.  
  2979.     SYNOPSIS
  2980.     lock  = Lock( name, accessMode )
  2981.     D0          D1    D2
  2982.  
  2983.     BPTR Lock(STRPTR, LONG)
  2984.  
  2985.     FUNCTION
  2986.     A filing system lock on the file or directory 'name' is returned if
  2987.     possible.
  2988.  
  2989.     If the accessMode is ACCESS_READ, the lock is a shared read lock;
  2990.     if the accessMode is ACCESS_WRITE then it is an exclusive write
  2991.     lock.  Do not use random values for mode.
  2992.  
  2993.     If Lock() fails (that is, if it cannot obtain a filing system lock
  2994.     on the file or directory) it returns a zero.
  2995.  
  2996.     Tricky assumptions about the internal format of a lock are unwise,
  2997.     as are any attempts to use the fl_Link or fl_Access fields.
  2998.  
  2999.     INPUTS
  3000.     name       - pointer to a null-terminated string
  3001.     accessMode - integer
  3002.  
  3003.     RESULTS
  3004.     lock - BCPL pointer to a lock
  3005.  
  3006.     SEE ALSO
  3007.     UnLock(), DupLock(), ChangeMode(), NameFromLock(), DupLockFromFH()
  3008.  
  3009. dos.library/LockDosList                               dos.library/LockDosList
  3010.  
  3011.    NAME
  3012.     LockDosList -- Locks the specified Dos Lists for use (V36)
  3013.  
  3014.    SYNOPSIS
  3015.     dlist = LockDosList(flags)
  3016.     D0             D1
  3017.  
  3018.     struct DosList *LockDosList(ULONG)
  3019.  
  3020.    FUNCTION
  3021.     Locks the dos device list in preparation to walk the list.
  3022.     If the list is 'busy' then this routine will not return until it is 
  3023.     available.  This routine "nests": you can call it multiple times, and
  3024.     then must unlock it the same number of times.  The dlist
  3025.     returned is NOT a valid entry: it is a special value.  Note that
  3026.     for 1.3 compatibility, it also does a Forbid() - this will probably
  3027.     be removed at some future time.  The 1.3 Forbid() locking of this
  3028.     list had some race conditions.  The pointer returned by this is NOT
  3029.     an actual DosList pointer - you should use on of the other DosEntry
  3030.     calls to get actual pointers to DosList structures (such as
  3031.     NextDosEntry()), passing the value returned by LockDosList()
  3032.     as the dlist value.
  3033.  
  3034.     Note for handler writers: you should never call this function with
  3035.     LDF_WRITE, since it can deadlock you (if someone has it read-locked
  3036.     and they're trying to send you a packet).  Use AttemptLockDosList()
  3037.     instead, and effectively busy-wait with delays for the list to be
  3038.     available.  The other option is that you can spawn a process to
  3039.     add the entry safely.
  3040.  
  3041.     As an example, here's how you can search for all volumes of a specific
  3042.     name and do something with them:
  3043.  
  3044.     2.0 way:
  3045.  
  3046.         dl = LockDosList(LDF_VOLUMES|LDF_READ);
  3047.         while (dl = FindDosEntry(dl,name,LDF_VOLUMES))
  3048.         {
  3049.             Add to list of volumes to process or break out of
  3050.             the while loop.
  3051.             (You could try using it here, but I advise
  3052.             against it for compatability reasons if you
  3053.             are planning on continuing to examine the list.)
  3054.         }
  3055.         
  3056.         process list of volumes saved above, or current entry if
  3057.         you're only interested in the first one of that name.
  3058.  
  3059.         UnLockDosList(LDF_VOLUMES|LDF_READ);
  3060.                   \* must not use dl after this! *\
  3061.  
  3062.     1.3/2.0 way:
  3063.  
  3064.         if (version >= 36)
  3065.             dl = LockDosList(LDF_VOLUMES|LDF_READ);
  3066.         else {
  3067.             Forbid();
  3068.             /* tricky! note dol_Next is at offset 0! */
  3069.             dl = &(...->di_DeviceList);
  3070.         }
  3071.  
  3072.         while (version >= 36 ?
  3073.                 dl = FindDosEntry(dl,name,LDF_VOLUMES) :
  3074.                     dl = yourfindentry(dl,name,DLT_VOLUME))
  3075.         {
  3076.             Add to list of volumes to process, or break out of
  3077.             the while loop.
  3078.             Do NOT lock foo1/foo2 here if you will continue
  3079.             to examine the list - it breaks the forbid
  3080.             and the list may change on you.
  3081.         }
  3082.         
  3083.         process list of volumes saved above, or current entry if
  3084.         you're only interested in the first one of that name.
  3085.  
  3086.         if (version >= 36)
  3087.             UnLockDosList(LDF_VOLUMES|LDF_READ);
  3088.         else
  3089.             Permit();
  3090.         \* must not use dl after this! *\
  3091.         ...
  3092.  
  3093.         struct DosList *
  3094.         yourfindentry (struct DosList *dl, STRPTRname, type)
  3095.         {
  3096.         \* tricky - depends on dol_Next being at offset 0,
  3097.            and the initial ptr being a ptr to di_DeviceList! *\
  3098.             while (dl = dl->dol_Next)
  3099.             {
  3100.                 if (dl->dol_Type == type &&
  3101.                 stricmp(name,BADDR(dl->dol_Name)+1) == 0)
  3102.                 {
  3103.                 break;
  3104.                 }
  3105.             }
  3106.             return dl;
  3107.         }
  3108.  
  3109.    INPUTS
  3110.     flags - Flags stating which types of nodes you want to lock.
  3111.  
  3112.    RESULT
  3113.     dlist - Pointer to the head of the list.  NOT a valid node!
  3114.  
  3115.    SEE ALSO
  3116.     AttemptLockDosList(), UnLockDosList(), Forbid(), NextDosEntry()
  3117.  
  3118. dos.library/LockRecord                                 dos.library/LockRecord
  3119.  
  3120.    NAME
  3121.     LockRecord -- Locks a portion of a file (V36)
  3122.  
  3123.    SYNOPSIS
  3124.     success = LockRecord(fh,offset,length,mode,timeout)
  3125.     D0                   D1   D2     D3    D4    D5
  3126.  
  3127.     BOOL LockRecord(BPTR,ULONG,ULONG,ULONG,ULONG)
  3128.  
  3129.    FUNCTION
  3130.     This locks a portion of a file for exclusive access.  Timeout is how
  3131.     long to wait in ticks (1/50 sec) for the record to be available.
  3132.  
  3133.     Valid modes are:
  3134.         REC_EXCLUSIVE
  3135.         REC_EXCLUSIVE_IMMED
  3136.         REC_SHARED
  3137.         REC_SHARED_IMMED
  3138.     For the IMMED modes, the timeout is ignored.
  3139.  
  3140.     Record locks are tied to the filehandle used to create them.  The
  3141.     same filehandle can get any number of exclusive locks on the same
  3142.     record, for example.  These are cooperative locks, they only
  3143.     affect other people calling LockRecord().
  3144.  
  3145.    INPUTS
  3146.     fh      - File handle for which to lock the record
  3147.     offset  - Record start position
  3148.     length  - Length of record in bytes
  3149.     mode    - Type of lock requester
  3150.     timeout - Timeout interval in ticks.  0 is legal.
  3151.  
  3152.    RESULT
  3153.     success - Success or failure
  3154.  
  3155.    BUGS
  3156.     In 2.0 through 2.02 (V36), LockRecord() only worked in the ramdisk.
  3157.     Attempting to lock records on the disk filesystem causes a crash.
  3158.     This was fixed for V37.
  3159.  
  3160.    SEE ALSO
  3161.     LockRecords(), UnLockRecord(), UnLockRecords()
  3162.  
  3163. dos.library/LockRecords                               dos.library/LockRecords
  3164.  
  3165.    NAME
  3166.     LockRecords -- Lock a series of records (V36)
  3167.  
  3168.    SYNOPSIS
  3169.     success = LockRecords(record_array,timeout)
  3170.     D0                       D1           D2
  3171.  
  3172.     BOOL LockRecords(struct RecordLock *,ULONG)
  3173.  
  3174.    FUNCTION
  3175.     This locks several records within a file for exclusive access.
  3176.     Timeout is how long to wait in ticks for the records to be available.
  3177.     The wait is applied to each attempt to lock each record in the list.
  3178.     It is recommended that you always lock a set of records in the same
  3179.     order to reduce possibilities of deadlock.
  3180.  
  3181.     The array of RecordLock structures is terminated by an entry with
  3182.     rec_FH of NULL.
  3183.  
  3184.    INPUTS
  3185.     record_array - List of records to be locked
  3186.     timeout      - Timeout interval.  0 is legal
  3187.  
  3188.    RESULT
  3189.     success      - Success or failure
  3190.  
  3191.    BUGS
  3192.     See LockRecord()
  3193.  
  3194.    SEE ALSO
  3195.     LockRecord(), UnLockRecord(), UnLockRecords()
  3196.  
  3197. dos.library/MakeDosEntry                             dos.library/MakeDosEntry
  3198.  
  3199.    NAME
  3200.     MakeDosEntry -- Creates a DosList structure (V36)
  3201.  
  3202.    SYNOPSIS
  3203.     newdlist = MakeDosEntry(name, type)
  3204.     D0                       D1    D2
  3205.  
  3206.     struct DosList *MakeDosEntry(STRPTR, LONG)
  3207.  
  3208.    FUNCTION
  3209.     Create a DosList structure, including allocating a name and correctly
  3210.     null-terminating the BSTR.  It also sets the dol_Type field, and sets
  3211.     all other fields to 0.  This routine should be eliminated and replaced
  3212.     by a value passed to AllocDosObject()!
  3213.  
  3214.    INPUTS
  3215.     name - name for the device/volume/assign node.
  3216.     type - type of node.
  3217.  
  3218.    RESULT
  3219.     newdlist - The new device entry or NULL.
  3220.  
  3221.    SEE ALSO
  3222.     AddDosEntry(), RemDosEntry(), FindDosEntry(), LockDosList(),
  3223.     NextDosEntry(), FreeDosEntry()
  3224.  
  3225. dos.library/MakeLink                                     dos.library/MakeLink
  3226.  
  3227.    NAME
  3228.     MakeLink -- Creates a filesystem link (V36)
  3229.  
  3230.    SYNOPSIS
  3231.     success = MakeLink( name, dest, soft )
  3232.     D0             D1    D2    D3
  3233.  
  3234.     BOOL MakeLink( STRPTR, LONG, LONG )
  3235.  
  3236.    FUNCTION
  3237.     Create a filesystem link from 'name' to dest.  For "soft-links",
  3238.     dest is a pointer to a null-terminated path string.  For "hard-
  3239.     links", dest is a lock (BPTR).  'soft' is FALSE for hard-links,
  3240.     non-zero otherwise.
  3241.  
  3242.     Soft-links are resolved at access time by a combination of the
  3243.     filesystem (by returning ERROR_IS_SOFT_LINK to dos), and by
  3244.     Dos (using ReadLink() to resolve any links that are hit).
  3245.  
  3246.     Hard-links are resolved by the filesystem in question.  A series
  3247.     of hard-links to a file are all equivalent to the file itself.
  3248.     If one of the links (or the original entry for the file) is 
  3249.     deleted, the data remains until there are no links left.
  3250.  
  3251.    INPUTS
  3252.     name - Name of the link to create
  3253.     dest - CPTR to path string, or BPTR lock
  3254.     soft - FALSE for hard-links, non-zero for soft-links
  3255.  
  3256.    RESULT
  3257.     Success - boolean
  3258.  
  3259.    BUGS
  3260.     In V36, soft-links didn't work in the ROM filesystem.  This was
  3261.     fixed for V37.
  3262.  
  3263.    SEE ALSO
  3264.     ReadLink(), Open(), Lock()
  3265.  
  3266. dos.library/MatchEnd                                     dos.library/MatchEnd
  3267.  
  3268.    NAME
  3269.     MatchEnd -- Free storage allocated for MatchFirst()/MatchNext() (V36)
  3270.  
  3271.    SYNOPSIS
  3272.     MatchEnd(AnchorPath)
  3273.                  D1
  3274.  
  3275.     VOID MatchEnd(struct AnchorPath *)
  3276.  
  3277.    FUNCTION
  3278.     Return all storage associated with a given search.
  3279.  
  3280.    INPUTS
  3281.     AnchorPath - Anchor used for MatchFirst()/MatchNext()
  3282.              MUST be longword aligned!
  3283.  
  3284.    SEE ALSO
  3285.     MatchFirst(), ParsePattern(), Examine(), CurrentDir(), Examine(),
  3286.     MatchNext(), ExNext(), <dos/dosasl.h>
  3287.  
  3288. dos.library/MatchFirst                                 dos.library/MatchFirst
  3289.  
  3290.    NAME
  3291.     MatchFirst -- Finds file that matches pattern (V36)
  3292.  
  3293.    SYNOPSIS
  3294.     error = MatchFirst(pat, AnchorPath)
  3295.     D0                 D1       D2
  3296.  
  3297.     LONG MatchFirst(STRPTR, struct AnchorPath *)
  3298.  
  3299.    FUNCTION
  3300.     Locates the first file or directory that matches a given pattern.
  3301.     MatchFirst() is passed your pattern (you do not pass it through
  3302.     ParsePattern() - MatchFirst() does that for you), and the control
  3303.     structure.  MatchFirst() normally initializes your AnchorPath
  3304.     structure for you, and returns the first file that matched your
  3305.     pattern, or an error.  Note that MatchFirst()/MatchNext() are unusual
  3306.     for Dos in that they return 0 for success, or the error code (see
  3307.     <dos/dos.h>), instead of the application getting the error code
  3308.     from IoErr().
  3309.  
  3310.     When looking at the result of MatchFirst()/MatchNext(), the ap_Info
  3311.     field of your AnchorPath has the results of an Examine() of the object.
  3312.     You normally get the name of the object from fib_FileName, and the
  3313.     directory it's in from ap_Current->an_Lock.  To access this object,
  3314.     normally you would temporarily CurrentDir() to the lock, do an action
  3315.     to the file/dir, and then CurrentDir() back to your original directory.
  3316.     This makes certain you affect the right object even when two volumes
  3317.     of the same name are in the system.  You can use ap_Buf (with
  3318.     ap_Strlen) to get a name to report to the user.
  3319.  
  3320.     To initialize the AnchorPath structure (particularily when reusing
  3321.     it), set ap_BreakBits to the signal bits (CDEF) that you want to take
  3322.     a break on, or NULL, if you don't want to convenience the user.
  3323.     ap_Flags should be set to any flags you need or all 0's otherwise.
  3324.     ap_FoundBreak should be cleared if you'll be using breaks.
  3325.  
  3326.     If you want to have the FULL PATH NAME of the files you found,
  3327.     allocate a buffer at the END of this structure, and put the size of
  3328.     it into ap_Strlen.  If you don't want the full path name, make sure
  3329.     you set ap_Strlen to zero.  In this case, the name of the file, and
  3330.     stats are available in the ap_Info, as per usual.
  3331.  
  3332.     Then call MatchFirst() and then afterwards, MatchNext() with this
  3333.     structure.  You should check the return value each time (see below)
  3334.     and take the appropriate action, ultimately calling MatchEnd() when
  3335.     there are no more files or you are done.  You can tell when you are
  3336.     done by checking for the normal AmigaDOS return code
  3337.     ERROR_NO_MORE_ENTRIES.
  3338.  
  3339.     Note: patterns with trailing slashes may cause MatchFirst()/MatchNext()
  3340.     to return with an ap_Current->an_Lock on the object, and a filename
  3341.     of the empty string ("").
  3342.  
  3343.     See ParsePattern() for more information on the patterns.
  3344.  
  3345.    INPUTS
  3346.     pat        - Pattern to search for
  3347.     AnchorPath - Place holder for search.  MUST be longword aligned!
  3348.  
  3349.    RESULT
  3350.     error - 0 for success or error code.  (Opposite of most Dos calls!)
  3351.  
  3352.    BUGS
  3353.     In V36, there were a number of bugs with MatchFirst()/MatchNext().
  3354.     One was that if you entered a directory with a name like "df0:l"
  3355.     using DODIR, it would re-lock the full string "df0:l", which can
  3356.     cause problems if the disk has changed.  It also had problems
  3357.     with patterns such as #?/abc/def - the ap_Current->an_Lock would
  3358.     not be on the directory def is found in.  ap_Buf would be correct,
  3359.     however.  It had similar problems with patterns with trailing
  3360.     slashes.  These have been fixed for V37 and later.
  3361.  
  3362.     A bug that has not been fixed for V37 concerns a pattern of a
  3363.     single directory name (such as "l").  If you enter such a directory
  3364.     via DODIR, it re-locks l relative to the current directory.  Thus
  3365.     you must not change the current directory before calling MatchNext()
  3366.     with DODIR in that situation.  If you aren't using DODIR to enter
  3367.     directories you can ignore this.  This may be fixed in some upcoming
  3368.     release.
  3369.  
  3370.    SEE ALSO
  3371.     MatchNext(), ParsePattern(), Examine(), CurrentDir(), Examine(),
  3372.     MatchEnd(), ExNext(), <dos/dosasl.h>
  3373.  
  3374. dos.library/MatchNext                                   dos.library/MatchNext
  3375.  
  3376.    NAME
  3377.     MatchNext - Finds the next file or directory that matches pattern (V36)
  3378.  
  3379.    SYNOPSIS
  3380.     error = MatchNext(AnchorPath)
  3381.     D0                    D1
  3382.  
  3383.     LONG MatchNext(struct AnchorPath *)
  3384.  
  3385.    FUNCTION
  3386.     Locates the next file or directory that matches a given pattern.
  3387.     See <dos/dosasl.h> for more information.  Various bits in the flags
  3388.     allow the application to control the operation of MatchNext().
  3389.  
  3390.     See MatchFirst() for other notes.
  3391.  
  3392.    INPUTS
  3393.     AnchorPath - Place holder for search.  MUST be longword aligned!
  3394.  
  3395.    RESULT
  3396.     error - 0 for success or error code.  (Opposite of most Dos calls)
  3397.  
  3398.    BUGS
  3399.     See MatchFirst().
  3400.  
  3401.    SEE ALSO
  3402.     MatchFirst(), ParsePattern(), Examine(), CurrentDir(), Examine(),
  3403.     MatchEnd(), ExNext(), <dos/dosasl.h>
  3404.  
  3405. dos.library/MatchPattern                             dos.library/MatchPattern
  3406.  
  3407.    NAME
  3408.     MatchPattern --  Checks for a pattern match with a string (V36)
  3409.  
  3410.    SYNOPSIS
  3411.     match = MatchPattern(pat, str)
  3412.     D0                   D1   D2
  3413.  
  3414.     BOOL MatchPattern(STRPTR, STRPTR)
  3415.  
  3416.    FUNCTION
  3417.     Checks for a pattern match with a string.  The pattern must be a
  3418.     tokenized string output by ParsePattern().  This routine is
  3419.     case-sensitive.
  3420.  
  3421.     NOTE: this routine is highly recursive.  You must have at least
  3422.     1500 free bytes of stack to call this (it will cut off it's
  3423.     recursion before going any deeper than that and return failure).
  3424.     That's _currently_ enough for about 100 levels deep of #, (, ~, etc.
  3425.  
  3426.    INPUTS
  3427.     pat - Special pattern string to match as returned by ParsePattern()
  3428.     str - String to match against given pattern
  3429.  
  3430.    RESULT
  3431.     match - success or failure of pattern match.  On failure,
  3432.         IoErr() will return 0 or ERROR_TOO_MANY_LEVELS (starting
  3433.         with V37 - before that there was no stack checking).
  3434.  
  3435.    SEE ALSO
  3436.     ParsePattern(), MatchPatternNoCase(), MatchFirst(), MatchNext()
  3437.  
  3438. dos.library/MatchPatternNoCase                 dos.library/MatchPatternNoCase
  3439.  
  3440.    NAME
  3441.     MatchPatternNoCase --  Checks for a pattern match with a string (V37)
  3442.  
  3443.    SYNOPSIS
  3444.     match = MatchPatternNoCase(pat, str)
  3445.     D0                         D1   D2
  3446.  
  3447.     BOOL MatchPatternNoCase(STRPTR, STRPTR)
  3448.  
  3449.    FUNCTION
  3450.     Checks for a pattern match with a string.  The pattern must be a
  3451.     tokenized string output by ParsePatternNoCase().  This routine is
  3452.     case-insensitive.
  3453.  
  3454.     NOTE: this routine is highly recursive.  You must have at least
  3455.     1500 free bytes of stack to call this (it will cut off it's
  3456.     recursion before going any deeper than that and return failure).
  3457.     That's _currently_ enough for about 100 levels deep of #, (, ~, etc.
  3458.  
  3459.    INPUTS
  3460.     pat - Special pattern string to match as returned by ParsePatternNoCase()
  3461.     str - String to match against given pattern
  3462.  
  3463.    RESULT
  3464.     match - success or failure of pattern match.  On failure,
  3465.         IoErr() will return 0 or ERROR_TOO_MANY_LEVELS (starting
  3466.         with V37 - before that there was no stack checking).
  3467.  
  3468.    BUGS
  3469.     See ParsePatternNoCase().
  3470.  
  3471.    SEE ALSO
  3472.     ParsePatternNoCase(), MatchPattern(), MatchFirst(), MatchNext()
  3473.  
  3474. dos.library/MaxCli                                         dos.library/MaxCli
  3475.  
  3476.    NAME
  3477.     MaxCli -- returns the highest CLI process number possibly in use (V36)
  3478.  
  3479.    SYNOPSIS
  3480.     number = MaxCli()
  3481.     D0
  3482.  
  3483.     LONG MaxCli(void)
  3484.  
  3485.    FUNCTION
  3486.     Returns the highest CLI number that may be in use.  CLI numbers are
  3487.     reused, and are usually as small as possible.  To find all CLIs, scan
  3488.     using FindCliProc() from 1 to MaxCLI().  The number returned by
  3489.     MaxCli() may change as processes are created and destroyed.
  3490.  
  3491.    RESULT
  3492.     number - The highest CLI number that _may_ be in use.
  3493.  
  3494.    SEE ALSO
  3495.     FindCliProc(), Cli()
  3496.  
  3497. dos.library/NameFromFH                                 dos.library/NameFromFH
  3498.  
  3499.    NAME
  3500.     NameFromFH -- Get the name of an open filehandle (V36)
  3501.  
  3502.    SYNOPSIS
  3503.     success = NameFromFH(fh, buffer, len)
  3504.     D0                   D1    D2    D3
  3505.  
  3506.     BOOL NameFromFH(BPTR, STRPTR, LONG)
  3507.  
  3508.    FUNCTION
  3509.     Returns a fully qualified path for the filehandle.  This routine is
  3510.     guaranteed not to write more than len characters into the buffer.  The
  3511.     name will be null-terminated.  See NameFromLock() for more information.
  3512.  
  3513.     Note: Older filesystems that don't support ExamineFH() will cause
  3514.     NameFromFH() to fail with ERROR_ACTION_NOT_SUPPORTED.
  3515.  
  3516.    INPUTS
  3517.     fh     - Lock of object to be examined.
  3518.     buffer - Buffer to store name.
  3519.     len    - Length of buffer.
  3520.  
  3521.    RESULT
  3522.     success - Success/failure indicator.
  3523.  
  3524.    SEE ALSO
  3525.     NameFromLock(), ExamineFH()
  3526.  
  3527. dos.library/NameFromLock                             dos.library/NameFromLock
  3528.  
  3529.    NAME
  3530.     NameFromLock -- Returns the name of a locked object (V36)
  3531.  
  3532.    SYNOPSIS
  3533.     success = NameFromLock(lock, buffer, len)
  3534.     D0                      D1     D2    D3
  3535.  
  3536.     BOOL NameFromLock(BPTR, STRPTR, LONG)
  3537.  
  3538.    FUNCTION
  3539.     Returns a fully qualified path for the lock.  This routine is
  3540.     guaranteed not to write more than len characters into the buffer.  The
  3541.     name will be null-terminated.  NOTE: if the volume is not mounted,
  3542.     the system will request it (unless of course you set pr_WindowPtr to
  3543.     -1).  If the volume is not mounted or inserted, it will return an
  3544.     error.  If the lock passed in is NULL, "SYS:" will be returned. If
  3545.     the buffer is too short, an error will be returned, and IoErr() will
  3546.     return ERROR_LINE_TOO_LONG.
  3547.  
  3548.    INPUTS
  3549.     lock   - Lock of object to be examined.
  3550.     buffer - Buffer to store name.
  3551.     len    - Length of buffer.
  3552.  
  3553.    RESULT
  3554.     success - Success/failure indicator.
  3555.  
  3556.    BUGS
  3557.     Should return the name of the boot volume instead of SYS: for a NULL
  3558.     lock.
  3559.  
  3560.    SEE ALSO
  3561.     NameFromFH(), Lock()
  3562.  
  3563. dos.library/NewLoadSeg                                 dos.library/NewLoadSeg
  3564.  
  3565.    NAME
  3566.     NewLoadSeg -- Improved version of LoadSeg for stacksizes (V36)
  3567.  
  3568.    SYNOPSIS
  3569.     seglist = NewLoadSeg(file, tags)
  3570.     D0              D1    D2
  3571.  
  3572.     BPTR NewLoadSeg(STRPTR, struct TagItem *)
  3573.  
  3574.     seglist = NewLoadSegTagList(file, tags)
  3575.     D0                 D1    D2
  3576.  
  3577.     BPTR NewLoadSegTagList(STRPTR, struct TagItem *)
  3578.  
  3579.     seglist = NewLoadSegTags(file, ...)
  3580.  
  3581.     BPTR NewLoadSegTags(STRPTR, ...)
  3582.  
  3583.    FUNCTION
  3584.     Does a LoadSeg on a file, and takes additional actions based on the
  3585.     tags supplied.
  3586.  
  3587.     Clears unused portions of Code and Data hunks (as well as BSS hunks).
  3588.     (This also applies to InternalLoadSeg() and LoadSeg()).
  3589.  
  3590.     NOTE to overlay users: NewLoadSeg() does NOT return seglist in
  3591.     both D0 and D1, as LoadSeg does.  The current ovs.asm uses LoadSeg(),
  3592.     and assumes returns are in D1.  We will support this for LoadSeg()
  3593.     ONLY.
  3594.  
  3595.    INPUTS
  3596.     file - Filename of file to load
  3597.     tags - pointer to tagitem array
  3598.  
  3599.    RESULT
  3600.     seglist - Seglist loaded, or NULL
  3601.  
  3602.    BUGS
  3603.     No tags are currently defined.
  3604.  
  3605.    SEE ALSO
  3606.     LoadSeg(), UnLoadSeg(), InternalLoadSeg(), InternalUnLoadSeg()
  3607.  
  3608. dos.library/NextDosEntry                             dos.library/NextDosEntry
  3609.  
  3610.    NAME
  3611.     NextDosEntry -- Get the next Dos List entry (V36)
  3612.  
  3613.    SYNOPSIS
  3614.     newdlist = NextDosEntry(dlist,flags)
  3615.     D0                       D1    D2
  3616.  
  3617.     struct DosList *NextDosEntry(struct DosList *,ULONG)
  3618.  
  3619.    FUNCTION
  3620.     Find the next Dos List entry of the right type.  You MUST have locked
  3621.     the types you're looking for.  Returns NULL if there are no more of
  3622.     that type in the list.
  3623.  
  3624.    INPUTS
  3625.     dlist    - The current device entry.
  3626.     flags     - What type of entries to look for.
  3627.  
  3628.    RESULT
  3629.     newdlist - The next device entry of the right type or NULL.
  3630.  
  3631.    SEE ALSO
  3632.     AddDosEntry(), RemDosEntry(), FindDosEntry(), LockDosList(),
  3633.     MakeDosEntry(), FreeDosEntry()
  3634.  
  3635. dos.library/Open                                             dos.library/Open
  3636.  
  3637.     NAME
  3638.     Open -- Open a file for input or output
  3639.  
  3640.     SYNOPSIS
  3641.     file = Open( name, accessMode )
  3642.     D0         D1    D2
  3643.  
  3644.     BPTR Open(STRPTR, LONG)
  3645.  
  3646.     FUNCTION
  3647.     The named file is opened and a file handle returned.  If the
  3648.     accessMode is MODE_OLDFILE, an existing file is opened for reading
  3649.     or writing. If the value is MODE_NEWFILE, a new file is created for
  3650.     writing. MODE_READWRITE opens a file with an shared lock, but
  3651.     creates it if it didn't exist.  Open types are documented in the
  3652.     <dos/dos.h> or <libraries/dos.h> include file.
  3653.  
  3654.     The 'name' can be a filename (optionally prefaced by a device
  3655.     name), a simple device such as NIL:, a window specification such as
  3656.     CON: or RAW: followed by window parameters, or "*", representing the
  3657.     current window.  Note that as of V36, "*" is obsolete, and CONSOLE:
  3658.     should be used instead.
  3659.  
  3660.     If the file cannot be opened for any reason, the value returned
  3661.     will be zero, and a secondary error code will be available by
  3662.     calling the routine IoErr().
  3663.  
  3664.     INPUTS
  3665.     name       - pointer to a null-terminated string
  3666.     accessMode - integer
  3667.  
  3668.     RESULTS
  3669.     file - BCPL pointer to a file handle
  3670.  
  3671.     SEE ALSO
  3672.     Close(), ChangeMode(), NameFromFH(), ParentOfFH(), ExamineFH()
  3673.  
  3674. dos.library/OpenFromLock                             dos.library/OpenFromLock
  3675.  
  3676.    NAME
  3677.     OpenFromLock -- Opens a file you have a lock on (V36)
  3678.  
  3679.    SYNOPSIS
  3680.     fh = OpenFromLock(lock)
  3681.     D0                 D1
  3682.  
  3683.     BPTR OpenFromLock(BPTR)
  3684.  
  3685.    FUNCTION
  3686.     Given a lock, this routine performs an open on that lock.  If the open
  3687.     succeeds, the lock is (effectively) relinquished, and should not be
  3688.     UnLock()ed or used.  If the open fails, the lock is still usable.
  3689.     The lock associated with the file internally is of the same access
  3690.     mode as the lock you gave up - shared is similar to MODE_OLDFILE,
  3691.     exclusive is similar to MODE_NEWFILE.
  3692.  
  3693.    INPUTS
  3694.     lock - Lock on object to be opened.
  3695.  
  3696.    RESULT
  3697.     fh   - Newly opened file handle or NULL for failure
  3698.  
  3699.    BUGS
  3700.     In the original V36 autodocs, this was shown (incorrectly) as
  3701.     taking a Mode parameter as well.  The prototypes and pragmas were
  3702.     also wrong.
  3703.  
  3704.    SEE ALSO
  3705.     Open(), Close(), Lock(), UnLock()
  3706.  
  3707. dos.library/Output                                         dos.library/Output
  3708.  
  3709.     NAME
  3710.     Output -- Identify the programs' initial output file handle
  3711.  
  3712.     SYNOPSIS
  3713.     file = Output()
  3714.     D0
  3715.  
  3716.     BPTR Output(void)
  3717.  
  3718.     FUNCTION
  3719.     Output() is used to identify the initial output stream allocated
  3720.     when the program was initiated.  Never close the filehandle returned
  3721.     by Output().
  3722.  
  3723.     RESULTS
  3724.     file - BCPL pointer to a file handle
  3725.  
  3726.     SEE ALSO
  3727.     Input()
  3728.  
  3729. dos.library/ParentDir                                   dos.library/ParentDir
  3730.  
  3731.     NAME
  3732.     ParentDir -- Obtain the parent of a directory or file
  3733.  
  3734.     SYNOPSIS
  3735.     newlock = ParentDir( lock )
  3736.     D0             D1
  3737.  
  3738.     BPTR ParentDir(BPTR)
  3739.  
  3740.     FUNCTION
  3741.     The argument 'lock' is associated with a given file or directory.
  3742.     ParentDir() returns 'newlock' which is associated the parent
  3743.     directory of 'lock'.
  3744.  
  3745.     Taking the ParentDir() of the root of the current filing system
  3746.     returns a NULL (0) lock.  Note this 0 lock represents the root of
  3747.     file system that you booted from (which is, in effect, the parent
  3748.     of all other file system roots.)
  3749.  
  3750.     INPUTS
  3751.     lock - BCPL pointer to a lock
  3752.  
  3753.     RESULTS
  3754.     newlock - BCPL pointer to a lock
  3755.  
  3756.     SEE ALSO
  3757.     Lock(), DupLock(), UnLock(), ParentOfFH(), DupLockFromFH()
  3758.  
  3759. dos.library/ParentOfFH                                 dos.library/ParentOfFH
  3760.  
  3761.    NAME
  3762.     ParentOfFH -- returns a lock on the parent directory of a file (V36)
  3763.  
  3764.    SYNOPSIS
  3765.     lock = ParentOfFH(fh)
  3766.     D0               D1
  3767.  
  3768.     BPTR ParentOfFH(BPTR)
  3769.  
  3770.    FUNCTION
  3771.     Returns a shared lock on the parent directory of the filehandle.
  3772.  
  3773.    INPUTS
  3774.     fh   - Filehandle you want the parent of.
  3775.  
  3776.    RESULT
  3777.     lock - Lock on parent directory of the filehandle or NULL for failure.
  3778.  
  3779.    SEE ALSO
  3780.     Parent(), Lock(), UnLock() DupLockFromFH()
  3781.  
  3782. dos.library/ParsePattern                             dos.library/ParsePattern
  3783.  
  3784.    NAME
  3785.     ParsePattern -- Create a tokenized string for MatchPattern() (V36)
  3786.  
  3787.    SYNOPSIS
  3788.     IsWild = ParsePattern(Source, Dest, DestLength)
  3789.     d0                      D1     D2      D3
  3790.  
  3791.     LONG ParsePattern(STRPTR, STRPTR, LONG)
  3792.  
  3793.    FUNCTION
  3794.     Tokenizes a pattern, for use by MatchPattern().  Also indicates if
  3795.     there are any wildcards in the pattern (i.e. whether it might match
  3796.     more than one item).  Note that Dest must be at least 2 times as
  3797.     large as Source plus bytes to be (almost) 100% certain of no
  3798.     buffer overflow.  This is because each input character can currently
  3799.     expand to 2 tokens (with one exception that can expand to 3, but
  3800.     only once per string).  Note: this implementation may change in
  3801.     the future, so you should handle error returns in all cases, but
  3802.     the size above should still be a reasonable upper bound for a buffer
  3803.     allocation.
  3804.  
  3805.     The patterns are fairly extensive, and approximate some of the ability
  3806.     of Unix/grep "regular expression" patterns.  Here are the available
  3807.     tokens:
  3808.  
  3809.     ?    Matches a single character.
  3810.     #    Matches the following expression 0 or more times.
  3811.     (ab|cd)    Matches any one of the items seperated by '|'.
  3812.     ~    Negates the following expression.  It matches all strings
  3813.         that do not match the expression (aka ~(foo) matches all
  3814.         strings that are not exactly "foo").
  3815.     [abc]    Character class: matches any of the characters in the class.
  3816.     [~bc]    Character class: matches any of the characters not in the
  3817.         class.
  3818.     a-z    Character range (only within character classes). 
  3819.     %    Matches 0 characters always (useful in "(foo|bar|%)").
  3820.     *    Synonym for "#?", not available by default in 2.0.  Available
  3821.         as an option that can be turned on.
  3822.  
  3823.     "Expression" in the above table means either a single character
  3824.     (ex: "#?"), or an alternation (ex: "#(ab|cd|ef)"), or a character
  3825.     class (ex: "#[a-zA-Z]").
  3826.  
  3827.    INPUTS
  3828.     source     - unparsed wildcard string to search for.
  3829.        dest       - output string, gets tokenized version of input.
  3830.     DestLength - length available in destination (should be at least as
  3831.              twice as large as source + 2 bytes).
  3832.  
  3833.    RESULT
  3834.     IsWild - 1 means there were wildcards in the pattern,
  3835.          0 means there were no wildcards in the pattern,
  3836.         -1 means there was a buffer overflow or other error
  3837.  
  3838.    BUGS
  3839.     In V37 this call didn't always set IoErr() to something useful on an
  3840.     error.  Fixed in V39.
  3841.  
  3842.    SEE ALSO
  3843.     ParsePatternNoCase(), MatchPattern(), MatchFirst(), MatchNext()
  3844.  
  3845. dos.library/ParsePatternNoCase                 dos.library/ParsePatternNoCase
  3846.  
  3847.    NAME
  3848.     ParsePatternNoCase -- Create a tokenized string for
  3849.                         MatchPatternNoCase() (V37)
  3850.  
  3851.    SYNOPSIS
  3852.     IsWild = ParsePatternNoCase(Source, Dest, DestLength)
  3853.     d0                            D1     D2      D3
  3854.  
  3855.     LONG ParsePatternNoCase(STRPTR, STRPTR, LONG)
  3856.  
  3857.    FUNCTION
  3858.     Tokenizes a pattern, for use by MatchPatternNoCase().  Also indicates
  3859.     if there are any wildcards in the pattern (i.e. whether it might match
  3860.     more than one item).  Note that Dest must be at least 2 times as
  3861.     large as Source plus 2 bytes.
  3862.  
  3863.     For a description of the wildcards, see ParsePattern().
  3864.  
  3865.    INPUTS
  3866.     source     - unparsed wildcard string to search for.
  3867.        dest       - output string, gets tokenized version of input.
  3868.     DestLength - length available in destination (should be at least as
  3869.              twice as large as source + 2 bytes).
  3870.  
  3871.    RESULT
  3872.     IsWild - 1 means there were wildcards in the pattern,
  3873.          0 means there were no wildcards in the pattern,
  3874.         -1 means there was a buffer overflow or other error
  3875.  
  3876.    BUGS
  3877.     In V37 this call didn't always set IoErr() to something useful on an
  3878.     error.  Fixed in V39.
  3879.     In V37, it didn't properly convert character-classes ([x-y]) to
  3880.     upper case.  Workaround: convert the input pattern to upper case
  3881.     using ToUpper() from utility.library before calling
  3882.     ParsePatternNoCase().  Fixed in V39 dos.
  3883.  
  3884.    SEE ALSO
  3885.     ParsePattern(), MatchPatternNoCase(), MatchFirst(), MatchNext(),
  3886.     utility.library/ToUpper()
  3887.  
  3888. dos.library/PathPart                                     dos.library/PathPart
  3889.  
  3890.    NAME
  3891.     PathPart -- Returns a pointer to the end of the next-to-last (V36)
  3892.             component of a path.
  3893.  
  3894.    SYNOPSIS
  3895.     fileptr = PathPart( path )
  3896.     D0             D1
  3897.  
  3898.     STRPTR PathPart( STRPTR )
  3899.  
  3900.    FUNCTION
  3901.     This function returns a pointer to the character after the next-to-last
  3902.     component of a path specification, which will normally be the directory
  3903.     name.  If there is only one component, it returns a pointer to the
  3904.     beginning of the string.  The only real difference between this and
  3905.     FilePart() is the handling of '/'.
  3906.  
  3907.    INPUTS
  3908.     path - pointer to an path string.  May be relative to the current
  3909.            directory or the current disk.
  3910.  
  3911.    RESULT
  3912.     fileptr - pointer to the end of the next-to-last component of the path.
  3913.  
  3914.    EXAMPLE
  3915.     PathPart("xxx:yyy/zzz/qqq") would return a pointer to the last '/'.
  3916.     PathPart("xxx:yyy") would return a pointer to the first 'y').
  3917.  
  3918.    SEE ALSO
  3919.     FilePart(), AddPart()
  3920.  
  3921. dos.library/PrintFault                                 dos.library/PrintFault
  3922.  
  3923.    NAME
  3924.     PrintFault -- Returns the text associated with a DOS error code (V36)
  3925.  
  3926.    SYNOPSIS
  3927.     success = PrintFault(code, header)
  3928.     D0                    D1     D2   
  3929.  
  3930.     BOOL PrintFault(LONG, STRPTR)
  3931.  
  3932.    FUNCTION
  3933.     This routine obtains the error message text for the given error code.
  3934.     This is similar to the Fault() function, except that the output is
  3935.     written to the default output channel with buffered output.
  3936.     The value returned by IoErr() is set to the code passed in.
  3937.  
  3938.    INPUTS
  3939.     code   - Error code
  3940.     header - header to output before error text
  3941.  
  3942.    RESULT
  3943.     success - Success/failure code.
  3944.  
  3945.    SEE ALSO
  3946.     IoErr(), Fault(), SetIoErr(), Output(), FPuts()
  3947.  
  3948. dos.library/PutStr                                         dos.library/PutStr
  3949.  
  3950.    NAME
  3951.     PutStr -- Writes a string the the default output (buffered) (V36)
  3952.  
  3953.    SYNOPSIS
  3954.     error = PutStr(str)
  3955.     D0             D1
  3956.  
  3957.     LONG PutStr(STRPTR)
  3958.  
  3959.    FUNCTION
  3960.     This routine writes an unformatted string to the default output.  No 
  3961.     newline is appended to the string and any error is returned.  This
  3962.     routine is buffered.
  3963.  
  3964.    INPUTS
  3965.     str   - Null-terminated string to be written to default output
  3966.  
  3967.    RESULT
  3968.     error - 0 for success, -1 for any error.  NOTE: this is opposite
  3969.         most Dos function returns!
  3970.  
  3971.    SEE ALSO
  3972.     FPuts(), FPutC(), FWrite(), WriteChars()
  3973.  
  3974. dos.library/Read                                             dos.library/Read
  3975.  
  3976.     NAME
  3977.     Read -- Read bytes of data from a file
  3978.  
  3979.     SYNOPSIS
  3980.     actualLength = Read( file, buffer, length )
  3981.     D0             D1    D2       D3
  3982.  
  3983.     LONG Read(BPTR, void *, LONG)
  3984.  
  3985.     FUNCTION
  3986.     Data can be copied using a combination of Read() and Write().
  3987.     Read() reads bytes of information from an opened file (represented
  3988.     here by the argument 'file') into the buffer given. The argument
  3989.     'length' is the length of the buffer given.
  3990.  
  3991.     The value returned is the length of the information actually read.
  3992.     So, when 'actualLength' is greater than zero, the value of
  3993.     'actualLength' is the the number of characters read. Usually Read
  3994.     will try to fill up your buffer before returning. A value of zero
  3995.     means that end-of-file has been reached. Errors are indicated by a
  3996.     value of -1.
  3997.  
  3998.     Note: this is an unbuffered routine (the request is passed directly
  3999.     to the filesystem.)  Buffered I/O is more efficient for small
  4000.     reads and writes; see FGetC().
  4001.  
  4002.     INPUTS
  4003.     file - BCPL pointer to a file handle
  4004.     buffer - pointer to buffer
  4005.     length - integer
  4006.  
  4007.     RESULTS
  4008.     actualLength - integer
  4009.  
  4010.     SEE ALSO
  4011.     Open(), Close(), Write(), Seek(), FGetC()
  4012.  
  4013. dos.library/ReadArgs                                     dos.library/ReadArgs
  4014.  
  4015.    NAME
  4016.     ReadArgs - Parse the command line input (V36)
  4017.  
  4018.    SYNOPSIS
  4019.     result = ReadArgs(template, array, rdargs)
  4020.     D0                   D1      D2      D3
  4021.  
  4022.     struct RDArgs * ReadArgs(STRPTR, LONG *, struct RDArgs *)
  4023.  
  4024.    FUNCTION
  4025.     Parses and argument string according to a template.  Normally gets
  4026.     the arguments by reading buffered IO from Input(), but also can be
  4027.     made to parse a string.  MUST be matched by a call to FreeArgs().
  4028.  
  4029.     ReadArgs() parses the commandline according to a template that is
  4030.     passed to it.  This specifies the different command-line options and
  4031.     their types.  A template consists of a list of options.  Options are
  4032.     named in "full" names where possible (for example, "Quick" instead of
  4033.     "Q").  Abbreviations can also be specified by using "abbrev=option"
  4034.     (for example, "Q=Quick").
  4035.  
  4036.     Options in the template are separated by commas.  To get the results
  4037.     of ReadArgs(), you examine the array of longwords you passed to it
  4038.     (one entry per option in the template).  This array should be cleared
  4039.     (or initialized to your default values) before passing to ReadArgs().
  4040.     Exactly what is put in a given entry by ReadArgs() depends on the type
  4041.     of option.  The default is a string (a sequence of non-whitespace
  4042.     characters, or delimited by quotes, which will be stripped by
  4043.     ReadArgs()), in which case the entry will be a pointer.
  4044.  
  4045.     Options can be followed by modifiers, which specify things such as
  4046.     the type of the option.  Modifiers are specified by following the
  4047.     option with a '/' and a single character modifier.  Multiple modifiers
  4048.     can be specified by using multiple '/'s.  Valid modifiers are:
  4049.  
  4050.     /S - Switch.  This is considered a boolean variable, and will be
  4051.          set if the option name appears in the command-line.  The entry
  4052.          is the boolean (0 for not set, non-zero for set).
  4053.  
  4054.     /K - Keyword.  This means that the option will not be filled unless
  4055.          the keyword appears.  For example if the template is "Name/K",
  4056.          then unless "Name=<string>" or "Name <string>" appears in the
  4057.          command line, Name will not be filled.
  4058.  
  4059.     /N - Number.  This parameter is considered a decimal number, and will
  4060.          be converted by ReadArgs.  If an invalid number is specified,
  4061.          an error will be returned.  The entry will be a pointer to the
  4062.          longword number (this is how you know if a number was specified).
  4063.  
  4064.     /T - Toggle.  This is similar to a switch, but when specified causes
  4065.          the boolean value to "toggle".  Similar to /S.
  4066.  
  4067.     /A - Required.  This keyword must be given a value during command-line
  4068.          processing, or an error is returned.
  4069.  
  4070.     /F - Rest of line.  If this is specified, the entire rest of the line
  4071.          is taken as the parameter for the option, even if other option
  4072.          keywords appear in it.
  4073.  
  4074.     /M - Multiple strings.  This means the argument will take any number
  4075.          of strings, returning them as an array of strings.  Any arguments
  4076.          not considered to be part of another option will be added to this
  4077.          option.  Only one /M should be specified in a template.  Example:
  4078.          for a template "Dir/M,All/S" the command-line "foo bar all qwe"
  4079.          will set the boolean "all", and return an array consisting of
  4080.          "foo", "bar", and "qwe".  The entry in the array will be a pointer
  4081.          to an array of string pointers, the last of which will be NULL.
  4082.  
  4083.          There is an interaction between /M parameters and /A parameters.
  4084.          If there are unfilled /A parameters after parsing, it will grab
  4085.          strings from the end of a previous /M parameter list to fill the
  4086.          /A's.  This is used for things like Copy ("From/A/M,To/A").
  4087.  
  4088.     ReadArgs() returns a struct RDArgs if it succeeds.  This serves as an
  4089.     "anchor" to allow FreeArgs() to free the associated memory.  You can
  4090.     also pass in a struct RDArgs to control the operation of ReadArgs()
  4091.     (normally you pass NULL for the parameter, and ReadArgs() allocates
  4092.     one for you).  This allows providing different sources for the
  4093.     arguments, providing your own string buffer space for temporary
  4094.     storage, and extended help text.  See <dos/rdargs.h> for more
  4095.     information on this.  Note: if you pass in a struct RDArgs, you must
  4096.     still call FreeArgs() to release storage that gets attached to it,
  4097.     but you are responsible for freeing the RDArgs yourself.
  4098.  
  4099.     If you pass in a RDArgs structure, you MUST reset (clear or set)
  4100.     RDA_Buffer for each new call to RDArgs.  The exact behavior if you
  4101.     don't do this varies from release to release and case to case; don't
  4102.     count on the behavior!
  4103.  
  4104.     See BUGS regarding passing in strings.
  4105.     
  4106.    INPUTS
  4107.     template - formatting string
  4108.     array    - array of longwords for results, 1 per template entry
  4109.     rdargs   - optional rdargs structure for options.  AllocDosObject
  4110.            should be used for allocating them if you pass one in.
  4111.  
  4112.    RESULT
  4113.     result   - a struct RDArgs or NULL for failure.
  4114.  
  4115.    BUGS
  4116.     In V36, there were a couple of minor bugs with certain argument
  4117.     combinations (/M/N returned strings, /T didn't work, and /K and
  4118.     /F interacted).  Also, a template with a /K before any non-switch
  4119.     parameter will require the argument name to be given in order for
  4120.     line to be accepted (i.e. "parm/K,xyzzy/A" would require
  4121.     "xyzzy=xxxxx" in order to work - "xxxxx" would not work).  If you
  4122.     need to avoid this for V36, put /K parameters after all non-switch
  4123.     parameters.  These problems should be fixed for V37.
  4124.  
  4125.     Currently (V37 and before) it requires any strings passed in to have
  4126.     newlines at the end of the string.  This may or may not be fixed in
  4127.     the future.
  4128.  
  4129.    SEE ALSO
  4130.     FindArg(), ReadItem(), FreeArgs(), AllocDosObject()
  4131.  
  4132. dos.library/ReadItem                                     dos.library/ReadItem
  4133.  
  4134.    NAME
  4135.     ReadItem - reads a single argument/name from command line (V36)
  4136.  
  4137.    SYNOPSIS
  4138.     value = ReadItem(buffer, maxchars, input)
  4139.     D0                D1        D2      D3
  4140.  
  4141.     LONG ReadItem(STRPTR, LONG, struct CSource *)
  4142.  
  4143.    FUNCTION
  4144.     Reads a "word" from either Input() (buffered), or via CSource, if it
  4145.     is non-NULL (see <dos/rdargs.h> for more information).  Handles
  4146.     quoting and some '*' substitutions (*e and *n) inside quotes (only).
  4147.     See dos/dos.h for a listing of values returned by ReadItem()
  4148.     (ITEM_XXXX).  A "word" is delimited by whitespace, quotes, '=', or
  4149.     an EOF.
  4150.  
  4151.     ReadItem always unreads the last thing read (UnGetC(fh,-1)) so the
  4152.     caller can find out what the terminator was.
  4153.  
  4154.    INPUTS
  4155.     buffer   - buffer to store word in.
  4156.     maxchars - size of the buffer
  4157.     input    - CSource input or NULL (uses FGetC(Input()))
  4158.  
  4159.    RESULT
  4160.     value - See <dos/dos.h> for return values.
  4161.  
  4162.    BUGS
  4163.     Doesn't actually unread the terminator.
  4164.  
  4165.    SEE ALSO
  4166.     ReadArgs(), FindArg(), UnGetC(), FGetC(), Input(), <dos/dos.h>,
  4167.     <dos/rdargs.h>, FreeArgs()
  4168.  
  4169. dos.library/ReadLink                                     dos.library/ReadLink
  4170.  
  4171.    NAME
  4172.     ReadLink -- Reads the path for a soft filesystem link (V36)
  4173.  
  4174.    SYNOPSIS
  4175.     success = ReadLink( port, lock, path, buffer, size)
  4176.     D0             D1    D2    D3     D4     D5
  4177.  
  4178.     BOOL ReadLink( struct MsgPort *, BPTR, STRPTR, STRPTR, ULONG)
  4179.  
  4180.    FUNCTION
  4181.     ReadLink() takes a lock/name pair (usually from a failed attempt
  4182.     to use them to access an object with packets), and asks the
  4183.     filesystem to find the softlink and fill buffer with the modified
  4184.     path string.  You then start the resolution process again by
  4185.     calling GetDeviceProc() with the new string from ReadLink().
  4186.  
  4187.     Soft-links are resolved at access time by a combination of the
  4188.     filesystem (by returning ERROR_IS_SOFT_LINK to dos), and by
  4189.     Dos (using ReadLink() to resolve any links that are hit).
  4190.  
  4191.    INPUTS
  4192.     port - msgport of the filesystem
  4193.     lock - lock this path is relative to on the filesystem
  4194.     path - path that caused the ERROR_IS_SOFT_LINK
  4195.     buffer - pointer to buffer for new path from handler.
  4196.     size - size of buffer.
  4197.  
  4198.    RESULT
  4199.     Success - boolean
  4200.  
  4201.    BUGS
  4202.     In V36, soft-links didn't work in the ROM filesystem.  This was
  4203.     fixed for V37.
  4204.  
  4205.    SEE ALSO
  4206.     MakeLink(), Open(), Lock(), GetDeviceProc()
  4207.  
  4208. dos.library/Relabel                                       dos.library/Relabel
  4209.  
  4210.    NAME
  4211.     Relabel -- Change the volume name of a volume (V36)
  4212.  
  4213.    SYNOPSIS
  4214.     success = Relabel(volumename,name)
  4215.     D0                    D1      D2
  4216.  
  4217.     BOOL Relabel(STRPTR,STRPTR)
  4218.  
  4219.    FUNCTION
  4220.     Changes the volumename of a volume, if supported by the filesystem.
  4221.  
  4222.    INPUTS
  4223.     volumename - Full name of device to rename (with ':')
  4224.     newname    - New name to apply to device (without ':')
  4225.  
  4226.    RESULT
  4227.     success    - Success/failure indicator
  4228.  
  4229.    SEE ALSO
  4230.  
  4231. dos.library/RemAssignList                           dos.library/RemAssignList
  4232.  
  4233.    NAME
  4234.     RemAssignList -- Remove an entry from a multi-dir assign (V36)
  4235.  
  4236.    SYNOPSIS
  4237.     success = RemAssignList(name,lock)
  4238.     D0                       D1   D2
  4239.  
  4240.     BOOL RemAssignList(STRPTR,BPTR)
  4241.  
  4242.    FUNCTION
  4243.     Removes an entry from a multi-directory assign.  The entry removed is
  4244.     the first one for which SameLock with 'lock' returns that they are on
  4245.     the same object.  The lock for the entry in the list is unlocked (not
  4246.     the entry passed in).
  4247.  
  4248.    INPUTS
  4249.     name - Name of device to remove lock from (without trailing ':')
  4250.     lock - Lock associated with the object to remove from the list
  4251.  
  4252.    RESULT
  4253.     success - Success/failure indicator.
  4254.  
  4255.    BUGS
  4256.     In V36 through V39.23 dos, it would fail to remove the first lock
  4257.     in the assign.  Fixed in V39.24 dos (after the V39.106 kickstart).
  4258.  
  4259.    SEE ALSO
  4260.     Lock(), AssignLock(), AssignPath(), AssignLate(), DupLock(),
  4261.     AssignAdd(), UnLock()
  4262.  
  4263. dos.library/RemDosEntry                               dos.library/RemDosEntry
  4264.  
  4265.    NAME
  4266.     RemDosEntry -- Removes a Dos List entry from it's list (V36)
  4267.  
  4268.    SYNOPSIS
  4269.     success = RemDosEntry(dlist)
  4270.     D0                     D1
  4271.  
  4272.     BOOL RemDosEntry(struct DosList *)
  4273.  
  4274.    FUNCTION
  4275.     This removes an entry from the Dos Device list.  The memory associated
  4276.     with the entry is NOT freed.  NOTE: you must have locked the Dos List
  4277.     with the appropriate flags before calling this routine.  Handler
  4278.     writers should see the AddDosEntry() caveats about locking and use
  4279.     a similar workaround to avoid deadlocks.
  4280.  
  4281.    INPUTS
  4282.     dlist   - Device list entry to be removed.
  4283.  
  4284.    RESULT
  4285.     success - Success/failure indicator
  4286.  
  4287.    SEE ALSO
  4288.     AddDosEntry(), FindDosEntry(), NextDosEntry(), LockDosList(),
  4289.     MakeDosEntry(), FreeDosEntry()
  4290.  
  4291. dos.library/RemSegment                                 dos.library/RemSegment
  4292.  
  4293.    NAME
  4294.     RemSegment - Removes a resident segment from the resident list (V36)
  4295.  
  4296.    SYNOPSIS
  4297.     success = RemSegment(segment)
  4298.     D0                D1
  4299.  
  4300.     BOOL RemSegment(struct Segment *)
  4301.  
  4302.    FUNCTION
  4303.     Removes a resident segment from the Dos resident segment list,
  4304.     unloads it, and does any other cleanup required.  Will only succeed
  4305.     if the seg_UC (usecount) is 0.
  4306.  
  4307.    INPUTS
  4308.     segment - the segment to be removed
  4309.  
  4310.    RESULT
  4311.     success - success or failure.
  4312.  
  4313.    SEE ALSO
  4314.     FindSegment(), AddSegment()
  4315.  
  4316. dos.library/Rename                                         dos.library/Rename
  4317.  
  4318.     NAME
  4319.     Rename -- Rename a directory or file
  4320.  
  4321.     SYNOPSIS
  4322.     success = Rename( oldName, newName )
  4323.     D0          D1       D2
  4324.  
  4325.     BOOL Rename(STRPTR, STRPTR)
  4326.  
  4327.     FUNCTION
  4328.     Rename() attempts to rename the file or directory specified as
  4329.     'oldName' with the name 'newName'. If the file or directory
  4330.     'newName' exists, Rename() fails and returns an error. Both
  4331.     'oldName' and the 'newName' can contain a directory specification.
  4332.     In this case, the file will be moved from one directory to another.
  4333.  
  4334.     Note: it is impossible to Rename() a file from one volume to
  4335.     another.
  4336.  
  4337.     INPUTS
  4338.     oldName - pointer to a null-terminated string
  4339.     newName - pointer to a null-terminated string
  4340.  
  4341.     RESULTS
  4342.     success - boolean
  4343.  
  4344.     SEE ALSO
  4345.     Relabel()
  4346.  
  4347. dos.library/ReplyPkt                                     dos.library/ReplyPkt
  4348.  
  4349.    NAME
  4350.     ReplyPkt -- replies a packet to the person who sent it to you (V36)
  4351.  
  4352.    SYNOPSIS
  4353.     ReplyPkt(packet, result1, result2)
  4354.            D1      D2       D3
  4355.  
  4356.     void ReplyPkt(struct DosPacket *, LONG, LONG)
  4357.  
  4358.    FUNCTION
  4359.     This returns a packet to the process which sent it to you.  In
  4360.     addition, puts your pr_MsgPort address in dp_Port, so using ReplyPkt()
  4361.     again will send the message to you.  (This is used in "ping-ponging"
  4362.     packets between two processes).  It uses result 1 & 2 to set the
  4363.     dp_Res1 and dp_Res2 fields of the packet.
  4364.  
  4365.    INPUTS
  4366.     packet  - packet to reply, assumed to set up correctly.
  4367.     result1 - first result
  4368.     result2 - secondary result
  4369.  
  4370.    SEE ALSO
  4371.     DoPkt(), SendPkt(), WaitPkt(), IoErr()
  4372.  
  4373. dos.library/RunCommand                                 dos.library/RunCommand
  4374.  
  4375.    NAME
  4376.     RunCommand -- Runs a program using the current process (V36)
  4377.  
  4378.    SYNOPSIS
  4379.     rc = RunCommand(seglist, stacksize, argptr, argsize)
  4380.     D0                D1         D2       D3      D4
  4381.  
  4382.     LONG RunCommand(BPTR, ULONG, STRPTR, ULONG)
  4383.  
  4384.    FUNCTION
  4385.     Runs a command on your process/cli.  Seglist may be any language,
  4386.     including BCPL programs.  Stacksize is in bytes.  argptr is a null-
  4387.     terminated string, argsize is its length.  Returns the returncode the
  4388.     program exited with in d0. Returns -1 if the stack couldn't be
  4389.     allocated.
  4390.  
  4391.     NOTE: the argument string MUST be terminated with a newline to work
  4392.     properly with ReadArgs() and other argument parsers.
  4393.  
  4394.     RunCommand also takes care of setting up the current input filehandle
  4395.     in such a way that ReadArgs() can be used in the program, and restores
  4396.     the state of the buffering before returning.  It also sets the value
  4397.     returned by GetArgStr(), and restores it before returning.  NOTE:
  4398.     the setting of the argument string in the filehandle was added in V37.
  4399.  
  4400.     It's usually appropriate to set the command name (via
  4401.     SetProgramName()) before calling RunCommand().  RunCommand() sets
  4402.     the value returned by GetArgStr() while the command is running.
  4403.  
  4404.    INPUTS
  4405.     seglist   - Seglist of command to run.
  4406.     stacksize - Number of bytes to allocate for stack space
  4407.     argptr    - Pointer to argument command string.
  4408.     argsize   - Number of bytes in argument command.
  4409.  
  4410.    RESULT
  4411.     rc        - Return code from executed command. -1 indicates failure 
  4412.  
  4413.    SEE ALSO
  4414.     CreateNewProc(), SystemTagList(), Execute(), GetArgStr(),
  4415.     SetProgramName(), ReadArgs()
  4416.  
  4417. dos.library/SameDevice                                 dos.library/SameDevice
  4418.  
  4419.    NAME
  4420.     SameDevice -- Are two locks are on partitions of the device? (V37)
  4421.  
  4422.    SYNOPSIS
  4423.     same = SameDevice(lock1, lock2)
  4424.     D0           D1     D2
  4425.  
  4426.     BOOL SameDevice( BPTR, BPTR )
  4427.  
  4428.    FUNCTION
  4429.     SameDevice() returns whether two locks refer to partitions that
  4430.     are on the same physical device (if it can figure it out).  This
  4431.     may be useful in writing copy routines to take advantage of
  4432.     asynchronous multi-device copies.
  4433.  
  4434.     Entry existed in V36 and always returned 0.
  4435.  
  4436.    INPUTS
  4437.     lock1,lock2 - locks
  4438.  
  4439.    RESULT
  4440.     same - whether they're on the same device as far as Dos can determine.
  4441.  
  4442. dos.library/SameLock                                     dos.library/SameLock
  4443.  
  4444.    NAME
  4445.     SameLock -- returns whether two locks are on the same object (V36)
  4446.  
  4447.    SYNOPSIS
  4448.     value = SameLock(lock1, lock2)
  4449.     D0          D1     D2
  4450.  
  4451.     LONG SameLock(BPTR, BPTR)
  4452.  
  4453.    FUNCTION
  4454.     Compares two locks.  Returns LOCK_SAME if they are on the same object,
  4455.     LOCK_SAME_VOLUME if on different objects on the same volume, and
  4456.     LOCK_DIFFERENT if they are on different volumes.  Always compare
  4457.     for equality or non-equality with the results, in case new return
  4458.     values are added.
  4459.  
  4460.    INPUTS
  4461.     lock1 - 1st lock for comparison
  4462.     lock2 - 2nd lock for comparison
  4463.  
  4464.    RESULT
  4465.     value -    LOCK_SAME, LOCK_SAME_VOLUME, or LOCK_DIFFERENT
  4466.  
  4467.    BUGS
  4468.     Should do more extensive checks for NULL against a real lock, checking
  4469.     to see if the real lock is a lock on the root of the boot volume.
  4470.  
  4471.     In V36, it would return LOCK_SAME_VOLUME for different volumes on the
  4472.     same handler.  Also, LOCK_SAME_VOLUME was LOCK_SAME_HANDLER (now
  4473.     an obsolete define, see <dos/dos.h>).
  4474.  
  4475.    SEE ALSO
  4476.     <dos/dos.h>
  4477.  
  4478. dos.library/Seek                                             dos.library/Seek
  4479.  
  4480.     NAME
  4481.     Seek -- Set the current position for reading and writing
  4482.  
  4483.     SYNOPSIS
  4484.     oldPosition = Seek( file, position, mode )
  4485.     D0            D1      D2        D3
  4486.  
  4487.     LONG Seek(BPTR, LONG, LONG)
  4488.  
  4489.     FUNCTION
  4490.     Seek() sets the read/write cursor for the file 'file' to the
  4491.     position 'position'. This position is used by both Read() and
  4492.     Write() as a place to start reading or writing. The result is the
  4493.     current absolute position in the file, or -1 if an error occurs, in
  4494.     which case IoErr() can be used to find more information. 'mode' can
  4495.     be OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END. It is used to
  4496.     specify the relative start position. For example, 20 from current
  4497.     is a position 20 bytes forward from current, -20 is 20 bytes back
  4498.     from current.
  4499.  
  4500.     So that to find out where you are, seek zero from current. The end
  4501.     of the file is a Seek() positioned by zero from end. You cannot
  4502.     Seek() beyond the end of a file.
  4503.  
  4504.     INPUTS
  4505.     file - BCPL pointer to a file handle
  4506.     position - integer
  4507.     mode - integer
  4508.  
  4509.     RESULTS
  4510.     oldPosition - integer
  4511.  
  4512.     BUGS
  4513.     The V36 and V37 ROM filesystem (and V36/V37 l:fastfilesystem)
  4514.     returns the current position instead of -1 on an error.  It sets
  4515.     IoErr() to 0 on success, and an error code on an error.  This bug
  4516.     was fixed in the V39 filesystem.
  4517.  
  4518.     SEE ALSO
  4519.     Read(), Write(), SetFileSize()
  4520.  
  4521. dos.library/SelectInput                               dos.library/SelectInput
  4522.  
  4523.    NAME
  4524.     SelectInput -- Select a filehandle as the default input channel (V36)
  4525.  
  4526.    SYNOPSIS
  4527.     old_fh = SelectInput(fh)
  4528.     D0                   D1
  4529.  
  4530.     BPTR SelectInput(BPTR)
  4531.  
  4532.    FUNCTION
  4533.     Set the current input as the default input for the process.
  4534.     This changes the value returned by Input().  old_fh should
  4535.     be closed or saved as needed.
  4536.  
  4537.    INPUTS
  4538.     fh     - Newly default input handle
  4539.  
  4540.    RESULT
  4541.     old_fh - Previous default input filehandle
  4542.  
  4543.    SEE ALSO
  4544.     Input(), SelectOutput(), Output()
  4545.  
  4546. dos.library/SelectOutput                             dos.library/SelectOutput
  4547.  
  4548.    NAME
  4549.     SelectOutput -- Select a filehandle as the default output channel (V36)
  4550.  
  4551.    SYNOPSIS
  4552.     old_fh = SelectOutput(fh)
  4553.     D0                    D1
  4554.  
  4555.     BPTR SelectOutput(BPTR)
  4556.  
  4557.    FUNCTION
  4558.     Set the current output as the default output for the process.
  4559.     This changes the value returned by Output().  old_fh should
  4560.     be closed or saved as needed.
  4561.  
  4562.    INPUTS
  4563.     fh     - Newly desired output handle
  4564.  
  4565.    RESULT
  4566.     old_fh - Previous current output
  4567.  
  4568.    SEE ALSO
  4569.     Output(), SelectInput(), Input()
  4570.  
  4571. dos.library/SendPkt                                       dos.library/SendPkt
  4572.  
  4573.    NAME
  4574.     SendPkt -- Sends a packet to a handler (V36)
  4575.  
  4576.    SYNOPSIS
  4577.     SendPkt(packet, port, replyport)
  4578.          D1     D2    D3
  4579.  
  4580.     void SendPkt(struct DosPacket *,struct MsgPort *,struct MsgPort *)
  4581.  
  4582.    FUNCTION
  4583.     Sends a packet to a handler and does not wait.  All fields in the
  4584.     packet must be initialized before calling this routine.  The packet
  4585.     will be returned to replyport.  If you wish to use this with
  4586.     WaitPkt(), use the address of your pr_MsgPort for replyport.
  4587.  
  4588.    INPUTS
  4589.     packet - packet to send, must be initialized and have a message.
  4590.     port   - pr_MsgPort of handler process to send to.
  4591.     replyport - MsgPort for the packet to come back to.
  4592.  
  4593.    NOTES
  4594.     Callable from a task.
  4595.  
  4596.    SEE ALSO
  4597.     DoPkt(), WaitPkt(), AllocDosObject(), FreeDosObject(), AbortPkt()
  4598.  
  4599. dos.library/SetArgStr                                   dos.library/SetArgStr
  4600.  
  4601.    NAME
  4602.     SetArgStr -- Sets the arguments for the current process (V36)
  4603.  
  4604.    SYNOPSIS
  4605.     oldptr = SetArgStr(ptr)
  4606.     D0           D1
  4607.  
  4608.     STRPTR SetArgStr(STRPTR)
  4609.  
  4610.    FUNCTION
  4611.     Sets the arguments for the current program.  The ptr MUST be reset
  4612.     to it's original value before process exit.
  4613.  
  4614.    INPUTS
  4615.     ptr - pointer to new argument string.
  4616.  
  4617.    RESULT
  4618.     oldptr - the previous argument string
  4619.  
  4620.    SEE ALSO
  4621.     GetArgStr(), RunCommand()
  4622.  
  4623. dos.library/SetComment                                 dos.library/SetComment
  4624.  
  4625.     NAME
  4626.     SetComment -- Change a files' comment string
  4627.  
  4628.     SYNOPSIS
  4629.     success = SetComment( name, comment )
  4630.     D0              D1    D2
  4631.  
  4632.     BOOL SetComment(STRPTR, STRPTR)
  4633.  
  4634.     FUNCTION
  4635.     SetComment() sets a comment on a file or directory. The comment is
  4636.     a pointer to a null-terminated string of up to 80 characters in the
  4637.     current ROM filesystem (and RAM:).  Note that not all filesystems
  4638.     will support comments (for example, NFS usually will not), or the
  4639.     size of comment supported may vary.
  4640.  
  4641.     INPUTS
  4642.     name    - pointer to a null-terminated string
  4643.     comment - pointer to a null-terminated string
  4644.  
  4645.     RESULTS
  4646.     success - boolean
  4647.  
  4648.     SEE ALSO
  4649.     Examine(), ExNext(), SetProtection()
  4650.  
  4651. dos.library/SetConsoleTask                         dos.library/SetConsoleTask
  4652.  
  4653.    NAME
  4654.     SetConsoleTask -- Sets the default console for the process (V36)
  4655.  
  4656.    SYNOPSIS
  4657.     oldport = SetConsoleTask(port)
  4658.     D0              D1
  4659.  
  4660.     struct MsgPort *SetConsoleTask(struct MsgPort *)
  4661.  
  4662.    FUNCTION
  4663.     Sets the default console task's port (pr_ConsoleTask) for the
  4664.     current process.
  4665.  
  4666.    INPUTS
  4667.     port - The pr_MsgPort of the default console handler for the process
  4668.  
  4669.    RESULT
  4670.     oldport - The previous ConsoleTask value.
  4671.  
  4672.    SEE ALSO
  4673.     GetConsoleTask(), Open()
  4674.  
  4675. dos.library/SetCurrentDirName                   dos.library/SetCurrentDirName
  4676.  
  4677.    NAME
  4678.     SetCurrentDirName -- Sets the directory name for the process (V36)
  4679.  
  4680.    SYNOPSIS
  4681.     success = SetCurrentDirName(name)
  4682.     D0                        D1
  4683.  
  4684.     BOOL SetCurrentDirName(STRPTR)
  4685.  
  4686.    FUNCTION
  4687.     Sets the name for the current dir in the cli structure.  If the name
  4688.     is too long to fit, a failure is returned, and the old value is left
  4689.     intact.  It is advised that you inform the user of this condition.
  4690.     This routine is safe to call even if there is no CLI structure.
  4691.  
  4692.    INPUTS
  4693.     name    - Name of directory to be set.
  4694.  
  4695.    RESULT
  4696.     success - Success/failure indicator
  4697.  
  4698.    BUGS
  4699.     This clips to a fixed (1.3 compatible) size.
  4700.  
  4701.    SEE ALSO
  4702.     GetCurrentDirName()
  4703.  
  4704. dos.library/SetFileDate                               dos.library/SetFileDate
  4705.  
  4706.    NAME
  4707.     SetFileDate -- Sets the modification date for a file or dir (V36)
  4708.  
  4709.    SYNOPSIS
  4710.     success = SetFileDate(name, date)
  4711.     D0                     D1    D2
  4712.  
  4713.     BOOL SetFileDate(STRPTR, struct DateStamp *)
  4714.  
  4715.    FUNCTION
  4716.     Sets the file date for a file or directory.  Note that for the Old
  4717.     File System and the Fast File System, the date of the root directory
  4718.     cannot be set.  Other filesystems may not support setting the date
  4719.     for all files/directories.
  4720.  
  4721.    INPUTS
  4722.     name - Name of object
  4723.     date - New modification date
  4724.  
  4725.    RESULT
  4726.     success - Success/failure indication
  4727.  
  4728.    SEE ALSO
  4729.     DateStamp(), Examine(), ExNext(), ExAll()
  4730.  
  4731. dos.library/SetFileSize                               dos.library/SetFileSize
  4732.  
  4733.    NAME
  4734.     SetFileSize -- Sets the size of a file (V36)
  4735.  
  4736.    SYNOPSIS
  4737.     newsize = SetFileSize(fh, offset, mode)
  4738.     D0                    D1    D2     D3
  4739.  
  4740.     LONG SetFileSize(BPTR, LONG, LONG)
  4741.  
  4742.    FUNCTION
  4743.     Changes the file size, truncating or extending as needed.  Not all
  4744.     handlers may support this; be careful and check the return code.  If
  4745.     the file is extended, no values should be assumed for the new bytes.
  4746.     If the new position would be before the filehandle's current position
  4747.     in the file, the filehandle will end with a position at the
  4748.     end-of-file.  If there are other filehandles open onto the file, the
  4749.     new size will not leave any filehandle pointing past the end-of-file.
  4750.     You can check for this by looking at the new size (which would be
  4751.     different than what you requested).
  4752.  
  4753.     The seek position should not be changed unless the file is made
  4754.     smaller than the current seek position.  However, see BUGS.
  4755.  
  4756.     Do NOT count on any specific values to be in any extended area.
  4757.  
  4758.    INPUTS
  4759.     fh     - File to be truncated/extended.
  4760.     offset - Offset from position determined by mode.
  4761.     mode   - One of OFFSET_BEGINNING, OFFSET_CURRENT, or OFFSET_END.
  4762.  
  4763.    RESULT
  4764.     newsize - position of new end-of-file or -1 for error.
  4765.  
  4766.    BUGS
  4767.     The RAM: filesystem and the normal Amiga filesystem act differently
  4768.     in where the file position is left after SetFileSize().  RAM: leaves
  4769.     you at the new end of the file (incorrectly), while the Amiga ROM
  4770.     filesystem leaves the seek position alone, unless the new position
  4771.     is less than the current position, in which case you're left at the
  4772.     new EOF.
  4773.  
  4774.     The best workaround is to not make any assumptions about the seek
  4775.     position after SetFileSize().    
  4776.  
  4777.    SEE ALSO
  4778.     Seek()
  4779.  
  4780. dos.library/SetFileSysTask                         dos.library/SetFileSysTask
  4781.  
  4782.    NAME
  4783.     SetFileSysTask -- Sets the default filesystem for the process (V36)
  4784.  
  4785.    SYNOPSIS
  4786.     oldport = SetFileSysTask(port)
  4787.     D0              D1
  4788.  
  4789.     struct MsgPort *SetFileSysTask(struct MsgPort *)
  4790.  
  4791.    FUNCTION
  4792.     Sets the default filesystem task's port (pr_FileSystemTask) for the
  4793.     current process.
  4794.  
  4795.    INPUTS
  4796.     port - The pr_MsgPort of the default filesystem for the process
  4797.  
  4798.    RESULT
  4799.     oldport - The previous FileSysTask value
  4800.  
  4801.    SEE ALSO
  4802.     GetFileSysTask(), Open()
  4803.  
  4804. dos.library/SetIoErr                                     dos.library/SetIoErr
  4805.  
  4806.    NAME
  4807.     SetIoErr -- Sets the value returned by IoErr() (V36)
  4808.  
  4809.    SYNOPSIS
  4810.     oldcode = SetIoErr(code)
  4811.     D0            D1
  4812.  
  4813.     LONG SetIoErr(LONG);
  4814.  
  4815.    FUNCTION
  4816.     This routine sets up the secondary result (pr_Result2) return code 
  4817.     (returned by the IoErr() function).
  4818.  
  4819.    INPUTS
  4820.     code - Code to be returned by a call to IoErr.
  4821.  
  4822.    RESULT
  4823.     oldcode - The previous error code.
  4824.  
  4825.    SEE ALSO
  4826.     IoErr(), Fault(), PrintFault()
  4827.  
  4828. dos.library/SetMode                                       dos.library/SetMode
  4829.  
  4830.    NAME
  4831.     SetMode - Set the current behavior of a handler (V36)
  4832.  
  4833.    SYNOPSIS
  4834.     success = SetMode(fh, mode)
  4835.     D0                D1  D2
  4836.  
  4837.     BOOL SetMode(BPTR, LONG)
  4838.  
  4839.    FUNCTION
  4840.     SetMode() sends an ACTION_SCREEN_MODE packet to the handler in
  4841.     question, normally for changing a CON: handler to raw mode or
  4842.     vice-versa.  For CON:, use 1 to go to RAW: mode, 0 for CON: mode.
  4843.  
  4844.    INPUTS
  4845.     fh   - filehandle
  4846.     mode - The new mode you want
  4847.  
  4848.    RESULT
  4849.     success - Boolean
  4850.  
  4851.    SEE ALSO
  4852.  
  4853. dos.library/SetOwner                                     dos.library/SetOwner
  4854.  
  4855.     NAME
  4856.     SetOwner -- Set owner information for a file or directory (V39)
  4857.  
  4858.     SYNOPSIS
  4859.     success = SetOwner( name, owner_info )
  4860.     D0             D1       D2
  4861.  
  4862.     BOOL SetOwner (STRPTR, LONG)
  4863.  
  4864.     FUNCTION
  4865.     SetOwner() sets the owner information for the file or directory.
  4866.     This value is a 32-bit value that is normally split into 16 bits
  4867.     of owner user id (bits 31-16), and 16 bits of owner group id (bits
  4868.     15-0).  However, other than returning them as shown by Examine()/
  4869.     ExNext()/ExAll(), the filesystem take no interest in the values.
  4870.     These are primarily for use by networking software (clients and
  4871.     hosts), in conjunction with the FIBF_OTR_xxx and FIBF_GRP_xxx
  4872.     protection bits.
  4873.  
  4874.     This entrypoint did not exist in V36, so you must open at least V37
  4875.     dos.library to use it.  V37 dos.library will return FALSE to this
  4876.     call.
  4877.  
  4878.     INPUTS
  4879.     name       - pointer to a null-terminated string
  4880.     owner_info - owner uid (31:16) and group id (15:0)
  4881.  
  4882.     RESULTS
  4883.     success - boolean
  4884.  
  4885.     SEE ALSO
  4886.     SetProtect(), Examine(), ExNext(), ExAll(), <dos/dos.h>
  4887.  
  4888. dos.library/SetProgramDir                           dos.library/SetProgramDir
  4889.  
  4890.    NAME
  4891.     SetProgramDir -- Sets the directory returned by GetProgramDir (V36)
  4892.  
  4893.    SYNOPSIS
  4894.     oldlock = SetProgramDir(lock)
  4895.     D0                 D1
  4896.  
  4897.     BPTR SetProgramDir(BPTR)
  4898.  
  4899.    FUNCTION
  4900.     Sets a shared lock on the directory the program was loaded from.
  4901.     This can be used for a program to find data files, etc, that are
  4902.     stored with the program, or to find the program file itself.  NULL
  4903.     is a valid input.  This can be accessed via GetProgramDir() or
  4904.     by using paths relative to PROGDIR:.
  4905.  
  4906.    INPUTS
  4907.     lock - A lock on the directory the current program was loaded from
  4908.  
  4909.    RESULT
  4910.     oldlock - The previous ProgramDir.
  4911.  
  4912.    SEE ALSO
  4913.     GetProgramDir(), Open()
  4914.  
  4915. dos.library/SetProgramName                         dos.library/SetProgramName
  4916.  
  4917.    NAME
  4918.     SetProgramName -- Sets the name of the program being run (V36)
  4919.  
  4920.    SYNOPSIS
  4921.     success = SetProgramName(name)
  4922.     D0                        D1
  4923.  
  4924.     BOOL SetProgramName(STRPTR)
  4925.  
  4926.    FUNCTION
  4927.     Sets the name for the program in the cli structure.  If the name is 
  4928.     too long to fit, a failure is returned, and the old value is left
  4929.     intact.  It is advised that you inform the user if possible of this
  4930.     condition, and/or set the program name to an empty string.
  4931.     This routine is safe to call even if there is no CLI structure.
  4932.  
  4933.    INPUTS
  4934.     name    - Name of program to use.
  4935.  
  4936.    RESULT
  4937.     success - Success/failure indicator.
  4938.  
  4939.    BUGS
  4940.     This clips to a fixed (1.3 compatible) size.
  4941.  
  4942.    SEE ALSO
  4943.     GetProgramName()
  4944.  
  4945. dos.library/SetPrompt                                   dos.library/SetPrompt
  4946.  
  4947.    NAME
  4948.     SetPrompt -- Sets the CLI/shell prompt for the current process (V36)
  4949.  
  4950.    SYNOPSIS
  4951.     success = SetPrompt(name)
  4952.     D0                D1
  4953.  
  4954.     BOOL SetPrompt(STRPTR)
  4955.  
  4956.    FUNCTION
  4957.     Sets the text for the prompt in the cli structure.  If the prompt is 
  4958.     too long to fit, a failure is returned, and the old value is left
  4959.     intact.  It is advised that you inform the user of this condition.
  4960.     This routine is safe to call even if there is no CLI structure.
  4961.  
  4962.    INPUTS
  4963.     name    - Name of prompt to be set.
  4964.  
  4965.    RESULT
  4966.     success - Success/failure indicator.
  4967.  
  4968.    BUGS
  4969.     This clips to a fixed (1.3 compatible) size.
  4970.  
  4971.    SEE ALSO
  4972.     GetPrompt()
  4973.  
  4974. dos.library/SetProtection                           dos.library/SetProtection
  4975.  
  4976.     NAME
  4977.     SetProtection -- Set protection for a file or directory
  4978.  
  4979.     SYNOPSIS
  4980.     success = SetProtection( name, mask )
  4981.     D0             D1    D2
  4982.  
  4983.     BOOL SetProtection (STRPTR, LONG)
  4984.  
  4985.     FUNCTION
  4986.     SetProtection() sets the protection attributes on a file or
  4987.     directory.  See <dos/dos.h> for a listing of protection bits.
  4988.  
  4989.     Before V36, the ROM filesystem didn't respect the Read and Write
  4990.     bits.  In V36 or later and in the FFS, the Read and Write
  4991.     bits are respected.
  4992.  
  4993.     The archive bit should be cleared by the filesystem whenever the file
  4994.     is changed.  Backup utilities will generally set the bit after
  4995.     backing up each file.
  4996.  
  4997.     The V36 Shell looks at the execute bit, and will refuse to execute
  4998.     a file if it is set.
  4999.  
  5000.     Other bits will be defined in the <dos/dos.h> include files.  Rather
  5001.     than referring to bits by number you should use the definitions in
  5002.     <dos/dos.h>.
  5003.  
  5004.     INPUTS
  5005.     name - pointer to a null-terminated string
  5006.     mask - the protection mask required
  5007.  
  5008.     RESULTS
  5009.     success - boolean
  5010.  
  5011.     SEE ALSO
  5012.     SetComment(), Examine(), ExNext(), <dos/dos.h>
  5013.  
  5014. dos.library/SetVar                                         dos.library/SetVar
  5015.  
  5016.    NAME
  5017.     SetVar -- Sets a local or environment variable (V36)
  5018.  
  5019.    SYNOPSIS
  5020.     success = SetVar( name, buffer, size, flags ) 
  5021.     D0               D1     D2     D3    D4
  5022.  
  5023.     BOOL SetVar(STRPTR, STRPTR, LONG, ULONG ) 
  5024.  
  5025.    FUNCTION
  5026.     Sets a local or environment variable.  It is advised to only use
  5027.     ASCII strings inside variables, but not required.
  5028.  
  5029.    INPUTS
  5030.     name   - pointer to an variable name.  Note variable names follow
  5031.          filesystem syntax and semantics.
  5032.     buffer - a user allocated area which contains a string that is the
  5033.          value to be associated with this variable.
  5034.     size   - length of the buffer region in bytes.  -1 means buffer
  5035.          contains a null-terminated string.
  5036.     flags  - combination of type of var to set (low 8 bits), and
  5037.          flags to control the behavior of this routine.  Currently
  5038.          defined flags include:
  5039.  
  5040.         GVF_LOCAL_ONLY - set a local (to your process) variable.
  5041.         GVF_GLOBAL_ONLY - set a global environment variable.
  5042.  
  5043.         The default is to set a local environment variable.
  5044.  
  5045.    RESULT
  5046.     success - If non-zero, the variable was sucessfully set, FALSE
  5047.            indicates failure.
  5048.  
  5049.    BUGS
  5050.     LV_VAR is the only type that can be global
  5051.  
  5052.    SEE ALSO
  5053.     GetVar(), DeleteVar(), FindVar(), <dos/var.h>
  5054.  
  5055. dos.library/SetVBuf                                       dos.library/SetVBuf
  5056.  
  5057.    NAME
  5058.     SetVBuf -- set buffering modes and size (V39)
  5059.  
  5060.    SYNOPSIS
  5061.     error = SetVBuf(fh, buff, type, size)
  5062.     D0        D1   D2    D3    D4
  5063.  
  5064.     LONG SetVBuf(BPTR, STRPTR, LONG, LONG)
  5065.  
  5066.    FUNCTION
  5067.     Changes the buffering modes and buffer size for a filehandle.
  5068.     With buff == NULL, the current buffer will be deallocated and a
  5069.     new one of (approximately) size will be allocated.  If buffer is
  5070.     non-NULL, it will be used for buffering and must be at least
  5071.     max(size,208) bytes long, and MUST be longword aligned.  If size
  5072.     is -1, then only the buffering mode will be changed.
  5073.  
  5074.     Note that a user-supplied buffer will not be freed if it is later
  5075.     replaced by another SetVBuf() call, nor will it be freed if the
  5076.     filehandle is closed.
  5077.  
  5078.     Has no effect on the buffersize of filehandles that were not created
  5079.     by AllocDosObject().
  5080.  
  5081.    INPUTS
  5082.     fh   - Filehandle
  5083.     buff - buffer pointer for buffered I/O or NULL.  MUST be LONG-aligned!
  5084.     type - buffering mode (see <dos/stdio.h>)
  5085.     size - size of buffer for buffered I/O (sizes less than 208 bytes
  5086.            will be rounded up to 208), or -1.
  5087.  
  5088.    RESULT
  5089.     error - 0 if successful.  NOTE: opposite of most dos functions!
  5090.         NOTE: fails if someone has replaced the buffer without
  5091.         using SetVBuf() - RunCommand() does this.  Remember to
  5092.         check error before freeing user-supplied buffers!
  5093.  
  5094.    BUGS
  5095.     Not implemented until after V39.  From V36 up to V39, always
  5096.     returned 0.
  5097.  
  5098.    SEE ALSO
  5099.     FputC(), FGetC(), UnGetC(), Flush(), FRead(), FWrite(), FGets(),
  5100.     FPuts(), AllocDosObject()
  5101.  
  5102. dos.library/SplitName                                   dos.library/SplitName
  5103.  
  5104.    NAME
  5105.     SplitName -- splits out a component of a pathname into a buffer (V36)
  5106.  
  5107.    SYNOPSIS
  5108.     newpos = SplitName(name, separator, buf, oldpos, size)
  5109.     D0                  D1      D2      D3     D4     D5
  5110.  
  5111.     WORD SplitName(STRPTR, UBYTE, STRPTR, WORD, LONG)
  5112.  
  5113.    FUNCTION
  5114.     This routine splits out the next piece of a name from a given file
  5115.     name.  Each piece is copied into the buffer, truncating at size-1
  5116.     characters.  The new position is then returned so that it may be
  5117.     passed in to the next call to splitname.  If the separator is not
  5118.     found within 'size' characters, then size-1 characters plus a null will
  5119.     be put into the buffer, and the position of the next separator will
  5120.     be returned.
  5121.  
  5122.     If a a separator cannot be found, -1 is returned (but the characters
  5123.     from the old position to the end of the string are copied into the
  5124.     buffer, up to a maximum of size-1 characters).  Both strings are
  5125.     null-terminated.
  5126.  
  5127.     This function is mainly intended to support handlers.
  5128.  
  5129.    INPUTS
  5130.     name      - Filename being parsed.
  5131.     separator - Separator charactor to split by.
  5132.     buf       - Buffer to hold separated name.
  5133.     oldpos    - Current position in the file.
  5134.     size       - Size of buf in bytes (including null termination).
  5135.  
  5136.    RESULT
  5137.     newpos    - New position for next call to splitname.  -1 for last one.
  5138.  
  5139.    BUGS
  5140.     In V36 and V37, path portions greater than or equal to 'size' caused
  5141.     the last character of the portion to be lost when followed by a
  5142.     separator.  Fixed for V39 dos.  For V36 and V37, the suggested work-
  5143.     around is to call SplitName() with a buffer one larger than normal
  5144.     (for example, 32 bytes), and then set buf[size-2] to '0' (for example,
  5145.     buf[30] = '\0';).
  5146.  
  5147.    SEE ALSO
  5148.     FilePart(), PathPart(), AddPart()
  5149.  
  5150. dos.library/StartNotify                               dos.library/StartNotify
  5151.  
  5152.    NAME
  5153.     StartNotify -- Starts notification on a file or directory (V36)
  5154.  
  5155.    SYNOPSIS
  5156.     success = StartNotify(notifystructure)
  5157.     D0                          D1
  5158.  
  5159.     BOOL StartNotify(struct NotifyRequest *)
  5160.  
  5161.    FUNCTION
  5162.     Posts a notification request.  Do not modify the notify structure while
  5163.     it is active.  You will be notified when the file or directory changes.
  5164.     For files, you will be notified after the file is closed.  Not all
  5165.     filesystems will support this: applications should NOT require it.  In
  5166.     particular, most network filesystems won't support it.
  5167.  
  5168.    INPUTS
  5169.     notifystructure - A filled-in NotifyRequest structure
  5170.  
  5171.    RESULT
  5172.     success - Success/failure of request
  5173.  
  5174.    BUGS
  5175.     The V36 floppy/HD filesystem doesn't actually send notifications.  The
  5176.     V36 ram handler (ram:) does.  This has been fixed for V37.
  5177.  
  5178.    SEE ALSO
  5179.     EndNotify(), <dos/notify.h>
  5180.  
  5181. dos.library/StrToDate                                   dos.library/StrToDate
  5182.  
  5183.    NAME
  5184.     StrToDate -- Converts a string to a DateStamp (V36)
  5185.  
  5186.    SYNOPSIS
  5187.     success = StrToDate( datetime )
  5188.     D0                      D1
  5189.  
  5190.     BOOL StrToDate( struct DateTime * )
  5191.  
  5192.    FUNCTION
  5193.     Converts a human readable ASCII string into an AmigaDOS
  5194.     DateStamp.
  5195.  
  5196.    INPUTS
  5197.     DateTime - a pointer to an initialized DateTime structure.
  5198.  
  5199.     The DateTime structure should    be initialized as follows:
  5200.  
  5201.     dat_Stamp  - ignored on input.
  5202.  
  5203.     dat_Format - a format    byte which specifies the format    of the
  5204.         dat_StrDat.  This can    be any of the following    (note:
  5205.         If value used    is something other than    those below,
  5206.         the default of FORMAT_DOS is used):
  5207.  
  5208.         FORMAT_DOS:      AmigaDOS format (dd-mmm-yy).
  5209.  
  5210.         FORMAT_INT:      International    format (yy-mmm-dd).
  5211.  
  5212.         FORMAT_USA:      American format (mm-dd-yy).
  5213.  
  5214.         FORMAT_CDN:      Canadian format (dd-mm-yy).
  5215.  
  5216.         FORMAT_DEF:      default format for locale.
  5217.  
  5218.     dat_Flags - a flags byte.  The only flag which affects this
  5219.           function is:
  5220.  
  5221.         DTF_SUBST:    ignored by this function
  5222.         DTF_FUTURE:      If set, indicates that strings such
  5223.                   as (stored in    dat_StrDate) "Monday"
  5224.                   refer    to "next" monday. Otherwise,
  5225.                   if clear, strings like "Monday"
  5226.                   refer    to "last" monday.
  5227.  
  5228.     dat_StrDay - ignored bythis function.
  5229.  
  5230.     dat_StrDate -    pointer    to valid string    representing the date.
  5231.           This can be a    "DTF_SUBST" style string such as
  5232.           "Today" "Tomorrow" "Monday", or it may be a string
  5233.           as specified by the dat_Format byte.    This will be
  5234.           converted to the ds_Days portion of the DateStamp.
  5235.           If this pointer is NULL, DateStamp->ds_Days will not
  5236.           be affected.
  5237.  
  5238.     dat_StrTime -    Pointer    to a buffer which contains the time in
  5239.           the ASCII format hh:mm:ss.  This will    be converted
  5240.           to the ds_Minutes and    ds_Ticks portions of the
  5241.           DateStamp.  If this pointer is NULL, ds_Minutes and
  5242.           ds_Ticks will    be unchanged.
  5243.  
  5244.    RESULT
  5245.     success    - a zero return indicates that a conversion could
  5246.         not be performed. A non-zero return indicates that the
  5247.         DateTime.dat_Stamp variable contains the converted
  5248.         values.
  5249.  
  5250.    SEE ALSO
  5251.     DateStamp(), DateToStr(), <dos/datetime.h>
  5252.  
  5253. dos.library/StrToLong                                   dos.library/StrToLong
  5254.  
  5255.    NAME
  5256.     StrToLong -- string to long value (decimal) (V36)
  5257.  
  5258.    SYNOPSIS
  5259.     characters = StrToLong(string,value)
  5260.     D0                       D1    D2
  5261.  
  5262.     LONG StrToLong(STRPTR, LONG *)
  5263.  
  5264.    FUNCTION
  5265.     Converts decimal string into LONG value.  Returns number of characters
  5266.     converted.  Skips over leading spaces & tabs (included in count).  If
  5267.     no decimal digits are found (after skipping leading spaces & tabs),
  5268.     StrToLong returns -1 for characters converted, and puts 0 into value.
  5269.  
  5270.    INPUTS
  5271.     string - Input string.
  5272.     value  - Pointer to long value.  Set to 0 if no digits are converted.
  5273.  
  5274.    RESULT
  5275.     result - Number of characters converted or -1.
  5276.  
  5277.    BUGS
  5278.     Before V39, if there were no convertible characters it returned the
  5279.     number of leading white-space characters (space and tab in this case).
  5280.  
  5281. dos.library/SystemTagList                           dos.library/SystemTagList
  5282.  
  5283.    NAME
  5284.     SystemTagList -- Have a shell execute a command line (V36)
  5285.  
  5286.    SYNOPSIS
  5287.     error = SystemTagList(command, tags)
  5288.     D0                D1      D2 
  5289.  
  5290.     LONG SystemTagList(STRPTR, struct TagItem *)
  5291.  
  5292.     error = System(command, tags)
  5293.     D0         D1      D2 
  5294.  
  5295.     LONG System(STRPTR, struct TagItem *)
  5296.  
  5297.     error = SystemTags(command, Tag1, ...)
  5298.  
  5299.     LONG SystemTags(STRPTR, ULONG, ...)
  5300.  
  5301.    FUNCTION
  5302.     Similar to Execute(), but does not read commands from the input
  5303.     filehandle.  Spawns a Shell process to execute the command, and
  5304.     returns the returncode the command produced, or -1 if the command
  5305.     could not be run for any reason.  The input and output filehandles
  5306.     will not be closed by System, you must close them (if needed) after
  5307.     System returns, if you specified them via SYS_Input or SYS_Output.
  5308.  
  5309.     By default the new process will use your current Input() and Output()
  5310.     filehandles.  Normal Shell command-line parsing will be done
  5311.     including redirection on 'command'.  The current directory and path
  5312.     will be inherited from your process.  Your path will be used to find
  5313.     the command (if no path is specified).
  5314.  
  5315.     Note that you may NOT pass the same filehandle for both SYS_Input
  5316.     and SYS_Output.  If you want input and output to both be to the same
  5317.     CON: window, pass a SYS_Input of a filehandle on the CON: window,
  5318.     and pass a SYS_Output of NULL.  The shell will automatically set
  5319.     the default Output() stream to the window you passed via SYS_Input,
  5320.     by opening "*" on that handler.
  5321.  
  5322.     If used with the SYS_Asynch flag, it WILL close both it's input and
  5323.     output filehandles after running the command (even if these were
  5324.     your Input() and Output()!)
  5325.  
  5326.     Normally uses the boot (ROM) shell, but other shells can be specified
  5327.     via SYS_UserShell and SYS_CustomShell.  Normally, you should send
  5328.     things written by the user to the UserShell.  The UserShell defaults
  5329.     to the same shell as the boot shell.
  5330.  
  5331.     The tags are passed through to CreateNewProc() (tags that conflict
  5332.     with SystemTagList() will be filtered out).  This allows setting
  5333.     things like priority, etc for the new process.  The tags that are
  5334.     currently filtered out are:
  5335.  
  5336.         NP_Seglist
  5337.         NP_FreeSeglist
  5338.         NP_Entry
  5339.         NP_Input
  5340.         NP_Output
  5341.         NP_CloseInput
  5342.         NP_CloseOutput
  5343.         NP_HomeDir
  5344.         NP_Cli
  5345.  
  5346.    INPUTS
  5347.     command - Program and arguments
  5348.     tags    - see <dos/dostags.h>.  Note that both SystemTagList()-
  5349.           specific tags and tags from CreateNewProc() may be passed.
  5350.  
  5351.    RESULT
  5352.     error    - 0 for success, result from command, or -1.  Note that on
  5353.           error, the caller is responsible for any filehandles or other
  5354.           things passed in via tags.  -1 will only be returned if
  5355.           dos could not create the new shell.  If the command is not
  5356.           found the shell will return an error value, normally
  5357.           RETURN_ERROR.
  5358.  
  5359.    SEE ALSO
  5360.     Execute(), CreateNewProc(), <dos/dostags.h>, Input(), Output()
  5361.  
  5362. dos.library/UnGetC                                         dos.library/UnGetC
  5363.  
  5364.    NAME
  5365.     UnGetC -- Makes a char available for reading again. (buffered) (V36)
  5366.  
  5367.    SYNOPSIS
  5368.     value = UnGetC(fh, character)
  5369.     D0           D1      D2
  5370.  
  5371.     LONG UnGetC(BPTR, LONG)
  5372.  
  5373.    FUNCTION
  5374.     Pushes the character specified back into the input buffer.  Every
  5375.     time you use a buffered read routine, you can always push back 1
  5376.     character.  You may be able to push back more, though it is not
  5377.     recommended, since there is no guarantee on how many can be
  5378.     pushed back at a given moment.
  5379.  
  5380.     Passing -1 for the character will cause the last character read to
  5381.     be pushed back.  If the last character read was an EOF, the next
  5382.     character read will be an EOF.
  5383.  
  5384.     Note: UnGetC can be used to make sure that a filehandle is set up
  5385.     as a read filehandle.  This is only of importance if you are writing
  5386.     a shell, and must manipulate the filehandle's buffer.
  5387.  
  5388.    INPUTS
  5389.     fh      - filehandle to use for buffered I/O
  5390.     character - character to push back or -1
  5391.  
  5392.    RESULT
  5393.     value     - character pushed back, or FALSE if the character cannot
  5394.             be pushed back.
  5395.  
  5396.    BUGS
  5397.     In V36, UnGetC(fh,-1) after an EOF would not cause the next character
  5398.     read to be an EOF.  This was fixed for V37.
  5399.  
  5400.    SEE ALSO
  5401.     FGetC(), FPutC(), Flush()
  5402.  
  5403. dos.library/UnLoadSeg                                   dos.library/UnLoadSeg
  5404.  
  5405.     NAME
  5406.     UnLoadSeg -- Unload a seglist previously loaded by LoadSeg()
  5407.  
  5408.     SYNOPSIS
  5409.     success = UnLoadSeg( seglist )
  5410.     D0               D1
  5411.  
  5412.     BOOL UnLoadSeg(BPTR)
  5413.  
  5414.     FUNCTION
  5415.     Unload a seglist loaded by LoadSeg().  'seglist' may be zero.
  5416.     Overlaid segments will have all needed cleanup done, including
  5417.     closing files.
  5418.  
  5419.     INPUTS
  5420.     seglist - BCPL pointer to a segment identifier
  5421.  
  5422.     RESULTS
  5423.     success - returns 0 if a NULL seglist was passed or if it failed
  5424.           to close an overlay file.  NOTE: this function returned
  5425.           a random value before V36!
  5426.  
  5427.     SEE ALSO
  5428.     LoadSeg(), InternalLoadSeg(), InternalUnLoadSeg()
  5429.  
  5430. dos.library/UnLock                                         dos.library/UnLock
  5431.  
  5432.     NAME
  5433.     UnLock -- Unlock a directory or file
  5434.  
  5435.     SYNOPSIS
  5436.     UnLock( lock )
  5437.         D1
  5438.  
  5439.     void UnLock(BPTR)
  5440.  
  5441.     FUNCTION
  5442.     The filing system lock (obtained from Lock(), DupLock(), or
  5443.     CreateDir()) is removed and deallocated.
  5444.  
  5445.     INPUTS
  5446.     lock - BCPL pointer to a lock
  5447.  
  5448.     NOTE
  5449.     passing zero to UnLock() is harmless
  5450.  
  5451.     SEE ALSO
  5452.     Lock(), DupLock(), ParentOfFH(), DupLockFromFH()
  5453.  
  5454. dos.library/UnLockDosList                           dos.library/UnLockDosList
  5455.  
  5456.    NAME
  5457.     UnLockDosList -- Unlocks the Dos List (V36)
  5458.  
  5459.    SYNOPSIS
  5460.     UnLockDosList(flags)
  5461.             D1
  5462.  
  5463.     void UnLockDosList(ULONG)
  5464.  
  5465.    FUNCTION
  5466.     Unlocks the access on the Dos Device List.  You MUST pass the same
  5467.     flags you used to lock the list.
  5468.  
  5469.    INPUTS
  5470.     flags - MUST be the same flags passed to (Attempt)LockDosList()
  5471.  
  5472.    SEE ALSO
  5473.     AttemptLockDosList(), LockDosList(), Permit()
  5474.  
  5475. dos.library/UnLockRecord                             dos.library/UnLockRecord
  5476.  
  5477.    NAME
  5478.     UnLockRecord -- Unlock a record (V36)
  5479.  
  5480.    SYNOPSIS
  5481.     success = UnLockRecord(fh,offset,length)
  5482.     D0               D1   D2     D3
  5483.  
  5484.     BOOL UnLockRecord(BPTR,ULONG,ULONG)
  5485.  
  5486.    FUNCTION
  5487.     This releases the specified lock on a file.  Note that you must use
  5488.     the same filehandle you used to lock the record, and offset and length
  5489.     must be the same values used to lock it.  Every LockRecord() call must
  5490.     be balanced with an UnLockRecord() call.
  5491.  
  5492.    INPUTS
  5493.     fh      - File handle of locked file
  5494.     offset  - Record start position
  5495.     length  - Length of record in bytes
  5496.  
  5497.    RESULT
  5498.     success - Success or failure.
  5499.  
  5500.    BUGS
  5501.     See LockRecord()
  5502.  
  5503.    SEE ALSO
  5504.     LockRecords(), LockRecord(), UnLockRecords()
  5505.  
  5506. dos.library/UnLockRecords                           dos.library/UnLockRecords
  5507.  
  5508.    NAME
  5509.     UnLockRecords -- Unlock a list of records (V36)
  5510.  
  5511.    SYNOPSIS
  5512.     success = UnLockRecords(record_array)
  5513.     D0                     D1
  5514.  
  5515.     BOOL UnLockRecords(struct RecordLock *)
  5516.  
  5517.    FUNCTION
  5518.     This releases an array of record locks obtained using LockRecords.
  5519.     You should NOT modify the record_array while you have the records
  5520.     locked.  Every LockRecords() call must be balanced with an
  5521.     UnLockRecords() call.
  5522.  
  5523.    INPUTS
  5524.     record_array - List of records to be unlocked
  5525.  
  5526.    RESULT
  5527.     success      - Success or failure.
  5528.  
  5529.    BUGS
  5530.     See LockRecord()
  5531.  
  5532.    SEE ALSO
  5533.     LockRecords(), LockRecord(), UnLockRecord()
  5534.  
  5535. dos.library/VFPrintf                                     dos.library/VFPrintf
  5536.  
  5537.    NAME
  5538.     VFPrintf -- format and print a string to a file (buffered) (V36)
  5539.  
  5540.    SYNOPSIS
  5541.     count = VFPrintf(fh, fmt, argv)
  5542.     D0               D1  D2    D3
  5543.  
  5544.     LONG VFPrintf(BPTR, STRPTR, LONG *)
  5545.  
  5546.     count = FPrintf(fh, fmt, ...)
  5547.  
  5548.     LONG FPrintf(BPTR, STRPTR, ...)
  5549.  
  5550.    FUNCTION
  5551.     Writes the formatted string and values to the given file.  This
  5552.     routine is assumed to handle all internal buffering so that the
  5553.     formatting string and resultant formatted values can be arbitrarily
  5554.     long.  Any secondary error code is returned in IoErr().  This routine
  5555.     is buffered.
  5556.  
  5557.    INPUTS
  5558.     fh    - Filehandle to write to
  5559.     fmt   - RawDoFmt() style formatting string
  5560.     argv  - Pointer to array of formatting values
  5561.  
  5562.    RESULT
  5563.     count - Number of bytes written or -1 (EOF) for an error
  5564.  
  5565.    BUGS
  5566.     The prototype for FPrintf() currently forces you to cast the first
  5567.     varargs parameter to LONG due to a deficiency in the program
  5568.     that generates fds, prototypes, and amiga.lib stubs.
  5569.  
  5570.    SEE ALSO
  5571.     VPrintf(), VFWritef(), RawDoFmt(), FPutC()
  5572.  
  5573. dos.library/VFWritef                                     dos.library/VFWritef
  5574.  
  5575.    NAME
  5576.     VFWritef - write a BCPL formatted string to a file (buffered) (V36)
  5577.  
  5578.    SYNOPSIS
  5579.     count = VFWritef(fh, fmt, argv)
  5580.     D0               D1  D2    D3
  5581.  
  5582.     LONG VFWritef(BPTR, STRPTR, LONG *)
  5583.  
  5584.     count = FWritef(fh, fmt, ...)
  5585.  
  5586.     LONG FWritef(BPTR, STRPTR, ...)
  5587.  
  5588.    FUNCTION
  5589.     Writes the formatted string and values to the specified file.  This
  5590.     routine is assumed to handle all internal buffering so that the
  5591.     formatting string and resultant formatted values can be arbitrarily
  5592.     long.  The formats are in BCPL form.  This routine is buffered.
  5593.  
  5594.     Supported formats are:  (Note x is in base 36!)
  5595.         %S  - string (CSTR)
  5596.         %Tx - writes a left-justified string in a field at least
  5597.               x bytes long.
  5598.         %C  - writes a single character
  5599.         %Ox - writes a number in octal, maximum x characters wide
  5600.         %Xx - writes a number in hex, maximum x characters wide
  5601.         %Ix - writes a number in decimal, maximum x characters wide
  5602.         %N  - writes a number in decimal, any length
  5603.         %Ux - writes an unsigned number, maximum x characters wide
  5604.         %$  - ignore parameter
  5605.  
  5606.     Note: 'x' above is actually the character value - '0'.
  5607.  
  5608.    INPUTS
  5609.     fh    - filehandle to write to
  5610.     fmt   - BCPL style formatting string
  5611.     argv  - Pointer to array of formatting values
  5612.  
  5613.    RESULT
  5614.     count - Number of bytes written or -1 for error
  5615.  
  5616.    BUGS
  5617.     As of V37, VFWritef() does NOT return a valid return value.  In
  5618.     order to reduce possible errors, the prototypes supplied for the
  5619.     system as of V37 have it typed as VOID.
  5620.  
  5621.    SEE ALSO
  5622.     VFPrintf(), VFPrintf(), FPutC()
  5623.  
  5624. dos.library/VPrintf                                       dos.library/VPrintf
  5625.  
  5626.    NAME
  5627.     VPrintf -- format and print string (buffered) (V36)
  5628.  
  5629.    SYNOPSIS
  5630.     count = VPrintf(fmt, argv)
  5631.       D0            D1   D2
  5632.  
  5633.     LONG VPrintf(STRPTR, LONG *)
  5634.  
  5635.     count = Printf(fmt, ...)
  5636.  
  5637.     LONG Printf(STRPTR, ...)
  5638.  
  5639.    FUNCTION
  5640.     Writes the formatted string and values to Output().  This routine is 
  5641.     assumed to handle all internal buffering so that the formatting string
  5642.     and resultant formatted values can be arbitrarily long.  Any secondary
  5643.     error code is returned in IoErr().  This routine is buffered.
  5644.  
  5645.     Note: RawDoFmt assumes 16 bit ints, so you will usually need 'l's in
  5646.     your formats (ex: %ld versus %d).
  5647.  
  5648.    INPUTS
  5649.     fmt   - exec.library RawDoFmt() style formatting string
  5650.     argv  - Pointer to array of formatting values
  5651.    
  5652.    RESULT
  5653.     count - Number of bytes written or -1 (EOF) for an error
  5654.  
  5655.    BUGS
  5656.     The prototype for Printf() currently forces you to cast the first
  5657.     varargs parameter to LONG due to a deficiency in the program
  5658.     that generates fds, prototypes, and amiga.lib stubs.
  5659.  
  5660.    SEE ALSO
  5661.     VFPrintf(), VFWritef(), RawDoFmt(), FPutC()
  5662.  
  5663. dos.library/WaitForChar                               dos.library/WaitForChar
  5664.  
  5665.     NAME
  5666.     WaitForChar -- Determine if chars arrive within a time limit
  5667.  
  5668.     SYNOPSIS
  5669.     status = WaitForChar( file, timeout )
  5670.     D0              D1    D2
  5671.  
  5672.     BOOL WaitForChar(BPTR, LONG)
  5673.  
  5674.     FUNCTION
  5675.     If a character is available to be read from 'file' within the
  5676.     time (in microseconds) indicated by 'timeout', WaitForChar()
  5677.     returns -1 (TRUE). If a character is available, you can use Read()
  5678.     to read it.  Note that WaitForChar() is only valid when the I/O
  5679.     stream is connected to a virtual terminal device. If a character is
  5680.     not available within 'timeout', a 0 (FALSE) is returned.
  5681.  
  5682.     BUGS
  5683.     Due to a bug in the timer.device in V1.2/V1.3, specifying a timeout
  5684.     of zero for WaitForChar() can cause the unreliable timer & floppy
  5685.     disk operation.
  5686.  
  5687.     INPUTS
  5688.     file - BCPL pointer to a file handle
  5689.     timeout - integer
  5690.  
  5691.     RESULTS
  5692.     status - boolean
  5693.  
  5694.     SEE ALSO
  5695.     Read(), FGetC()
  5696.  
  5697. dos.library/WaitPkt                                       dos.library/WaitPkt
  5698.  
  5699.    NAME
  5700.     WaitPkt -- Waits for a packet to arrive at your pr_MsgPort (V36)
  5701.  
  5702.    SYNOPSIS
  5703.     packet = WaitPkt()
  5704.     D0
  5705.  
  5706.     struct DosPacket *WaitPkt(void);
  5707.  
  5708.    FUNCTION
  5709.     Waits for a packet to arrive at your pr_MsgPort.  If anyone has
  5710.     installed a packet wait function in pr_PktWait, it will be called.
  5711.     The message will be automatically GetMsg()ed so that it is no longer
  5712.     on the port.  It assumes the message is a dos packet.  It is NOT
  5713.     guaranteed to clear the signal for the port.
  5714.  
  5715.    RESULT
  5716.     packet - the packet that arrived at the port (from ln_Name of message).
  5717.  
  5718.    SEE ALSO
  5719.     SendPkt(), DoPkt(), AbortPkt()
  5720.  
  5721. dos.library/Write                                           dos.library/Write
  5722.  
  5723.     NAME
  5724.     Write -- Write bytes of data to a file
  5725.  
  5726.     SYNOPSIS
  5727.     returnedLength =  Write( file, buffer, length )
  5728.     D0             D1    D2      D3
  5729.  
  5730.     LONG Write (BPTR, void *, LONG)
  5731.  
  5732.     FUNCTION
  5733.     Write() writes bytes of data to the opened file 'file'. 'length'
  5734.     indicates the length of data to be transferred; 'buffer' is a
  5735.     pointer to the buffer. The value returned is the length of
  5736.     information actually written. So, when 'length' is greater than
  5737.     zero, the value of 'length' is the number of characters written.
  5738.     Errors are indicated by a value of -1.
  5739.  
  5740.     Note: this is an unbuffered routine (the request is passed directly
  5741.     to the filesystem.)  Buffered I/O is more efficient for small
  5742.     reads and writes; see FPutC().
  5743.  
  5744.     INPUTS
  5745.     file - BCPL pointer to a file handle
  5746.     buffer - pointer to the buffer
  5747.     length - integer
  5748.  
  5749.     RESULTS
  5750.     returnedLength - integer
  5751.  
  5752.     SEE ALSO
  5753.     Read(), Seek(), Open(), Close(), FPutC
  5754.  
  5755. dos.library/WriteChars                                 dos.library/WriteChars
  5756.  
  5757.    NAME
  5758.     WriteChars -- Writes bytes to the the default output (buffered) (V36)
  5759.  
  5760.    SYNOPSIS
  5761.     count = WriteChars(buf, buflen)
  5762.     D0                 D1
  5763.  
  5764.     LONG WriteChars(STRPTR, LONG)
  5765.  
  5766.    FUNCTION
  5767.     This routine writes a number of bytes to the default output.  The
  5768.     length is returned.  This routine is buffered.
  5769.  
  5770.    INPUTS
  5771.     buf    - buffer of characters to write
  5772.     buflen - number of characters to write
  5773.  
  5774.    RESULT
  5775.     count - Number of bytes written.  -1 (EOF) indicates an error
  5776.  
  5777.    SEE ALSO
  5778.     FPuts(), FPutC(), FWrite(), PutStr()
  5779.  
  5780.