home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / cmanual-3.0.lha / CManual-3.0 / Amiga / Appendices / FunctionsAndLibraries / DosLibrary.doc < prev    next >
Encoding:
Text File  |  1993-10-12  |  13.3 KB  |  427 lines
  1. 4    DOS LIBRARY
  2.  
  3. 4.1  OPEN THE DOS LIBRARY
  4.  
  5. The Dos Library is automatically opened when your program is
  6. loaded, so you do not have to open it yorself. The functions
  7. listed in this file can therefore directly be used.
  8.  
  9.  
  10.  
  11. 4.2  FUNCTIONS
  12.  
  13. Close()
  14.  
  15.   This function closes an already opened file. Remember to
  16.   close ALL files you have opened!
  17.  
  18.   Synopsis:    Close( file_handle );
  19.  
  20.   file_handle: (BPTR) Actually a pointer to a FileHandle
  21.                structure which has been initialized by a
  22.                previous Open() call.
  23.  
  24.  
  25.  
  26. CreateDir()
  27.  
  28.   This function creates a new directory, AND "locks" is
  29.   automatically. (Remember to unlock the directory later on.)
  30.  
  31.   Synopsis: lock = CreateDir( name );
  32.  
  33.   lock:     (BPTR) Actually a pointer to a FileLock structure.
  34.             If lock is equal to NULL, AmigaDOS have not been
  35.             able to create the new directory.
  36.  
  37.   name:     (char *) Pointer to a string containing the name
  38.             of the new directory.
  39.  
  40.  
  41.  
  42. CurrentDir()
  43.  
  44.   This function makes a specified directory "current
  45.   directory". You need to lock the new directory (new_lock)
  46.   before you can make it the current directory. The function
  47.   returns the old current directories lock so you can unlock
  48.   it if necessary.
  49.   
  50.   Synopsis: old_lock = CurrentDir( new_lock );
  51.   
  52.   old_lock: (BPTR) Actually a pointer to a FileLock structure.
  53.             It is the old current directory lock.
  54.   
  55.   new_lock: (BPTR) Actually a pointer to a FileLock structure.
  56.             The new current directory lock.
  57.  
  58.  
  59.  
  60. Delay()
  61.  
  62.   This function will put your program to sleep for a specified
  63.   time period. Note that this function should be used instead
  64.   of a "dummy" loop when you want to pause a program. The
  65.   problem with wait loops is that the time it takes to execute
  66.   it depends on how fast the computer is. If you want to wait
  67.   for a while you should use this function since the delay time
  68.   will then always be the same no matter how fast or slow
  69.   the computer is. A dummy loop will also waist a lot of
  70.   processor time while the nice Delay() function will put your
  71.   task to sleep so the processor can work with other things.
  72.  
  73.   Synopsis: Delay( time );
  74.   
  75.   time:     (ULONG) How long time you want to wait. The value
  76.             is specified in "timer units" were 50 units is
  77.             equal to 1 second. If you want to wait two minutes
  78.             you should set this field to 2 * 60 * 50 = 6000.
  79.  
  80.             
  81.  
  82. DeleteFile()
  83.  
  84.   This function deletes a file or directory. Remember that
  85.   a directory must be empty before it can be deleted.
  86.  
  87.   Synopsis: ok = DeleteFile( name );
  88.  
  89.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  90.             could delete the file/directory, else FALSE which
  91.             means something went wrong. (Eg. disk write-
  92.             protected, directory not empty etc.)
  93.  
  94.   name:     (char *) Pointer to a string containing the name
  95.             of the file/directory you want to delete. 
  96.  
  97.  
  98.  
  99. Examine()
  100.   
  101.   This function can be used to get information about a file,
  102.   directory or device.
  103.  
  104.   Synopsis: ok = Examine( lock, fib_ptr );
  105.  
  106.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  107.             could get information about the file/directory,
  108.             else FALSE which means something went wrong.
  109.  
  110.   lock:     (BPTR) Actually a pointer to a FileLock structure.
  111.  
  112.   fib_ptr:  (struct FileInfoBlock *) Pointer to a FileInfoBlock
  113.             structure which will be initialized with some
  114.             information about the file/directory. IMPORTANT!
  115.             the structure must be on a 4 byte boundary.
  116.  
  117.  
  118. ExNext()
  119.  
  120.   This function should be used when you want to examine a
  121.   directory. You should first use the function Examine() to
  122.   see if it is a directory/device or if it simply is a file.
  123.   If it is a directory/device (fib_DirEntryType > 0), you may
  124.   call the ExNext() function until you receive an error
  125.   message.
  126.  
  127.   Synopsis: ok = ExNext( lock, fib_ptr );
  128.  
  129.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  130.             could get information about a file/directory in the
  131.             directory/device, else FALSE which means something
  132.             went wrong.
  133.  
  134.   lock:     (BPTR) Actually a pointer to a FileLock structure.
  135.  
  136.   fib_ptr:  (struct FileInfoBlock *) Pointer to a FileInfoBlock
  137.             structure which will be initialized with some
  138.             information about the file/directory. IMPORTANT!
  139.             the structure must be on a 4 byte boundary.
  140.  
  141.  
  142.  
  143. Info()
  144.  
  145.   This function returns information about a specified disk. You
  146.   specify which disk by either lock that disk, or a file/
  147.   directory on that disk.
  148.  
  149.   Synopsis:  ok = Info( lock, info_data );
  150.   
  151.   ok:        (long) Actually a Boolean. It is TRUE if AmigaDOS
  152.              could get information about the disk, else FALSE
  153.              which means something went wrong.
  154.  
  155.   lock:      (BPTR) Actually a pointer to a FileLock structure.
  156.  
  157.   info_data: (struct InfoData *) Pointer to an InfoData
  158.              structure which will be initialized by the Info()
  159.              function. The problem with this structure is that
  160.              it must be on a four byte boundary, so you need
  161.              to use the function AllocMem() to get the right
  162.              type of memory for the structure. (See Example.)
  163.  
  164.  
  165.  
  166. IoErr()
  167.  
  168.   This function can be used to get more information about an
  169.   error message. Whenever you have used an AmigaDOS function
  170.   which did not work properly (you have received an error
  171.   message), you call this function and it will return an
  172.   explanation.
  173.   
  174.   Synopsis: error = IoErr();
  175.   
  176.   error:    (long) This field contains a flag returned by
  177.             IoErr() which can be: (I do not think I need
  178.             to explain what they mean.)
  179.  
  180.             ERROR_NO_FREE_STORE
  181.             ERROR_TASK_TABLE_FULL
  182.             ERROR_LINE_TOO_LONG
  183.             ERROR_FILE_NOT_OBJECT
  184.             ERROR_INVALID_RESIDENT_LIBRARY
  185.             ERROR_NO_DEFAULT_DIR
  186.             ERROR_OBJECT_IN_USE
  187.             ERROR_OBJECT_EXISTS
  188.             ERROR_DIR_NOT_FOUND
  189.             ERROR_OBJECT_NOT_FOUND
  190.             ERROR_BAD_STREAM_NAME
  191.             ERROR_OBJECT_TOO_LARGE
  192.             ERROR_ACTION_NOT_KNOWN
  193.             ERROR_INVALID_COMPONENT_NAME
  194.             ERROR_INVALID_LOCK
  195.             ERROR_OBJECT_WRONG_TYPE
  196.             ERROR_DISK_NOT_VALIDATED
  197.             ERROR_DISK_WRITE_PROTECTED
  198.             ERROR_RENAME_ACROSS_DEVICES
  199.             ERROR_DIRECTORY_NOT_EMPTY
  200.             ERROR_TOO_MANY_LEVELS
  201.             ERROR_DEVICE_NOT_MOUNTED
  202.             ERROR_SEEK_ERROR
  203.             ERROR_COMMENT_TOO_BIG
  204.             ERROR_DISK_FULL
  205.             ERROR_DELETE_PROTECTED
  206.             ERROR_WRITE_PROTECTED
  207.             ERROR_READ_PROTECTED
  208.             ERROR_NOT_A_DOS_DISK
  209.             ERROR_NO_DISK
  210.             ERROR_NO_MORE_ENTRIES
  211.  
  212.  
  213.  
  214. Lock()
  215.  
  216.   This function "locks" a file so no other processes may alter
  217.   the contents (SHARED_LOCK). You can even prevent other
  218.   processes to read the file (EXCLUSIVE_LOCK).
  219.  
  220.   Synopsis: lock = Lock( name, mode );
  221.  
  222.   lock:     (BPTR) Actually a pointer to a FileLock structure.
  223.  
  224.   name:     (char *) Pointer to a text string which contains
  225.             the file/directory name.
  226.  
  227.   mode:     (long) Accessmode:
  228.               SHARED_LOCK:     Other tasks may read the file.
  229.               ACCESS_READ:                 - " -
  230.               EXCLUSIVE_LOCK:  No other tasks may use this f.
  231.               ACCESS_WRITE:                - " -
  232.  
  233.  
  234.  
  235. Open()
  236.  
  237.   This function opens a file. Remember, before you can read/
  238.   write files you have to open them. 
  239.  
  240.   Synopsis:    file_handle = Open( file_name, mode );
  241.  
  242.   file_handle: (BPTR) Actually a pointer to a FileHandle
  243.                structure. If the system could not open the file
  244.                with our requirements Open() returns NULL.
  245.  
  246.   file_name:   (char *) Pointer to a text string which contains
  247.                the file name including any necessary devices/
  248.                directories.
  249.  
  250.   mode:        (long) When you open a file you need to tell the
  251.                system what you are going to do with it. This
  252.                field should therefore contain one of the
  253.                following flags:
  254.  
  255.                MODE_OLDFILE:   Opens an existing file for
  256.                                reading and writing.
  257.  
  258.                MODE_NEWFILE:   Opens a new file for writing.
  259.                                (If the file already exist it
  260.                                is deleted.)
  261.  
  262.                MODE_READWRITE: Opens an old file with an
  263.                                exclusive lock. (The file is
  264.                                automatically locked with an
  265.                                EXCLUSIVE_LOCK.)
  266.  
  267.                MODE_READONLY:  Same as MODE_OLDFILE.
  268.  
  269.  
  270.  
  271. Read()
  272.  
  273.   This function reads a specified number of bytes from a file.
  274.  
  275.   Synopsis:    bytes_read = Read( file_handle, buffer, size );
  276.  
  277.   bytes_read:  (long) Number of bytes actually read. Even if
  278.                you tell AmigaDOS that you want to read x
  279.                number of bytes, it is not certain that you
  280.                actually can do it. The file is maybe corrupted,
  281.                not as big as you thought etc.
  282.  
  283.   file_handle: (BPTR) Actually a pointer to a FileHandle
  284.                structure which has been initialized by a
  285.                previous Open() call.
  286.  
  287.   buffer:      (char *) Pointer to the data buffer you want to
  288.                read the data into.
  289.  
  290.   size:        (long) Number of bytes you want to read.
  291.  
  292.  
  293.  
  294. Rename()
  295.  
  296.   This function renames a file or directory. You can even
  297.   move a file between directories by renaming it. (For example,
  298.   Rename( "df0:Documents/Sale.doc", "df0:Letters/Sale.doc" );
  299.   will move the file Sale.doc from the directory "Documents"
  300.   to directory "Letters". Note! You can not rename a file from
  301.   one volume to another.)
  302.   
  303.   Synopsis: ok = Rename( old_name, new_name );
  304.   
  305.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  306.             could rename the file/directory, else FALSE which
  307.             means something went wrong. (Eg. disk write
  308.             -protected.)
  309.  
  310.   old_name: (char *) Pointer to a string containing the old
  311.             file/directory name.
  312.  
  313.   new_name: (char *) Pointer to a string containing the new
  314.             file/directory name.
  315.  
  316.  
  317.  
  318. Seek()
  319.  
  320.   This function moves the "file cursor" inside a file:
  321.  
  322.   Synopsis:    old_pos = Seek( file_handle, new_pos, mode );
  323.  
  324.   old_pos:     (long) Previous position in the file, or -1 if
  325.                an error occurred.
  326.  
  327.   file_handle: (BPTR) Actually a pointer to a FileHandle
  328.                structure which has been initialized by a
  329.                previous Open() call.
  330.  
  331.   new_pos:     (long) New position relative to the "mode".
  332.  
  333.   mode:        (long) The new_pos can be relative to:
  334.                  OFFSET_BEGINNING: Beginning of the file.
  335.                  OFFSET_CURRENT:   Current position.
  336.                  OFFSET_END:       The end of the file.
  337.  
  338.  
  339.  
  340. SetComment
  341.  
  342.   This function attach a comment to a file or directory.
  343.  
  344.   Synopsis: ok = SetComment( name, comment );
  345.  
  346.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  347.             could attach the new comment, else FALSE which
  348.             means something went wrong. (Eg. disk write-
  349.             protected.)
  350.  
  351.   name:     (char *) Pointer to a string containing the name
  352.             of the file/directory you want to attach the
  353.             comment to.
  354.  
  355.   comment:  (char *) Pointer to a string containing the
  356.             comment. (A comment may be up to 80 characters
  357.             long.)
  358.  
  359.  
  360.  
  361. SetProtection()
  362.  
  363.   This function alters the protection bits of a file.
  364.   You can set following flags:
  365.   
  366.   FIBF_DELETE  : the file/directory can not be deleted.
  367.   FIBF_EXECUTE : the file can not be executed.
  368.   FIBF_WRITE   : you can not write to the file.
  369.   FIBF_READ    : you can not read the file.
  370.   FIBF_ARCHIVE : Archive bit.
  371.   FIBF_PURE    : Pure bit.
  372.   FIBF_SCRIPT  : Script bit.
  373.  
  374.   (Note! All of the flags are for the moment not working!)
  375.   
  376.   Synopsis: ok = SetProtection( name, mask );
  377.   
  378.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  379.             could alter the protection bits, else FALSE which
  380.             means something went wrong. (Eg. disk write-
  381.             protected.)
  382.  
  383.   name:     (char *) Pointer to a string containing the name
  384.             of the file/directory you want to change the
  385.             protection bits.
  386.  
  387.   mask:     (long) The protection bits. (For example, if you
  388.             want to make the file/directory not deletable,
  389.             and that it can not be executed you should set the
  390.             protection bits: FIBF_DELETE | FIBF_EXECUTE.)
  391.  
  392.  
  393.  
  394. UnLock()
  395.  
  396.   This function unlocks a previously locked file: (Remember to
  397.   unlock ALL files you have locked!)
  398.  
  399.   Synopsis: Unlock( lock );
  400.  
  401.   lock:     (BPTR) Actually a pointer to FileLock structure
  402.             which has been initialized by a previous Lock()
  403.             call.
  404.  
  405.  
  406.  
  407. Write()
  408.  
  409.   This function writes a specified number of bytes to a file.
  410.  
  411.   Synopsis:  bytes_wr = Write( file_handle, buffer, size );
  412.  
  413.   bytes_wr:    (long) Number of bytes actually written. Even if
  414.                you tell AmigaDOS that you want to write x number
  415.                of bytes, it is not certain that you actually
  416.                can do it. Maybe the disk was full, write-
  417.                protected etc.
  418.  
  419.   file_handle: (BPTR) Actually a pointer to a FileHandle
  420.                structure which has been initialized by a
  421.                previous Open() call.
  422.  
  423.   buffer:      (char *) Pointer to the data buffer which you
  424.                want to write.
  425.  
  426.   size:        (long) Number of bytes you want to write.
  427.