TABLE OF CONTENTS dos.library/AAA-Packet-Documentation dos.library/ACTION_ADD_NOTIFY dos.library/ACTION_CHANGE_FILE_POSITION64 dos.library/ACTION_CHANGE_FILE_SIZE64 dos.library/ACTION_CHANGE_MODE dos.library/ACTION_CHANGE_SIGNAL dos.library/ACTION_COLLECT dos.library/ACTION_COPY_LOCK dos.library/ACTION_COPY_LOCK_FH dos.library/ACTION_CREATE_DIR dos.library/ACTION_CURRENT_VOLUME dos.library/ACTION_DELETE_OBJECT dos.library/ACTION_DIE dos.library/ACTION_DISK_INFO dos.library/ACTION_END dos.library/ACTION_EXAMINE_ALL dos.library/ACTION_EXAMINE_FH dos.library/ACTION_EXAMINE_NEXT dos.library/ACTION_EXAMINE_OBJECT dos.library/ACTION_EXAMINEDATA dos.library/ACTION_EXAMINEDATA_DIR dos.library/ACTION_EXAMINEDATA_FH dos.library/ACTION_FH_FROM_LOCK dos.library/ACTION_FILESYSTEM_ATTR dos.library/ACTION_FINDxxxx dos.library/ACTION_FLUSH dos.library/ACTION_FORMAT dos.library/ACTION_FREE_DISK_FSSM dos.library/ACTION_FREE_LOCK dos.library/ACTION_FREE_RECORD64 dos.library/ACTION_GET_DISK_FSSM dos.library/ACTION_GET_FILE_POSITION64 dos.library/ACTION_GET_FILE_SIZE64 dos.library/ACTION_INFO dos.library/ACTION_INHIBIT dos.library/ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_IS_FILESYSTEM dos.library/ACTION_LOCATE_OBJECT dos.library/ACTION_LOCK_RECORD64 dos.library/ACTION_MAKE_LINK dos.library/ACTION_MORE_CACHE dos.library/ACTION_NIL dos.library/ACTION_OBTAIN_CON_INFO dos.library/ACTION_PARENT dos.library/ACTION_PARENT_FH dos.library/ACTION_READ dos.library/ACTION_READ_SOFT_LINK dos.library/ACTION_RELEASE_CON_INFO dos.library/ACTION_REMOVE_NOTIFY dos.library/ACTION_RENAME_DISK dos.library/ACTION_RENAME_OBJECT dos.library/ACTION_SAME_FH dos.library/ACTION_SAME_LOCK dos.library/ACTION_SEEK dos.library/ACTION_SERIALIZE_DISK dos.library/ACTION_SET_BLOCKING_MODE dos.library/ACTION_SET_COMMENT dos.library/ACTION_SET_DATE dos.library/ACTION_SET_FILE_SIZE dos.library/ACTION_SET_OWNER dos.library/ACTION_SET_OWNER_INFO dos.library/ACTION_SET_PROTECT dos.library/ACTION_SHUTDOWN dos.library/ACTION_SINGLE_CHARACTER_MODE dos.library/ACTION_STARTUP dos.library/ACTION_WAIT_CHAR dos.library/ACTION_WAIT_FOR_DATA dos.library/ACTION_WRITE dos.library/ACTION_WRITE_PROTECT dos.library/AAA-Packet-Documentation dos.library/AAA-Packet-Documentation ============================================================================ NAME DOS LIBRARY PACKET DOCUMENTATION & FILESYSTEM VECTOR-PORT CALLING. SYNOPSIS This document is specifically for filesystem and handler writers. Normal application writers do not require this information. AmigaDOS conventionally communicates with file systems and DOS handlers by sending and receiving dospackets. Dospackets are basically exec style messages but with an extra structure appended to pass parameters back and forth. From dos.library V53.77+ this has been enhanced by making available a second method, exclusively for filesystems, using function vectors instead, functionally similar to the associated dospacket operations. These functions vectors are invoked within the same process context as the caller to perform the same basic operations as the dospacket methods but without the excessive overhead. More details follow at the end of this document, after the dospacket definitions. For opening and closing file handles (including console file handles), creating directories, and renaming disks all require DOS to tell a handler to perform these actions. The particular action a handler performs depends on the type of dospacket it receives, or the particular function vector called. This article documents the standard AmigaDOS dospacket types. Dospackets sent to a file system or handler can be divided into several basic categories: Basic Input/Output: These actions deal with tranferring data to and from objects controlled by the handler. File/Directory Manipulation/Information: These actions are used to gain access to and manipulate the high level structures of the file system. Volume Manipulation/Information: These actions allow access to the specific volume controlled by the file system. Handler Maintenance and Control: These allow control over the handler/file system itself, independent of the actual volume or structure underneath. Handler Internal: These actions are never sent to the handler directly. Instead they are generally responses to IO requests made by the handler. Obsolete Packets: These packets are no longer valid for use by handlers/filesystems. Deprecated Packets: These packets are superceded by new ones with updated functionality and filesystems/handlers should avoid implementing these packets at all and let dos.library emulate the old and limited functionality. Console Only Packets: These packets are specific to console handlers. File Systems can ignore these packets. Several structures are referenced here which can be found by looking at the include files and . Each packet type documented in this article is listed with its action name and any AmigaDOS routines which uses this packet, and the list of parameters that the packet uses. The C variable types for the packet parameters are some of the following types: BPTR This is BCPL pointer (an address which is right shifted by 2). This means that the object must be aligned on a 32 bit address. BSTR This is a BCPL pointer to a string where the first byte indicates the number of bytes in the string. This length byte is unsigned but because it is stored in only 8 bits, the strings are limited to 255 bytes in length before V52 of dos.library. As of V52+ dos.library, "extended BSTR" (XBSTR) strings can be sent to handlers and filesystems from dos.library for extensibility reasons, while still maintaining legacy backward compatibility. These extended BSTR strings are in the same format as a legacy BSTR string but are guaranteed to have a nul-terminator byte added to the end, and the length byte of these will be correct only up to 255 bytes, past that length, the length byte will always read 255 (0xFF) and is there just for limited legacy compatibility. These extended BSTR strings are always documented and identified by having an additional dospacket identifier parameter supplied, consult the individual dospacket documentation for details. See also; ACTION_INHIBIT_DOS_LONGPATH_HANDLING for details on this dospacket and how to formally control the use of XBSTR strings. BOOLEAN A 32-bit boolean value which is either ZERO or NON-ZERO. For implementation purposes, non-zero boolean values should be -1 this is also defined as DOSTRUE. However for compatibility reasons, performing equality comparisons with any value other than zero is absolutely forbidden, only 0 or FALSE may be used in a value comparison test. See the dos.doc file introduction paragraph for more details on this compatibility issue. RESULT1 A 32 or 64 bit primary result code as defined for the function. RESULT2 A 32 bit error code as defined in the dos/errors.h include file. Handlers should not return error codes besides those defined. For some functions a secondary result can also be returned here upon success. Summary of defined packet numbers, as of DOS library version 53.149 This is a listing of all the DOS packets defined by Commodore and other relevant authorities since. Unless otherwise noted, packets 2050-2999 and 8500-8999 are reserved for use by third party developers (see chart below). All remaining packets are reserved for future OS expansion. Decimal Action #define Status ------------------------------------------------------- 0 ACTION_NIL 0 ACTION_STARTUP SYNONYM 1 2 ACTION_GET_BLOCK OBSOLETE 3 4 ACTION_SET_MAP OBSOLETE 5 ACTION_DIE OBSOLETE 6 ACTION_EVENT OBSOLETE 7 ACTION_CURRENT_VOLUME OBSOLETE 8 ACTION_LOCATE_OBJECT 9 ACTION_RENAME_DISK 10-14 15 ACTION_FREE_LOCK 16 ACTION_DELETE_OBJECT 17 ACTION_RENAME_OBJECT 18 ACTION_MORE_CACHE DEPRECATED 19 ACTION_COPY_LOCK 19 ACTION_COPY_DIR SYNONYM 20 ACTION_WAIT_CHAR 21 ACTION_SET_PROTECT 22 ACTION_CREATE_DIR 23 ACTION_EXAMINE_OBJECT DEPRECATED 24 ACTION_EXAMINE_NEXT DEPRECATED 25 ACTION_DISK_INFO 26 ACTION_INFO 27 ACTION_FLUSH 28 ACTION_SET_COMMENT 29 ACTION_PARENT 30 ACTION_TIMER INTERNAL 31 ACTION_INHIBIT 32 ACTION_DISK_TYPE OBSOLETE 33 ACTION_DISK_CHANGE OBSOLETE 34 ACTION_SET_DATE 35-39 40 ACTION_SAME_LOCK 41-52 53 ACTION_SAME_FH 54-81 82 ACTION_READ 83-86 87 ACTION_WRITE 88-993 994 ACTION_SINGLE_CHARACTER_MODE 994 ACTION_SCREEN_MODE SYNONYM 995 ACTION_CHANGE_SIGNAL 996-1000 1001 ACTION_READ_RETURN INTERNAL 1002 ACTION_WRITE_RETURN INTERNAL 1003 ACTION_INT_WRITE_RETURN INTERNAL 1004 ACTION_FINDUPDATE (MODE_READWRITE) 1005 ACTION_FINDINPUT (MODE_OLDFILE) 1006 ACTION_FINDOUTPUT (MODE_NEWFILE) 1007 ACTION_END 1008 ACTION_SEEK DEPRECATED 1009 ACTION_ICONIFY INTERNAL 1010-1019 1020 ACTION_FORMAT 1021 ACTION_MAKE_LINK 1022 ACTION_SET_FILE_SIZE DEPRECATED 1023 ACTION_WRITE_PROTECT 1024 ACTION_READ_SOFT_LINK 1025 1026 ACTION_FH_FROM_LOCK 1027 ACTION_IS_FILESYSTEM 1028 ACTION_CHANGE_MODE 1029 1030 ACTION_COPY_DIR_FH 1031 ACTION_PARENT_FH 1032 1033 ACTION_EXAMINE_ALL DEPRECATED 1034 ACTION_EXAMINE_FH DEPRECATED 1035 ACTION_EXAMINE_ALL_END DEPRECATED 1036 ACTION_SET_OWNER DEPRECATED 1037 ACTION_SET_OWNER_INFO 1038 1039 ACTION_NEWMEMFILE INTERNAL 1040 ACTION_NEWMEMLOCK INTERNAL 1041-1997 1998 ACTION_WAIT_FOR_DATA 1999 ACTION_SET_BLOCKING_MODE 2000-2007 2008 ACTION_LOCK_RECORD OPTIONAL 2009 ACTION_FREE_RECORD OPTIONAL 2010-2049 2050-2999 3000 ACTION_SHUTDOWN 3001 ACTION_COLLECT 3002-3004 3005 ACTION_FILESYSTEM_ATTR 3006 ACTION_OBTAIN_CON_INFO 3007 ACTION_RELEASE_CON_INFO 3008-3029 3030 ACTION_EXAMINEDATA 3031 ACTION_EXAMINEDATA_FH 3032-3039 3040 ACTION_EXAMINEDATA_DIR 3041-4096 4097 ACTION_ADD_NOTIFY OPTIONAL 4098 ACTION_REMOVE_NOTIFY OPTIONAL 4099-4199 4200 ACTION_SERIALIZE_DISK 4201 ACTION_GET_DISK_FSSM DEPRECATED 4202 ACTION_FREE_DISK_FSSM DEPRECATED 4203-5322 5323 ACTION_INHIBIT_DOS_LONGPATH_HANDLING 5324-8000 8001 ACTION_CHANGE_FILE_POSITION64 8002 ACTION_GET_FILE_POSITION64 8003 ACTION_CHANGE_FILE_SIZE64 8004 ACTION_GET_FILE_SIZE64 8005-8499 8500-8999 9000- ... NAME FILESYSTEM VECTOR-PORT() CALLING: NB. The minimum DOS version for vector-port support is 53.95. Check your developer SDK:c for these tools; FSVPTool and FSTest. FSVPTool will generate a skeleton vector-port filesystem for you. The new V53 struct FileSystemVectorPort information follows. See also; include/dos/filehandler.h for structure definitions. The new filesystem vector-port calling method permits optional backward compatibility to the old style message port based dospacket interface, while allowing DOS to call the new filesystem vectors in the context of the dos.library function caller without the old dospacket overhead. The new filesystem vector-port calling method is to be implemented only by filesystems that, by convention, responds to ACTION_IS_FILESYSTEM with a TRUTH result. The implementation in a filesystems is relatively simple, a filesystem historically allocates its own dospacket message port upon filesystem process startup, the only requirement now is that the filesystem call the IDOS->AllocDosObject(DOS_FSVECTORPORT,...) function to create the new style vector-port which is basically a traditional message port with a function vector table appended. Supporting filesystems create an initialised 'struct FileSystemVector' table of function pointers which absolutely must include setting three additional fields in this structure, these are the 'Version' member to FS_VECTORPORT_VERSION and the 'StructSize' member shall be set to the sizeof(struct FileSystemVectors) and the 'End_Marker' set to -1. A pointer to this structure is then passed to the IDOS->AllocDosObject() function using the ADO_Vectors tag, it will then copy the vector table to the allocated FileSystemVectorPort structure, the ADO_Name tag should also be specified to give the port a name, this shall be the same as the device node name as used for the devicenode->dn_Name. This can be fetched from the devicenode via the ACTION_STARTUP dospacket (via dp_Arg3) that is still sent when the filesystem process is started. The IDOS->AllocDosObject() function will copy this name and also perform other validations such as setting the mgsport struct mp_Node.ln_Type to NT_FILESYSTEM. The returned struct FileSystemVectorPort pointer is then deployed the same way as a normal dospacket message port was. (See the ACTION_STARTUP autodoc for more info.) To avoid having to make large changes in the existing filesystems, the vector functions are as similar as practical to the parameters for the old dospackets, without any of the old BCPL pointer or BSTR conversion mayhem of course, the exceptions are where single dospackets were used in a somewhat convoluted manner in performing two or more functions based on some sort of flag/s, these have generally been separated into discrete functions. An example of this is the vector-port functions for ACTION_CHANGE_MODE, this is now two dedicated functions; FSChangeLockMode() and FSChangeFileMode(). It is also very important to avoid concurrency issues, because the vector-port functions will be invoked from the calling process context, all vector-port functions that modify global data (such as the filesystems internal locklist) MUST now be surrounded by at least an exclusive access semaphore, mutex or such like, while functions that only read data would use a shared access semaphore or mutex. To simplify the implementation, NULL vector-port function pointers have special meaning where the dos.library will fall back to sending the equivalent dospacket to the filesystem message port to try and obtain a response. This allows an existing dospacket orientated filesystem to implement the vector-port functions in a limited number for speed sensitive functions only, or implement functions incrementally for ease of debugging. To stop DOS from sending the fall back dospacket for truly unimplemented functions, simply provide a valid vector-port function stub that returns the values; Result1=0, Result2=ERROR_ACTION_NOT_KNOWN. VECTOR PORT FUNCTION SEMANTICS: (1) The dos.library startup methodology for filesystems remains the same as handlers, dos.library will start up a filesystem process and send an ACTION_STARTUP dospacket to the process message port initially, then wait for the reply, after this, supporting filesystems will have their vector-port functions called from this point onward, providing they are not NULL and the vector-port validates. An ACTION_SHUTDOWN dospacket may also be sent by the dos.library to shutdown the filesystem, this must be also handled by the filesystem in a method appropriate for the particular filesystem. (2) The 'result2' (secondary result) pointers will always be specified by dos.library, the filesystem may assume that these will never be NULL pointers, also, dos.library will always clear result2 to 0 just before calling the vector-port function. (3) For Vector-port calls only, all STRPTR object descriptors shall no longer contain any DOS path components whatsoever. The paths will be pre-resolved by dos.library to a single object name and a relative parent directory lock. Only the stored string returned from the FSReadSoftLink() function can contain DOS paths descriptors and the filesystem must never do anything with this itself, except store it. (4) Exclusive Directory locks have been deprecated, regardless of the requested mode. Only locks for files may be exclusive, all requests for exclusive directory locks shall be quietly changed to shared. This shall be employed for both dospacket and vector-port functions. LEGACY APPLICATIONS THAT SEND DOSPACKETS DIRECTLY TO FILESYSTEMS: Legacy applications that still send dospackets directly to the message port of the filesystem would normally break when a pure vector-port filesystem is created, to handle these situations, all filesystems are provided with a special vector-port function that the dos.library initialises when any vector-port is created by AllocDosObject(). The function vector prototype is; void DOSEmulatePacket(struct FSVP *vp, struct DosPacket *dp); A filesystem may simply pass all dospackets received from their port directly to this vector, ( except for the ACTION_SHUTDOWN dospacket which, like ACTION_STARTUP, is used for filesystem start and ending.) The dos.library will use the DosPacket information to perform an equivalent vector-port call through the supplied vector-port and dospacket arguments, then places the result back into the dospacket and return. The filesystem should reply to the dospacket as it normally would in the dospacket handling loop, which should look quite similar to this; EXAMPLE: while( ! shutdown ) { IExec->WaitPort(&VectorPort.MP); while((msg = IExec->GetMsg(&VectorPort.MP))) { if(( dp = (struct DosPacket *) msg->mn_Node.ln_Name )) { if( dp->dp_Link == msg ) /* validate for safety */ { if( ACTION_SHUTDOWN == dp->dp_Action ) { handle_action_shutdown(VectorPort,dp); shutdown = TRUE; /* don't break, must dequeue port */ } else /* Pass all other packets to the dos emulator. */ { VectorPort->FSV.DOSEmulatePacket(VectorPort,dp); } } } IExec->ReplyMsg(msg); } } The DOSEmulatePacket() vector will cause any dospackets sent by the dos.library to be responded to with 0 and ERROR_ACTION_NOT_KNOWN. Dospackets from all other senders will be converted to an equivalent vector-port function call, if the required functions are supported in the current dos.library version. If the vector-port has been invalidated, eg. from a shutdown, the dospacket return codes; res1=0 and res2=ERROR_ACTION_NOT_KNOWN, will always be returned from the DOSEmulatePacket() vector. For implementors of the handle_action_shutdown() function, writers must invalidate the vector-port to stop dos.library callers vectoring, before clearing the devicenode->dn_Port ONCE ONLY. To do this, set the version number to zero; VectorPort->FSV.Version = 0; A typical handle_action_shutdown() function should look something very much like this; EXAMPLE: static void handle_action_shutdown(struct FSVP * FSVectorPort, struct DosPacket *dp) { struct GlobalData *gd = FSVectorPort->FSV.FSPrivate; struct ObjLock *lock, *next; struct MsgPort *port; /* ** Trouble!, looks like someone tried to shut us down twice. */ if( 0 == FSVectorPort->FSV.Version ) { dp->dp_Res1 = FALSE; dp->dp_Res2 = ERROR_ACTION_NOT_KNOWN; return; } IEXEC->ObtainSemaphore(gd->Sem); /* gain exclusive access */ /* ** Invalidate the vector-port to stop any further dos.library ** callers vectoring from this point onward. */ FSVectorPort->FSV.Version = 0; /* ** Set InfoData->id_DiskType = ID_NO_DISK_PRESENT; at this point. ** If we have a volume node up, pull the disk out of service. ** The volume node will be deleted later. */ if( gd->Volume_Node ) { /* Set InfoData->id_DiskType = ID_NO_DISK_PRESENT; here */ IDOS->NonBlockingModifyDosEntry(gd->Volume_Node,NBM_REMDOSENTRY,0,0); } /* ** Clear the device nodes port, this will make the next access ** to this device from DOS, restart a new handler process. ** Clear the pointer from our global data to indicate it was ** done just the ONCE to avoid startup race conditions. */ if( gd->Device_Node ) { gd->Device_Node->dn_Port = NULL; gd->Device_Node = NULL; } /* ** Pass all the public locks/files over to the DOS lock_handler. ** It is nearly impossible for it to fail, as long as we ** get the message port for the lock_handler and the ** objects were allocated by IDOS->AllocDosObject(). ** Remember, only pointers to objects that are public ** may be passed to the DOS lockhandler. */ if(( port = IEXEC->FindPort("dos_lock_handler_port") )) { for(lock = BADDR(gd->Lock_List); lock; lock = next) { next = BADDR(lock->lock.fl_Link); if( lock->fh ) /* A public open file. */ { IDOS->DoPkt(port, ACTION_COLLECT, ID_COLLECT_FILEHANDLE, (int32)lock->fh, 0,0,0); /* free internal FS lock struct memory now */ IDOS->FreeDosObject(DOS_LOCK,lock); } else /* A public object lock */ { IDOS->DoPkt(port, ACTION_COLLECT, ID_COLLECT_LOCK, (int32)lock, 0,0,0); } } /* ** Clear the locklist, all locks are now owned ** by the DOS lock_handler, it will service them ** until they are unlocked or closed. */ gd->Lock_List = ZERO; } dp->dp_Res1 = DOSTRUE; dp->dp_Res2 = 0; /* ** Send a diskchange event so that anyone looking will notice ** that the volume has been removed. */ IDOS->NonBlockingModifyDosEntry(0, NBM_DISKREMOVED, 0,0); IEXEC->ReleaseSemaphore(gd->Sem); return; } ============================================================================ dos.library/ACTION_ADD_NOTIFY dos.library/ACTION_ADD_NOTIFY NAME ACTION_ADD_NOTIFY - FSAddNotify() (OPTIONAL - Emulated by DOS V52.28+) SYNOPSIS int32 RESULT1 = FSAddNotify(struct FileSystemVectorPort *fsvp, int32 *result2, struct NotifyRequest *nreq); FUNCTION Do not implement this action unless you are a remote filesystem or have a good reason to do so, that cannot be handled by the dos.library internal notification handler. This action asks a file system to notify the calling program if a particular object is altered. The handler will notify a program either by sending a message, calling a Hook or by signaling a task. To use this action, an application needs to allocate and initialize a NotifyRequest structure, this is done with IDOS->AllocDosObject(), the handler gets the watched object's name from the nr_FullName field. The string in nr_FullName will be an absolute path, including the name of the root volume or device (no assigns). The absolute path is necessary because the file or its parent directories do not have to exist when the notification is set up, this allows notification on files and directories that do not yet exist. Notification will not occur until the directory or file is created. An application that uses the StartNotify() DOS call does not fill in the NotifyRequest's nr_FullName field, but instead fills in the nr_Name field. StartNotify() takes the name from the nr_Name field and uses GetDeviceProc() and DevNameFromLock() to expand any assigns and storing the result in nr_FullName. The notification type depends on which bit is set in the NotifyRequest.nr_Flags field. If the NRF_SEND_MESSAGE bit is set, an application receives notification of changes to the object through a message (see NotifyMessage from dos/notify.h). In this case, the nr_Port field must point to the message port that will receive the notifying message . If the nr_Flags NRF_SEND_SIGNAL bit is set, the file system will signal a task instead of sending a message. In this case, nr_Task points to the task and nr_SignalNum is the signal number. The third method is NRF_CALL_HOOK, invoke the Hook pointed to by NotifyRequest->nr_stuff.nr_CallHook.nr_Hook; Note that this feature may not be supported by all file systems so be prepared for failure. This notification method was intended to be used with directories and does not work with files when serviced by a filesystem, however, both are supported only if dos.library V52.28+ is used to handle the notification. NB: Your hook structure MUST remain persistent for the life of the notify request. The Hook function is invoked with the following parameters: result = func(hook,reserved,msg); D0 A0 A2 A1 int32 func(struct Hook *hook, APTR reserved, struct NotifyHookMsg *msg); The 'reserved' parameter is currently used for special features within the operating system when employing dos.library handled notifications, filesystems must set this to 0. Your hook function should return 0 if successful. The NotifyHookMsg looks like this: struct NotifyHookMsg { int32 nhm_Size; int32 nhm_Action; STRPTR nhm_Name; }; The individual fields have the following meanings: nhm_Size The size of this data structure (in bytes); this must be >= 12; more fields may be added in the future and by looking at nhm_Size you can tell if the fields you are expecting are actually present. nhm_Name The name of the object. nhm_Action This can be one of the following values: NHM_ACTION_INITIAL This is the initial notification produced, as requested by setting the NRF_NOTIFY_INITIAL flag in NotifyRequest->nr_Flags. NHM_ACTION_ADD An entry by the name given in the nhm_Name field was added to the directory being monitored. NHM_ACTION_CHANGE The directory entry, whose name is given in the nhm_Name field, has changed. For example, its size or modification time may have changed. NHM_ACTION_DELETE An entry by the name given in the nhm_Name field was removed from the directory being monitoried. Note that further actions may be supported in the future. As a rule, if your hook cannot support or 'understand' the action given, then it should ignore it. Only three different actions represent changes to directory entries. For example, creating a new file will produce a message of type NHM_ACTION_ADD. Deleting a file will produce a message of type NHM_ACTION_DELETE. Changes to entries involving modification time, comments, size, protection bits and owner info will trigger NHM_ACTION_CHANGE messages. You will need to find out for yourself what exactly has changed. Only one of these three bits should be set! When an application wants to limit the number of NotifyMessages an handler can send per NotifyRequest, the application sets the NRF_WAIT_REPLY bit in the nr_Flags field. This bit tells the handler not to send new NotifyMessages to a NotifyRequest's message port if the application has not returned a previous NotifyMessage. This pertains only to a specific NotifyRequest, if other NotifyRequests exist on the same file (or directory) the handler will still send NotifyMessages to the other NotifyRequest's message ports. The NRF_WAIT_REPLY bit only applies to message notification. Handlers should only perform a notification when the actual contents of the file have changed or its associated meta-data. This includes ACTION_WRITE, ACTION_SET_xxxx, ACTION_DELETE, ACTION_RENAME_OBJECT, ACTION_FINDUPDATE (MODE_READWRITE - create), ACTION_FINDOUTPUT (MODE_NEWFILE). For file write (change) and create notifications, these are sent in the ACTION_END function. ( ie; Close() ) It should also include a change notification for all other meta-data modification actions such as the ACTION_SET_COMMENT/PROTECT/DATE/OWNER function, but this was not generally supported by filesystems. The built-in dos.library notification handler does support this. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. nreq - (struct NotifyRequest *) Pointer to the notify request. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS - (DosPacket method) dp_Type - (int32) ACTION_ADD_NOTIFY dp_Arg1 - (struct NotifyRequest *) NotifyRequest structure pointer. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. SEE ALSO IDOS->StartNotify() dos.library/ACTION_CHANGE_FILE_POSITION64 dos.library/ACTION_CHANGE_FILE_POSITION64 NAME ACTION_CHANGE_FILE_POSITION64 (DosPacket64) - FSChangeFilePosition() SYNOPSIS int32 RESULT1 = FSChangeFilePosition(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, int32 mode, int64 pos); FUNCTION ChangeFilePosition() sets the read/write cursor for the file to the position 'pos'. This position is used by both Read() and Write() as a place to start reading or writing. 'mode' can be OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END. It is used to specify the relative start position. For example, 20 from current is a position 20 bytes forward from current, -20 is 20 bytes back from current. Attempting to change the file position beyond the ends of a file must cause failure with a secondary result of ERROR_SEEK_ERROR. On any failure, the original file position shall remain valid. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. mode - (int32) OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END. pos - (int64) Position relative to mode. RESULT1 - (int32) Boolean, success/failure, FALSE on failure. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket64 method) dp_Type - (int32) ACTION_CHANGE_FILE_POSITION64 dp_Arg1 - (APTR) filehandle->fh_Arg1 dp_Arg2 - (int64) position. dp_Arg3 - (int32) mode dp_Arg4 - (struct FileHandle *) filehandle RESULT1 - (int64) 64 bit success/failure (-1LL or 0LL) 0LL on failure. RESULT2 - (int32) Failure code if RESULT1 == 0LL SEE ALSO IDOS->ChangeFilePosition() dos.library/ACTION_CHANGE_FILE_SIZE64 dos.library/ACTION_CHANGE_FILE_SIZE64 NAME ACTION_CHANGE_FILE_SIZE64 (NB: DosPacket64) - FSChangeFileSize() SYNOPSIS int32 RESULT1 = FSChangeFileSize(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, int32 mode, int64 size); FUNCTION Changes the file size, truncating or extending as needed. If the file is extended, the values for the new bytes should always be either zeroed or scrambled for security reasons, this area should never contain residual readable block data from some previous usage. This function shall return a failure code if the required new size cannot be achieved. If the file in question could not be changed successfully, the file must be left exactly as it was before. If the new size would be before the filehandle's current cursor position, the filehandle's cursor position shall be adjusted to point at the new end-of-file, otherwise the file cursor position shall not be changed. WARNING Filesystems shall not allow the size of a file to be changed if there is more than the one filehandle open on the same file and the size change would result in any of the other file position pointers being left pointing past the new end-of-file, the error code; ERROR_OBJECT_IN_USE shall be used to indicate the failure type for this situation. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. mode - (int32) OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END. size - (int64) Size relative to mode. RESULT1 - (int32) Boolean, success/failure, FALSE on failure. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket64 method) dp_Type - (int32) ACTION_CHANGE_FILE_SIZE64 dp_Arg1 - (APTR) filehandle->fh_Arg1 dp_Arg2 - (int64) size dp_Arg3 - (int32) mode dp_Arg4 - (struct FileHandle *) filehandle RESULT1 - (int64) 64 bit success/failure (-1LL or 0LL) 0LL on failure. RESULT2 - (int32) Failure code if RESULT1 == 0LL SEE ALSO IDOS->ChangeFileSize() dos.library/ACTION_CHANGE_MODE dos.library/ACTION_CHANGE_MODE NAME ACTION_CHANGE_MODE - FSChangeLockMode() - FSChangeFileMode() SYNOPSIS int32 RESULT1 = FSChangeLockMode(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *lock, int32 newmode); int32 RESULT1 = FSChangeFileMode(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, int32 newmode); FUNCTION This action requests that the handler change the mode of the given file handle or file lock to the new mode specified. This request should fail if the handler can't change the mode as requested, for example an exclusive request for a file that has multiple users already. Attempting to change a directory lock to an exclusive lock MUST cause failure from V53 onwards. This is NOT optional, if you fail to implement only the shared directory lock mode, then the dos.library vector-port and path handling code will not work properly. If an objects mode is already the same as being requested, a success code should be returned even if no actual operation was performed. INPUTS (FileSystemVectorPort method) - FSChangeLockMode() fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. lock - (struct Lock *) Pointer to the struct lock. newmode - (int32) New mode for object; SHARED_LOCK or EXCLUSIVE_LOCK RESULT1 - (int32) Success / Failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (FileSystemVectorPort method) - FSChangeFileMode() fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the file handle. newmode - (int32) New mode for file; SHARED_LOCK or EXCLUSIVE_LOCK RESULT1 - (int32) Success / Failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket method) dp_Type - (int32) ACTION_CHANGE_MODE dp_Arg1 - (int32) object_type_id; CHANGE_FH or CHANGE_LOCK. dp_Arg2 - (BPTR) filehandle or lock as identified by dp_Arg1. dp_Arg3 - (int32) Newmode of object; SHARED_LOCK or EXCLUSIVE_LOCK. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->ChangeMode() dos.library/ACTION_CHANGE_SIGNAL dos.library/ACTION_CHANGE_SIGNAL NAME ACTION_CHANGE_SIGNAL FUNCTION This packet redirects what process the console handler signals when the user hits Control-C, Control-D, Control-E, or Control-F. Normally the process that opened the file handle receives the break signal. INPUTS dp_Type - (int32) ACTION_CHANGE_SIGNAL dp_Arg1 - (APTR) filehandle->fh_Arg1 of the console file handle. dp_Arg2 - (struct MsgPort *)MsgPort of the process to signal. dp_Arg3 - (struct FileHandle *)filehandle.(added 53.49, previously 0) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->SystemTags() dos.library/ACTION_COLLECT dos.library/ACTION_COLLECT NAME ACTION_COLLECT FUNCTION This is a sub-packet used in conjunction with ACTION_SHUTDOWN Refer to ACTION_SHUTDOWN for extended documentation. Currently, the only way this packet can fail is if you pass an object that was not allocated by the IDOS->AllocDosObject() function, or if there is insufficient memory for one (struct Node) allocation. From dos.library 53.69 there are now (empty) nodes pre-allocated upon system start up. There are three objects recognised here, dp_Arg1 indicates which of these are passed in dp_Arg2; ID_COLLECT_LOCK, ID_COLLECT_FILEHANDLE or ID_COLLECT_NOTIFICATION. The object passed to the lock handler for servicing MUST be the same public structure addresss known to the application which requested its creation. Internal filesystem locks should never be passed to this handler, as no-one will ever try to unlock them. INPUTS (DosPacket method) dp_Type - (int32) ACTION_COLLECT dp_Arg1 - (int32) ID_COLLECT_xxxx (as above) dp_Arg2 - (APTR) object. RESULT1 - (int32) Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->DisMountDevice(), ACTION_SHUTDOWN dos.library/ACTION_COPY_LOCK dos.library/ACTION_COPY_LOCK NAME ACTION_COPY_LOCK - FSDupLock() SYNOPSIS struct Lock *RESULT1 = FSDupLock(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *lock); FUNCTION This actions original name (ACTION_COPY_DIR) was misleading as it does not manipulate directories, instead, it creates a copy of a shared lock. ACTION_COPY_LOCK should always be used now. The copy is subsequently freed with an ACTION_FREE_LOCK. Only valid (non zero) locks are passed on to the filesystem. This function will always fail with RESULT2 = ERROR_OBJECT_IN_USE when attempting to create a duplicate lock on an already exclusively locked object. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. lock - (struct Lock *) Pointer to the lock to duplicate. RESULT1 - (struct Lock *) Duplicate lock, NULL on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO. INPUTS (DosPacket method) dp_Type - (int32) ACTION_COPY_LOCK dp_Arg1 - (BPTR) lock. RESULT1 - (BPTR) Duplicated lock, ZERO on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO SEE ALSO IDOS->DupLock() dos.library/ACTION_COPY_LOCK_FH dos.library/ACTION_COPY_LOCK_FH NAME ACTION_COPY_LOCK_FH - FSDupLockFromFH() SYNOPSIS struct Lock *RESULT1 = FSDupLockFromFH(struct FileSystemVectorPort *vp, int32 *result2, struct FileHandle *file); FUNCTION This actions original name (ACTION_COPY_DIR_FH) was misleading as it does not actually manipulate directories, instead, it creates a shared lock on an open file. ACTION_COPY_LOCK_FH should only be used now. This function requests that the handler return a lock associated with the currently opened file handle. The request may fail for any restriction imposed by the file system (for example when the file handle is not opened in a shared mode). The file handle is still usable after this call, unlike the lock that is consumed with ACTION_FH_FROM_LOCK / FSOpenFromLock(). The RESULT1 lock remains valid even after the file is closed. INPUTS (FileSystemVectorPort method) vp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. RESULT1 - (struct Lock *) Lock associated with file handle, 0 on error. RESULT2 - (int32) Failure code if RESULT1 == NULL. INPUTS (DosPacket method) dp_Type - (int32) ACTION_COPY_LOCK_FH. dp_Arg1 - (APTR) filehandle->fh_Arg1. dp_Arg2 - (struct FileHandle *)filehandle. (added 53.49, previously 0) RESULT1 - (BPTR) Lock associated with file handle or ZERO on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO SEE ALSO IDOS->DupLockFromFH() dos.library/ACTION_CREATE_DIR dos.library/ACTION_CREATE_DIR NAME ACTION_CREATE_DIR - FSCreateDir() SYNOPSIS struct Lock *RESULT1 = FSCreateDir(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name); FUNCTION ACTION_CREATE_DIR creates a new directory with the specified name. An error is returned if it fails. Directories can only be created on devices which support them, e.g. disks. Before V53, ACTION_CREATE_DIR returned an exclusive lock on the new directory if it succeeded, from V53+ it is now required that this be a shared lock, this is NOT optional, if you fail to implement only a shared directory lock mode, then the dos.library vector-port and long path handling will simply not work in all circumstances. The 'name' refers to the object, which may include a path component for DosPacket callers only, vector-port calls will have only the final directory name and never any path component. Creating a directory must fail with the error code; ERROR_OBJECT_EXISTS if the 'name' was already in use by any filesystem object. If the disk itself is write protected, return failure along with the error code; ERROR_DISK_WRITE_PROTECTED. The new directory shall also inherit the parents protection mask, as well as the group and owner values, and comments shall always default to a nul-string. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' relative lock. name - (CONST_STRPTR) Pointer to the dir name.(no path component) RESULT1 - (struct Lock *) Lock - (NULL on failure.) RESULT2 - (int32) Failure code if RESULT1 == NULL INPUTS (DosPacket method) dp_Type - (int32) ACTION_CREATE_DIR dp_Arg1 - (BPTR) relative directory lock. dp_Arg2 - (BSTR) Name of new directory. (may also include path) dp_Arg3 - 0 dp_Arg4 - 0 dp_Arg5 - (BSTR) nametype - name format indicator value. if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (BPTR) Lock - (ZERO on failure.) RESULT2 - (int32) Failure code if RESULT1 == ZERO NOTES From V53 onwards, all DosPacket callers (using ACTION_CREATE_DIR) will have the result lock mode changed by dos.library to a shared lock upon success, vector port callers will be unaffected. SEE ALSO IDOS->CreateDir(), IDOS->CreateDirTree(), dos.library/ACTION_CURRENT_VOLUME dos.library/ACTION_CURRENT_VOLUME NAME ACTION_CURRENT_VOLUME (OBSOLETE) FUNCTION This action is obsolete and was generally used by AmigaDOS to provide the volume line for a requester. V53+ dos.library no longer uses this and previous versions queried the doslist if it failed. This action returns a pointer to the volume node (from the DOS device list) associated with the file system. As the volume node may be removed from the device list when the file system mounts a different volume (such as when directed to by an ACTION_INHIBIT) there is no guarantee that this pointer will remain valid for any amount of time. As long as the filehandle remains open, the result volume node pointer remains valid. dp_Arg1 is only required by the filesystems that support removable media. Some programs require that the current volume be returned even when dp_Arg1 is NULL. INPUTS dp_Type = (int32) ACTION_CURRENT_VOLUME dp_Arg1 = (APTR) filehandle->fh_Arg1 or NULL dp_Arg2 = (struct FileHandle *) filehandle (added 53.49, previously 0) RESULT1 (BPTR) BCPL pointer to a struct DosList volume node, ZERO for error. RESULT2 (int32) Failure code if RESULT1==ZERO, otherwise the Exec unit number will be returned here on success. SEE ALSO IDOS->ErrorReport(); dos.library/ACTION_DELETE_OBJECT dos.library/ACTION_DELETE_OBJECT NAME ACTION_DELETE_OBJECT - FSDelete() SYNOPSIS int32 RESULT1 = FSDelete(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name); FUNCTION This function deletes the file, directory or symbolic link specified if there are currently no active locks in force and the protection status bits allow it. If there are existing locks being held on the object to be deleted, return failure along with the error code; ERROR_OBJECT_IN_USE. Note that all the objects within a directory must be deleted before the directory itself can be deleted, if the directory is not empty, return failure along with the error code; ERROR_DIRECTORY_NOT_EMPTY. If any object has the protection bit EXDF_NO_DELETE set, return failure along with the error code; ERROR_DELETE_PROTECTED. If the object is a file and the protection bit EXDF_NO_WRITE is set, return failure along with the error code; ERROR_WRITE_PROTECTED. If the disk itself is write protected, return failure along with the error code; ERROR_DISK_WRITE_PROTECTED. The 'name' refers to the object, which may include a path component for DosPacket callers only, vector-port callers will have only the object name and never any path component. The 'rel' is a relative lock from which to look for the 'name' object. Use the example code shown in ACTION_LOCATE_OBJECT / FSLock() autodoc to handle the relative argument parameters in all situations. Failure (FALSE) is returned if the deletion fails, DOSTRUE upon success. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' reference lock. name - (CONST_STRPTR) Pointer to the object name.(no path component) RESULT1 - (int32) Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_DELETE_OBJECT dp_Arg1 - (BPTR) relative lock. dp_Arg2 - (BSTR) name. (may also include a path component) dp_Arg3 - 0 dp_Arg4 - 0 dp_Arg5 - (BSTR) nameformat - name format indicator value, only if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be a nul-terminated string. (53.23) RESULT1 - (int32) Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->Delete(), ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_DIE dos.library/ACTION_DIE NAME ACTION_DIE (OBSOLETE - use ACTION_SHUTDOWN for new handlers) FUNCTION In earlier documentation this dospacket it did not provide enough information or support on how to allow a handler to quit without requiring the handler process and resources to remain lurking forever. As this dospacket is likely to be already implemented in various and inconsistent ways with some handlers, it must now to be treated as an obsolete dospacket. INPUTS dp_Type - (int32) ACTION_DIE dp_Arg1 - 0 RESULT1 - (int32) Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->DisMountDevice(), ACTION_SHUTDOWN dos.library/ACTION_DISK_INFO dos.library/ACTION_DISK_INFO NAME ACTION_DISK_INFO - FSDeviceInfoData() SYNOPSIS int32 RESULT1 = FSDeviceInfoData(struct FileSystemVectorPort *fsvp, int32 *result2, struct InfoData *infodat); FUNCTION The ACTION_DISK_INFO is used to get information about the device and status of the handler. It fills in an InfoData structure about the device the file system currently controls. This packet has a special meaning for console style handlers. When presented with this packet, a console style handler will return an InfoData structure where some fields have special meaning and are documented here. The InfoData structure will always be longword aligned for dospacket calls due to the BPTR conversions required. For a vector-port calls, this is not mandated, so default alignment is satisfactory. Unlike FSVolumeInfo()/ACTION_INFO, this function does not depend on the state of a volume or depend on whether removable media is inserted, the only thing required is that the handler process is running. The contents of the InfoData structure are arranged as follows: id_NumSoftErrors ( -- Deprecated field ) Typically was for the number of media read/write errors encountered on this volume. This number increased for every error, regardless of which disk may be currently inserted, which means it's of little use for anything at all. Few file systems ever provided this information, it is generally always set to zero. This field will likely be reused in future for some other purpose, until then, please leave it set to zero. id_UnitNumber ( -- Deprecated field ) This can be the low level device driver unit number responsible for this disk drive, it also may not be. Few file systems ever provided this information, and the operating system itself no longer uses it as of AmigaOS 2.04 and beyond. This field is generally set to zero and will most likely be reused in future for some other purpose, until then, please leave it set to zero. id_DiskState This is one of the following: ID_DISKSTATE_WRITE_PROTECTED Medium is readable, but cannot be written to. ID_DISKSTATE_VALIDATED Medium is readable and writable. ID_DISKSTATE_VALIDATING Medium may be readable and is currently being prepared to make it writable again. This is also the default "parking" state used when the filesystem is waiting for media to be inserted, or the file system is in an unknown state and unable return meaningfull information about the medium, Always refer to id_DiskType for device state info. id_NumBlocks The number of storage units ("blocks") which this file system consists of. NOTE: This value can be zero! id_NumBlocksUsed The number of storage units currently in use by the file system. NOTE: This value can be zero or identical to the id_NumBlocks value! id_BytesPerBlock The number of bytes that make up a single storage unit ("block"). Note that this number may not match the physical size of the storage block, as used by the underlying storage device. The file system might return the size of a single data block instead, which can be shorter. id_DiskType This field indicates both the state of the file system and what kind of file system is involved. The following values indicate file system state: ID_NO_DISK_PRESENT No medium is currently present. ID_UNREADABLE_DISK A medium is present, but low level read errors have prevented the file system from figuring out what is stored on it. This medium may not be formatted or simply defective. ID_NOT_REALLY_DOS A medium is present, its contents are readable, but they are of no use for this file system. ID_BUSY The file system is currently "offline" and cannot access the medium. This may be because commands such as "Format" or "DiskCopy" are accessing the low level disk data and do not want the file system to interfere. The following values indicate what type of file system is involved: ID_DOS_DISK ID_FFS_DISK ID_INTER_DOS_DISK ID_INTER_FFS_DISK ID_FASTDIR_DOS_DISK ID_FASTDIR_FFS_DISK ID_LONGNAME_DOS_DISK ID_LONGNAME_FFS_DISK ID_MSDOS_DISK ID_VP255_DOS_DISK Each of these values stands for a particular type of file system and disk data format. The con-handler may return one of the following types, which indicate the state it currently operates in: ID_CON Input is line-buffered, i.e. you have to hit the [Return] key to transfer your input to the client reading data from this console stream. ID_RAWCON Input is unbuffered, i.e. each key you hit that produces a character immediately transfers input to the client software. This is the so-called 'single character' mode which can be enabled via IDOS->SetMode(..,DOSTRUE). Last, but not least, you might very rarely encounter a so-called "Kickstart" disk which contains the operating system for the Amiga 1000 and Amiga 3000 computers. It is identified by the following value: ID_KICKSTART_DISK Other disk type values may exist, which represent the file system signature stored on the disk (often in the first sector) or might just be random data found on an unformatted storage medium. Be prepared to handle this: always check the id_DiskState field to verify if the file system considers itself responsible for this disk. Do not make decisions based solely on the file system type found in the id_DiskType field! A file system should never report an id_DiskState value of ID_DISKSTATE_VALIDATED for a medium it cannot use. id_VolumeNode This field is supposed to be a BCPL pointer to the volume node of the currently active filesystem volume. Not all file systems will supply this, or exactly this particular information. Non filesystems may use this field for other completely incompatible purposes, for example, the con-handler may return a pointer to the console window. This field should be treated with caution. Note that it can also be ZERO! id_InUse This field is supposed to be set to FALSE/ZERO if there are currently no locks or files bound to the handler. Otherwise, the non-zero value returned from some old file systems may infact be any arbitrary non-zero boolean value. The now prefered V50+ use for filesystems is that they should actually return an integer for the number of locks currently in force. Stream handlers should indicate the number of streams currently open. The con-handler also uses this field for a completely different and incompatible purpose, such as storing a pointer to the console I/O request. As with id_VolumeNode this field should be treated with caution. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. infodat - (struct InfoData *) Pointer to the InfoData structure. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_DISK_INFO dp_Arg1 - (BPTR) InfoData structure. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->GetDiskInfo() dos.library/ACTION_END dos.library/ACTION_END NAME ACTION_END - FSClose() SYNOPSIS int32 RESULT1 = FSClose(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file); FUNCTION This action closes an open file handle. This function generally returns a DOSTRUE as there is little the application can do to recover from a file closing failure. However, if something does actually go wrong while releasing a file, it is recommended that FALSE be returned to indicate this, even if it is rather unlikely anybody is actually listening. This function is generally used to initiate the clearing of the Archive bit for changed objects, the archive bit of the parent directory shall always be cleared as well. This should propagate all the way back to the root directory so directories with changed objects can be identified by backup software. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to an open file. RESULT1 - (int32) BOOLEAN success. Returns FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO. INPUTS (DosPacket method) dp_Type - (int32) ACTION_END dp_Arg1 - (APTR) fh_Arg1 field of the opened struct FileHandle. dp_Arg2 - (APTR) struct FileHandle pointer (added 53.24, previously 0) RESULT1 - (int32) BOOLEAN success. Returns FALSE if Close() failed. RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES In the event a volume becomes write protected before a file is closed and the file has cached writes pending, the current methodology is to allow the cache flush to occur before the file is actually closed. BUGS If an error is returned under 2.0, DOS will not deallocate the file handle. Under 1.3, it does not check the result at all. SEE ALSO IDOS->Close() dos.library/ACTION_EXAMINE_ALL dos.library/ACTION_EXAMINE_ALL NAME ACTION_EXAMINE_ALL (DEPRECATED) FUNCTION This packet is deprecated. Do not implement this packet when ACTION_EXAMINEDATA_DIR is supported by the handler, because dos.library V53+ will emulate this function. Note that handlers may still be probed by this old packet but should always return RESULT1=FALSE, and RESULT2=ERROR_ACTION_NOT_KNOWN so the dos.library emulation code will take over. This action allows an application to obtain information on multiple directory entries. It is particularly useful for applications that need to obtain information on a large number of files and directories. This action fills the buffer (dp_Arg2) with partial or whole ExAllData structures. The size of the ExAllData structure depends on the type of request. If the request type field (dp_Arg4) is set to ED_NAME, only the ed_Name field is filled in. Instead of copying the unused fields of the ExAllData structure into the buffer, ACTION_EXAMINE_ALL truncates the unused fields. This effect is cumulative, so requests to fill in other fields in the ExAllData structure causes all fields that appear in the structure before the requested field will be filled in as well. Like the ED_NAME case mentioned above, any field that appears after the requested field will be truncated (see the ExAllData structure below). For example, if the request field is set to ED_COMMENT, ACTION_EXAMINE_ALL fills in all the fields of the ExAllData structure, because the ed_Comment field is last. This is the only case where the packet returns entire ExAllData struct. struct ExAllData { struct ExAllData *ed_Next; UBYTE *ed_Name; LONG ed_Type; ULONG ed_Size; ULONG ed_Prot; ULONG ed_Days; ULONG ed_Mins; ULONG ed_Ticks; UBYTE *ed_Comment; // Strings will be after last used field. // Note: Bug in V37 FFS treats this as a BSTR. Each ExAllData structure entry has an ead_Next field which points to the next ExAllData structure. Using these links, a program can easily chain through the ExAllData structures without having to worry about how large the structure is. Do not examine the fields beyond those requested as they certainly will not be initialized (and will probably overlay the next entry). The most important part of this action is the ExAllControl structure. It must be allocated and freed through AllocDosObject()/FreeDosObject(). This allows the structure to grow if necessary with future revisions of the operating and file systems. Currently, ExAllControl contains four fields: Entries - This field is maintained by the file system and indicates the actual number of entries present in the buffer after the action is complete. Note that a value of zero is possible here as no entries may match the match string. LastKey - This field must be initialized to 0 by the calling application before using this packet for the first time. This field is maintained by the file system as a state indicator of the current place in the list of entries to be examined. The file system may test this field to determine if this is the first or a subsequent call to this action. MatchString - This field points to a pattern matching string parsed by ParsePattern() or ParsePatternNoCase(). The string controls which directory entries are returned. If this field is NULL, then all entries are returned. Otherwise, this string is used to pattern match the names of all directory entries before putting them into the buffer. The default AmigaDOS pattern match routine is used unless MatchFunc is not NULL (see below). Note that it is not acceptable for the application to change this field between subsequent calls to this action for the same directory. MatchFunc - This field contains a pointer to an alternate pattern matching routine to validate entries. If it is NULL then the standard AmigaDOS wild card routines will be used. Otherwise, MatchFunc points to a hook function that is called in the following manner: BOOL = MatchFunc(hookptr, data,typeptr) A0 A1 A2 hookptr - Pointer to hook being called. data - Pointer to (partially) filled in ExAllData for item being checked. typeptr - Pointer to longword indicating the type of the ExAll request. This function is expected to return DOSTRUE if the entry is accepted and FALSE if it is to be discarded. INPUTS dp_Type - (int32) ACTION_EXAMINE_ALL dp_Arg1 - (BPTR) Lock on directory to examine. dp_Arg2 - (APTR) Buffer to store results. dp_Arg3 - (int32) Length (in bytes) of buffer (dp_Arg2) dp_Arg4 - (int32) Type of request - one of the following: ED_NAME Return only file names. ED_TYPE Return above plus file type. ED_SIZE Return above plus file size. ED_PROTECTION Return above plus protection mask. ED_DATE Return above plus 3 longwords of date. ED_COMMENT Return above plus comment or NULL. dp_Arg5 - (BPTR) Control structure to store state information. The control structure must be allocated with the function IDOS->AllocDosObject(). RESULT1 - (int32) Continuation flag - FALSE indicates termination. RESULT2 - (int32) Failure code if RESULT1 == FALSE From V53.59 DOS will emulate ACTION_EXAMINE_ALL by using the newer ACTION_EXAMINEDATA_DIR packet (or the vector-port call) in the fallback code if the handler reports that it does not support this old packet. SEE ALSO IDOS->ExAll(), IDOS->ExAllEnd() dos.library/ACTION_EXAMINE_FH dos.library/ACTION_EXAMINE_FH NAME ACTION_EXAMINE_FH (DEPRECATED) FUNCTION This packet is deprecated. Do not implement this packet when ACTION_EXAMINEDATA_FH is supported by the handler, because dos.library V53+ will emulate this function. Note that handlers may still be probed by this old packet but should always return RESULT1=FALSE, and RESULT2=ERROR_ACTION_NOT_KNOWN so the dos.library emulation code will take over. This function examines a file handle and fills in the FileInfoBlock (found in dp_Arg2) with information about the current state of the file. This routine is analogous to the ACTION_EXAMINE_OBJECT action for locks. Because it is not always possible to provide an accurate file size (for example when buffers have not been flushed or two processes are writing to a file), the fib_Size field (see dos/dos.h) may be inaccurate. The fib_Comment and fib_FileName strings MUST always be returned by the filesystem in BCPL string format. (1st byte is the length) Another quirk of this packet is that both the fib_Obsolete and the fib_DirEntryType fields must be set to the same value, as some programs look at one field while other programs look at the other, (due to a similar named field back in pre-V50 days). INPUTS dp_Type - (int32) ACTION_EXAMINE_FH dp_Arg1 - (APTR) filehandle->fh_Arg1 dp_Arg2 - (BPTR) fileinfoblock dp_Arg3 - (struct FileHandle *) filehandle (added 53.49, previously 0) RESULT1 - (int32) DOSTRUE/FALSE Success/failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->ExamineFH(); dos.library/ACTION_EXAMINE_NEXT dos.library/ACTION_EXAMINE_NEXT NAME ACTION_EXAMINE_NEXT (DEPRECATED) FUNCTION This packet is deprecated. Do not implement this packet when ACTION_EXAMINEDATA_DIR is supported by the handler, because dos.library V53+ will emulate this function. Note that handlers may still be probed by this old packet but should always return RESULT1=FALSE, and RESULT2=ERROR_ACTION_NOT_KNOWN so the dos.library emulation code will take over. The ExNext() function uses this packet to obtain information on all the objects in a directory. ACTION_EXAMINE fills in a FileInfoBlock structure describing the first file or directory stored in the directory referred to in the lock in dp_Arg1. ACTION_EXAMINE_NEXT is used to find out about the rest of the files and directories stored in the dp_Arg1 directory. dp_Arg2 holds a pointer to a valid FileInfoBlock field that was filled in by either an ACTION_EXAMINE or a previous ACTION_EXAMINE_NEXT call. It uses this structure to find the next entry in the directory. This packets writes over the old FileInfoBlock with information on the next file or directory in the dp_Arg2 directory. ACTION_EXAMINE_NEXT returns a failure code of ERROR_NO_MORE_ENTRIES when there are no more files or directories left to be examined. Unfortunately, like ACTION_EXAMINE, this packet has its own set of peculiarities. Among the quirks that ACTION_EXAMINE_NEXT must account for were: * The situation where an application calls ACTION_EXAMINE_NEXT one or more times and then stops invoking it before encountering the end of the directory. * The (now illegal) situation where a FileInfoBlock passed to ACTION_EXAMINE_NEXT was not the same one passed to ACTION_EXAMINE or even a previous EXAMINE_NEXT operation. Instead, it was a copy of the FileInfoBlock with only the fib_DiskKey and an arbitrary first 30 bytes of the fib_FileName copied over. This abuse is now quite illegal and will just not work anymore, so code must be written in a manner that mandates the same FIB is always supplied between calls and cause failure when not. * Because a handler can receive other dospacket types between the ACTION_EXAMINE_NEXT operations, the ACTION_EXAMINE_NEXT function must handle any special cases that may result, such as having the next entry deleted or renamed or moved just before being encountered. * The lock passed to ACTION_EXAMINE_NEXT is not always the same lock used in previous operations. It is however a lock on the same object. * The fib_Comment and fib_FileName strings MUST always be returned by the filesystem in BCPL string format. (1st byte is the length) * The fib_Obsolete and the fib_DirEntryType fields must be set to the same value, as some programs look at one field while other programs look at the other, due to a similar previously named field. Because of these problems, ACTION_EXAMINE_NEXT was probably the trickiest action to write in any handler. Failure to handle any of the above cases could be quite disastrous. INPUTS dp_Type - (int32) ACTION_EXAMINE_NEXT dp_Arg1 - (BPTR) Lock on directory being examined. dp_Arg2 - (BPTR) FileInfoBlock to fill in. RESULT1 - (int32) DOSTRUE/FALSE Success/failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->ExNext(); dos.library/ACTION_EXAMINE_OBJECT dos.library/ACTION_EXAMINE_OBJECT NAME ACTION_EXAMINE_OBJECT (DEPRECATED) FUNCTION This packet is deprecated. Do not implement this packet when ACTION_EXAMINEDATA is supported by the handler, because dos.library V53+ will emulate this function. Note that handlers may still be probed by this old packet but should always return RESULT1=FALSE, and RESULT2=ERROR_ACTION_NOT_KNOWN so the dos.library emulation code will take over. This action fills in the obsolete FileInfoBlock structure with information about the locked object. The DOS Examine() function uses this packet. This packet is actually used for two different types of operations. It is called to obtain information about a given object while in other cases, it is called to prepare for a sequence of EXAMINE_NEXT operations in order to traverse a directory. This seemingly simple operation is not without its quirks. One in particular is the FileInfoBlock->fib_Comment field. This field used to be 116 bytes long, but was changed to 80 bytes in release 1.2. The extra 36 bytes lie in the fib_Reserved field and owner fields. The fib_Comment and fib_FileName strings MUST always be returned by the filesystem in BCPL string format. (1st byte is the length) Another quirk of this packet is that both the fib_Obsolete and the fib_DirEntryType fields must be set to the same value, as some programs look at one field while other programs look at the other, due to a similar previously named field. Packet implementations should also accept a zero lock to examine the root directory of the volume. File systems must use the same values for fib_DirEntryType as the ROM file system and ram-handler do. These are as follows: ST_ROOT 1 ST_USERDIR 2 ST_SOFTLINK 3 ST_LINKDIR 4 ST_FILE -3 ST_LINKFILE -4 Note that for directories, handlers must use numbers greater than 0, since some programs test to see if fib_DirEntryType is greater than 0, ignoring the case where fib_DirEntryType equals 0. Handlers must avoid using 0 because it is not interpreted consistently. Also, ST_SOFTLINK shows as a directory unless checked explicitly. INPUTS dp_Type - (int32) ACTION_EXAMINE_OBJECT dp_Arg1 - (BPTR) Lock on object to be examined. dp_Arg2 - (BPTR) FileInfoBlock to fill in. RESULT1 - (int32) DOSTRUE/FALSE Success/failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->Examine(); dos.library/ACTION_EXAMINEDATA dos.library/ACTION_EXAMINEDATA NAME ACTION_EXAMINEDATA - FSExamineLock() SYNOPSIS struct ExamineData *RESULT1 = FSExamineLock( struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *lock); FUNCTION Examines a single filesystem object identified by the lock. Returns current data in the form of a struct ExamineData. The ExamineData block will be allocated by the filesystem by calling the AllocDosObject() function using the appropriate buffer sizes (###) as follows; data = IDOS->AllocDosObjectTags(DOS_EXAMINEDATA, ADO_ExamineData_NameSize, ###, ADO_ExamineData_CommentSize, ###, TAG_END); The filesystem will fill in the data structure members with current information for the object. This call may also cause the filesystem to flush any pending write buffers first, to get accurate information. If successfull, the returned data is used by the caller as needed, the caller must eventually release the ExamineData block by using the FreeDosObject() function; IDOS->FreeDosObject(DOS_EXAMINEDATA,data). The returned data structure looks like this; struct ExamineData { struct MinNode EXDnode; /* List node. */ uint32 EXDinfo; /* General purpose user data. */ /* */ /* These are private members exclusively for the FS & DOS. */ uint32 FSPrivate; /* FILESYSTEM ONLY - Private usage. */ uint32 Reserved0; /* DOS RESERVED - Private usage. */ APTR DOSPrivate; /* DOSLIB ONLY - Private usage. */ /* */ /* The following are public fields. */ uint32 StructSize; /* (RO) Full size of the structure. */ uint32 Type; /* The entry descriptor value. */ int64 FileSize; /* Size if a file or -1LL if not. */ struct DateStamp Date; /* Days, Mins, Ticks. */ uint32 RefCount; /* Object hardlink count. [Note 1] */ uint64 ObjectID; /* Unique object identifier. [Note 2] */ STRPTR Name; /* (RO) Nul-terminated object name. */ uint32 NameSize; /* (RO) Allocated name buffer size. */ STRPTR Comment; /* (RO) Nul-terminated comment. */ uint32 CommentSize; /* (RO) Allocated comment buffer size.*/ STRPTR Link; /* (RO) -- Unused by FSExamineLock(). */ uint32 LinkSize; /* (RO) -- Unused by FSExamineLock(). */ uint32 Protection; /* Protection status bitmask. */ uint32 OwnerUID; /* Owner info. [Note 3] */ uint32 OwnerGID; /* Group info. [Note 3] */ uint32 Reserved2; /* DOS reserved field. */ uint32 Reserved3; /* DOS reserved field. */ uint32 Reserved4; /* DOS reserved field. */ }; (RO) = Read Only, these fields must not be modified by the application. See structure definition in include/dos/dos.h for detailed information. [Note 1] If possible, this field should be supported by filesystems that support hardlinks, it is used to indicate the hardlink reference count for objects. A value of one indicates that the object has no additional references other than itself, a value of two will indicate that it has one additional hardlink reference, a value of three means it has two hardlink references, etc... All hardlinks themselves always show a value of 1 in this field when supported, otherwise this field MUST be set to zero for all objects, if the filesystem does not support it. It will be undefined if the caller fails to specify the EXF_REFCOUNT bit in the EX_DataFields mask. [Note 2] This field is the mandatory unique object identfier for all objects on this volume, the value used here may be any arbitrary value as long as it is unique from all other objects on this volume, it may use the object node address, the disk header block number or other such values. (Note: this field is 64 bits wide.) This field will be undefined if the caller fails to specify the EXF_OBJECTID bit in the EX_DataFields mask. [Note 3] Historically, these fields only used the low 16 bits. For extensibility, the size of these are now 32 bit fields. However, for interoperability, it is recommended that values greater than 65535 be avoided where possible so reading only the low 16 bits results in the same value for legacy applications. These fields will be undefined if the caller fails to specify the EXF_OWNER bit in the EX_DataFields mask. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. lock - (struct Lock *) Pointer to a valid object lock. RESULT1 - (struct ExamineData *) data or NULL on Failure. RESULT2 - (int32) Failure code if RESULT1 == NULL INPUTS (DosPacket method) dp_Type - (int32) ACTION_EXAMINEDATA dp_Arg1 - (struct Lock *) lock. RESULT1 - (struct ExamineData *) data or NULL on failure. RESULT2 - (int32) Failure code if RESULT1 == NULL NOTES This function shall return failure if 'lock' is NULL. SEE ALSO IDOS->ExamineObject() dos.library/ACTION_EXAMINEDATA_DIR dos.library/ACTION_EXAMINEDATA_DIR NAME ACTION_EXAMINEDATA_DIR - FSExamineDir() SYNOPSIS int32 RESULT1 = FSExamineDir(struct FileSystemVectorPort *fsvp, int32 *result2, struct PRIVATE_ExamineDirContext *ctx); FUNCTION This action initiates a list refill of struct ExamineData nodes that represent the entries within a directory specified by the parameters in the struct PRIVATE_ExamineDirContex which is initialised by the IDOS->ObtainDirContext() function. The returned data structure looks like this; struct ExamineData { struct MinNode EXDnode; /* List node. */ uint32 EXDinfo; /* General purpose user data. */ /* */ /* These are private members exclusively for the FS & DOS. */ uint32 FSPrivate; /* FILESYSTEM ONLY - Private usage. */ uint32 Reserved0; /* RESERVED - Future private usage. */ APTR DOSPrivate; /* DOSLIB ONLY - Private usage. */ /* */ /* The following are public fields. */ uint32 StructSize; /* (RO) Full size of the structure. */ uint32 Type; /* The entry descriptor value. */ int64 FileSize; /* Size if a file or -1LL if not. */ struct DateStamp Date; /* Days, Mins, Ticks. */ uint32 RefCount; /* Object hardlink count. [Note 1] */ uint64 ObjectID; /* Unique object identifier. [Note 2] */ STRPTR Name; /* (RO) Nul-terminated object name. */ uint32 NameSize; /* (RO) Allocated name buffer size. */ STRPTR Comment; /* (RO) Nul-terminated comment. */ uint32 CommentSize; /* (RO) Allocated comment buffer size.*/ STRPTR Link; /* (RO) Nul-terminated target name. */ uint32 LinkSize; /* (RO) Allocated target buffer size. */ uint32 Protection; /* Protection status bitmask. */ uint32 OwnerUID; /* Owner info. [Note 3] */ uint32 OwnerGID; /* Group info. [Note 3] */ uint32 Reserved2; /* DOS reserved field. */ uint32 Reserved3; /* DOS reserved field. */ uint32 Reserved4; /* DOS reserved field. */ }; (RO) = Read Only, these fields must not be modified by the application. See structure definition in include/dos/dos.h for detailed information. [Note 1] If possible, this field should be supported by filesystems that support hardlinks, it is used to indicate the hardlink reference count for objects. A value of one indicates that the object has no additional references other than itself, a value of two will indicate that it has one additional hardlink reference, a value of three means it has two hardlink references, etc... All hardlinks themselves always show a value of 1 in this field when supported, otherwise this field MUST be set to zero for all objects, if the filesystem does not support it. It will be undefined if the caller fails to specify the EXF_REFCOUNT bit in the EX_DataFields mask. [Note 2] This field is the mandatory unique object identfier for all objects on this volume, the value used here may be any arbitrary value as long as it is unique from all other objects on this volume, it may use the object node address, the disk header block number or other such values. (Note: this field is 64 bits wide.) This field will be undefined if the caller fails to specify the EXF_OBJECTID bit in the EX_DataFields mask. [Note 3] Historically, these fields only used the low 16 bits. For extensibility, the size of these are now 32 bit fields. However, for interoperability, it is recommended that values greater than 65535 be avoided where possible so reading only the low 16 bits results in the same value for legacy applications. These fields will be undefined if the caller fails to specify the EXF_OWNER bit in the EX_DataFields mask. ===== The private context control structure that is passed to the filesystem is as follows: struct PRIVATE_ExamineDirContext (see; dos/dosextens.h) { uint32 StructSize; struct MinList FreshNodeList; struct MinList StaleNodeList; uint32 DataRequestFlags; struct Lock * ReferenceLock; struct MsgPort * MessagePort; APTR MemoryPool; BPTR DOSPrivateCD; BPTR DOSPrivateLock; STRPTR DOSPrivateName; int32 DOSPrivateResult2; APTR DOSPrivateFallback; struct Hook * DOSPrivateMatchFunc; STRPTR DOSPrivateMatchString; APTR FSPrivateMemPtr; uint32 FSPrivate[8]; }; /* 108 bytes - v51.104 */ StructSize - (uint32) The size of this structure, it may expand in future for new features. FreshNodeList - (struct MinList) A list containing all the nodes that were added by the filesystem from the last action of type ACTION_EXAMINEDATA_DIR or a VP call to FSExamineDir(). Each time the caller invokes the IDOS->ExamineDir() function, DOS pulls the head node from this list and appends it to the StaleNodeList, then returns a pointer to that node. If there are no more nodes, another ACTION_EXAMINEDATA_DIR dospacket request is sent or a FSVP call to FSExamineDir(), DOS then tries to remove the head node again. If there are still no more, ExamineDir() returns NULL and the scan terminates. If this examine context is reused by using the tag; EX_ResetContext, DOS will move all nodes still left on this list to the "StaleNodeList" and reset the scan, before the next dospacket/fsvp call to the filesystem. StaleNodeList - (struct MinList) A list containing the ExamineData nodes which have already been returned to the caller by DOS, from invoking the ExamineDir() function. | On each call to this function, (and if the filesystem does | not wish to attempt node reuse), the filesystem should simply | call IExec->RemHead() for all nodes on this list and release | them back to the memory pool by calling; | while((n=IExec->RemHead(&ctx->StaleNodeList))) | { | IDOS->FreeDosObject(DOS_EXAMINEDATA,n); | } | | The filesystem should then obtain a new node by calling; | data = AllocDosObjectTags(DOS_EXAMINEDATA, | ADO_ExamineData_NameSize, ###, | ADO_ExamineData_CommentSize, ###, | ADO_ExamineData_LinkSize, ###, | ADO_ExamineDir_Context, context, TAG_END); | | | The filesystem shall then fill out the requested data fields | as specified by the 'DataRequestFlags' bitmask, | then it places the node on the tail of the 'FreshNodeList'. | This continues until there are no more directory entries. If the resources run out (memory) before directory entries, the filesystem can (at its discretion) do any of these; 1) Release all remaining nodes left on this 'StaleList' back to the pool using RemHead() + FreeDosObject(), then try to allocate a new one again. 2) Use the static FSPrivate[] array area to hold FS private context data so it can resume when the caller uses up what has just been partially provided by continuing to call ExamineDir() in the application. 3) Use the FSPrivateMemPtr buffer which the filesystem may have previously allocated to hold context data, or release it to free up "emergency memory" if it was used in that way. | Scan termination occurs ONLY when there are no more nodes | found on the 'FreshNodeList' after a filesystem call to refill. | | If the last refill request resulted in completion of the scan, | the filesystem must return FALSE with ERROR_NO_MORE_ENTRIES | in Result2. | | The filesystems primary FALSE returncode is only used by DOS | to evaluate if the call is supported or not, and to tell | when to save the secondary code that will eventually be | returned to the caller when there are no more entries found on | the FreshNodeList, TRUTH values are ignored by ExamineDir(). DataRequestFlags - (uint32) The bitmask specified with the tag; EX_DataFields in the ObtainDirContext() call to specify what data items are to be returned by the filesystem. NB: Unspecified fields shall be left uninitialised, if they are read they may contain data from a previous use. ReferenceLock - (struct Lock *) The reference lock place holder. Using EX_LockInput; DOS does not modify the original lock, only convert it to an APTR and places it here. Using EX_StringNameInput; The lock is obtained when DOS performs a Lock() on the string argument supplied, it is placed here and also in the DOSPrivateLock field which will be unlocked in ReleaseDirContext(). Using EX_FileHandleInput; The lock is obtained when DOS performs a ParentOfFH() on the filehandle supplied, it is placed here and also in the DOSPrivateLock field which will be unlocked in ReleaseDirContext(). MessagePort - (struct MsgPort *) The filesystems packet/vector port. MemoryPool - (APTR) Exec Memory pool for this context. DOSPrivateCD - (BPTR) DOS private lock for the original current directory lock when EX_DoCurrentDir,TRUE tag was specified. The old current dir will be restored in ReleaseDirContext() or on subsequent failure of this function if context reused. This value will be (BPTR)-1 if the tag EX_DoCurrentDir,TRUE has not been specified. ( Filesystems ignore this. ) DOSPrivateLock - (BPTR) DOS private lock. DOS lock for EX_StringNameInput or EX_FileHandleInput, this lock will be unlocked in ReleaseDirContext(). ( Filesystems ignore this. ) DOSPrivateName - (STRPTR) DOS private name of context allocator. ( Filesystems ignore this. ) ( Added 53.4 for resource track ) DOSPrivateResult2 - (int32) DOS private field. (internal Result2) ( Filesystems ignore this. ) DOSPrivateFallback - (APTR) DOS private memory for fallback code. This is used by DOS for the ExAllControl data only when the action is not supported by the respective filesystem. ( Filesystems ignore this. ) DOSPrivateMatchFunc - (struct Hook *) Pointer to a Hook structure which has the h_Entry pointer set to a filter function. (Default = NULL), for no filtering to occur. Value initialised by EX_MatchFunc tag. ( Filesystems ignore this. ) DOSPrivateMatchString - (STRPTR) If this field is NULL then all filenames will be returned, the MatchFunc will not be invoked. Value initialised by EX_MatchString tag. ( Filesystems ignore this. ) FSPrivate[8] - (uint32[8]) An -OPTIONAL- area for the filesystem to hold any sort of context information between successive action calls, such as may be required to restart a scan, if interrupted by a memory shortage, for example. All fields of this array will be 0 before the first call to ExamineDir() and all fields will also be set to 0 by DOS when an old context is reused with the EX_ResetContext tag. ( Filesystem use only. ) FSPrivateMemPtr - (APTR) An -OPTIONAL- pointer to an additional memory area that is reserved for the filesystem to use, to hold any sort of data or to reserve "emergency memory". DOS also uses this pointer for the fallback code read buffer, but ONLY if the filesystem does not support this action, otherwise, if the action is supported by the filesystem, this field can be considered as "filesystem use only". The required memory must be obtained ONLY from the function AllocVecPooled(), using the context memory pool pointer. This field will be NULL before the first call to ExamineDir(), and will be FreeVecPooled() and set to NULL by DOS, when an old context is released or reused with EX_ResetContext tag. ( Filesystem use only, when action is supported. ) INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. ctx - (struct PRIVATE_ExamineDirContext *) Pointer to the context. RESULT1 - (int32) DOSTRUE/FALSE (Success/Failure). RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_EXAMINEDATA_DIR dp_Arg1 - (struct PRIVATE_ExamineDirContext *) ctx. RESULT1 - (int32) DOSTRUE/FALSE (Success/Failure). RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES The 'Link' target field for softlinks and hardlinks shall be initialised as follows: For softlinks, the filesystem will follow the proceedure as per the FSReadSoftLink() / ACTION_READ_SOFT_LINK function autodocs, which means the only thing required is to copy the target string into the examinedata->Link buffer verbatim, nothing more. For hardlinks, the filesystem shall copy the target object name only into the examinedata->Link field buffer, nothing more. SEE ALSO IDOS->ExamineDir() dos.library/ACTION_EXAMINEDATA_FH dos.library/ACTION_EXAMINEDATA_FH NAME ACTION_EXAMINEDATA_FH - FSExamineFile() SYNOPSIS struct ExamineData *RESULT1 = FSExamineFile( struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file); FUNCTION Examines a single file identified by the filehandle reference. Returns data in the form of a struct ExamineData. The ExamineData block will be allocated by the filesystem by calling the AllocDosObject() function using the appropriate buffer sizes (###) as follows; data = IDOS->AllocDosObjectTags(DOS_EXAMINEDATA, ADO_ExamineData_NameSize, ###, ADO_ExamineData_CommentSize, ###, TAG_END); The filesystem will fill in the data structure members with current information for the file. This call may also cause the filesystem to flush any pending write buffers first, to get accurate information. If successfull, the returned data is used by the caller as needed, the caller must eventually release the ExamineData block by using the FreeDosObject() function; IDOS->FreeDosObject(DOS_EXAMINEDATA,data). The returned data structure looks like this; struct ExamineData { struct MinNode EXDnode; /* List node. */ uint32 EXDinfo; /* General purpose user data. */ /* */ /* These are private members exclusively for the FS & DOS. */ uint32 FSPrivate; /* FILESYSTEM ONLY - Private usage. */ uint32 Reserved0; /* DOS RESERVED - Private usage. */ APTR DOSPrivate; /* DOSLIB ONLY - Private usage. */ /* */ /* The following are public fields. */ uint32 StructSize; /* (RO) Full size of the structure. */ uint32 Type; /* The entry descriptor value. */ int64 FileSize; /* Size if a file or -1LL if not. */ struct DateStamp Date; /* Days, Mins, Ticks. */ uint32 RefCount; /* Object hardlink count. [Note 1] */ uint64 ObjectID; /* Unique object identifier. [Note 2] */ STRPTR Name; /* (RO) Nul-terminated object name. */ uint32 NameSize; /* (RO) Allocated name buffer size. */ STRPTR Comment; /* (RO) Nul-terminated comment. */ uint32 CommentSize; /* (RO) Allocated comment buffer size.*/ STRPTR Link; /* (RO) -- Unused by FSExamineFile(). */ uint32 LinkSize; /* (RO) -- Unused by FSExamineFile(). */ uint32 Protection; /* Protection status bitmask. */ uint32 OwnerUID; /* Owner info. [Note 3] */ uint32 OwnerGID; /* Group info. [Note 3] */ uint32 Reserved2; /* DOS reserved field. */ uint32 Reserved3; /* DOS reserved field. */ uint32 Reserved4; /* DOS reserved field. */ }; (RO) = Read Only, these fields must not be modified by the application. See structure definition in include/dos/dos.h for detailed information. [Note 1] If possible, this field should be supported by filesystems that support hardlinks, it is used to indicate the hardlink reference count for objects. A value of one indicates that the object has no additional references other than itself, a value of two will indicate that it has one additional hardlink reference, a value of three means it has two hardlink references, etc... All hardlinks themselves always show a value of 1 in this field when supported, otherwise this field MUST be set to zero for all objects, if the filesystem does not support it. It will be undefined if the caller fails to specify the EXF_REFCOUNT bit in the EX_DataFields mask. [Note 2] This field is the mandatory unique object identfier for all objects on this volume, the value used here may be any arbitrary value as long as it is unique from all other objects on this volume, it may use the object node address, the disk header block number or other such values. (Note: this field is 64 bits wide.) This field will be undefined if the caller fails to specify the EXF_OBJECTID bit in the EX_DataFields mask. [Note 3] Historically, these fields only used the low 16 bits. For extensibility, the size of these are now 32 bit fields. However, for interoperability, it is recommended that values greater than 65535 be avoided where possible so reading only the low 16 bits results in the same value for legacy applications. These fields will be undefined if the caller fails to specify the EXF_OWNER bit in the EX_DataFields mask. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to a valid file handle. RESULT1 - (struct ExamineData *) ExamineData or NULL on Failure. RESULT2 - (int32) Failure code if RESULT1 == NULL INPUTS (DosPacket method) dp_Type - (int32) ACTION_EXAMINEDATA_FH dp_Arg1 - (APTR) file->fh_Arg1 dp_Arg2 - (struct FileHandle *) file RESULT1 - (struct ExamineData *)data, NULL on failure. RESULT2 - (int32) Failure code if RESULT1 == NULL NOTES The function shall return failure if 'file' is NULL. SEE ALSO IDOS->ExamineObject() dos.library/ACTION_FH_FROM_LOCK dos.library/ACTION_FH_FROM_LOCK NAME ACTION_FH_FROM_LOCK - FSOpenFromLock() SYNOPSIS int32 RESULT1 = FSOpenFromLock(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, struct Lock *lock); FUNCTION This function opens a file from a given file lock. If this action is successful, the file system will essentially consume the lock so a program cannot use it anymore. If this function fails, the lock is still usable. Attempting to open a file using a directory lock MUST fail with the RESULT2 code set to ERROR_OBJECT_WRONG_TYPE. The lock mode determins the effective filehandle open mode, SHARED_LOCK returns a filehandle mode equivalent to MODE_OLDFILE, an EXCLUSIVE_LOCK returns a filehandle mode equivalent to MODE_NEWFILE but without modifying the file contents or meta-data, this operation is as would occur if opened in MODE_OLDFILE and promoted to MODE_NEWFILE with ACTION_CHANGE_MODE or FSChangeFileMode(). INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the file handle structure. lock - (struct Lock *) Pointer to the struct lock on the file. RESULT1 - (int32) Success / Failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS dp_Type - (int32) ACTION_FH_FROM_LOCK dp_Arg1 - (BPTR) filehandle structure to fill in. dp_Arg2 - (BPTR) lock on the file to open. RESULT1 - (int32) Boolean Success/Failure indicator. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->OpenFromLock() dos.library/ACTION_FILESYSTEM_ATTR dos.library/ACTION_FILESYSTEM_ATTR NAME ACTION_FILESYSTEM_ATTR - FSFileSystemAttr() SYNOPSIS int32 RESULT1 = FSFileSystemAttr(struct FileSystemVectorPort *fsvp, int32 *result2, struct TagItem *taglist); FUNCTION This packet allows access to various attributes of a given filesystem that is mounted on top of a disk driver, such as a hard or floppy disk. The ACTION_FILESYSTEM_ATTR function provides a simple method for reading parameters or setting values for filesystems supporting this feature. This function will only succeed if the underlying filesystem expressly supports a particular option, otherwise, it will return a failure code, (unless dos.library can supply the required information.) This function works by using a taglist to supply or obtain information, the taglist items are passed through to the underlying filesystem, the options are defined in such a way, as to provide specific tags that are used in either read or write mode. WARNING The filesystem shall reject values that are not within tollerance for that particular filesystem, it will simply abort further processing of any remaining tags when any value supplied is not within the allowable range. NB: The dos.library may also be able to extrapolate some required data if this function is not supported by the filesystem, in such cases, dos.library will only attempt to do so, where indicated, and only after it has determined that the filesystem cannot supply this information. There is also no guarantee that dos.library will succeed in doing this. INPUTS tags -- Pointer to a tagitem array for the options listed below. SOURCE TAGS ; Mandatory tag item to enable filesystem identification. The following four tags are mutually exclusive and are not passed through to the filesystem itself. FSA_StringNameInput (STRPTR) -- Pointer to a string identifier. (See GetDeviceProcFlags() for details about this.) FSA_FileHandleInput (BPTR) -- BCPL pointer to a FileHandle. Identify the filesystem by the stream pointed to by a FileHandle. The opening mode does not affect identification. FSA_LockInput (BPTR) -- BCPL pointer to a Lock. Identify the filesystem by this associated Lock. The lock mode does not affect the identification. FSA_MsgPortInput (struct MsgPort *) -- Pointer to a message port. Identify the filesystem by this associated message port. ( NOTE: This tag was added in 51.96 ) === READ TAGS ; The taglist options to Read filesystem information. FSA_MaxFileNameLengthR (uint32 *) -- Pointer to a uint32 storage area. Obtain the maximum filename length permitted. (not including \0) ( DOS library will attempt to extrapolate this value if the filesystem does not support this option. ) FSA_DOSTypeR (uint32 *) -- Pointer to a uint32 storage area. Obtain the dostype identifier for the filesystem. EG: 0x444F5303 = 'DOS\3' FSA_VersionNumberR (uint32 *) -- Pointer to a uint32 storage area. Obtain the filesystem version number as; (MAJOR<<16) | MINOR) FSA_VersionStringR (STRPTR) -- Pointer to a string buffer area. Obtain a copy of the version string for the filesystem. The version string will be the full version string in the same format as the 'bumprev' tools VSTRING, this being; "filesystem_name VER.REV (dd.mm.yyyy)" ( DOS library will attempt to extrapolate this value if the filesystem does not support this option, by searching for a $VER: cookie in the device nodes seglist. Note that the result buffer will have $VER: part removed, if one is found. ) You are required to specify the size of your string buffer area with the following sub-tag; FSA_VersionStringR_BufSize Failing to supply this tag will cause ERROR_REQUIRED_ARG_MISSING to be returned by IoErr(). (Dos.library tests for this before calling the filesystem) FSA_VersionStringR_BufSize (uint32) -- Size of the buffer pointed to by the FSA_VersionStringR tag. Recommended minimum; 60 bytes. Note: You are guaranteed that no more than this number of bytes will be written to your buffer area, if the storage area is smaller than the version string, it will be truncated. Passing a value of zero will fail with ERROR_BAD_NUMBER. (Dos.library test for zero before calling the filesystem) FSA_ActivityFlushTimeoutR (uint32 *) --Pointer to a uint32 storage area. Obtain the time in milliseconds before a flush while active occurs. ( 1000mS = 1 second) FSA_InactivityFlushTimeoutR (uint32 *) --Pointer to uint32 storage area. Obtain the time in milliseconds before a flush when inactive occurs. ( 1000mS = 1 second) FSA_HasRecycledEntriesR (int32 *) -- Pointer to a int32 storage area. Boolean test to see if the filesystem supports recycled entries. Note: This tag exists because the following FSA_MaxRecycledEntriesR tag allows for zero to indicate a valid number. FSA_MaxRecycledEntriesR (uint32 *) -- Pointer to a uint32 storage area. Obtain the number of recycled entries supported by the filesystem. Note: This may be zero, even if recycled entries are supported. === TAGS ; The taglist options to Set features for the filesystem. FSA_MaxFileNameLengthW (uint32) -- New value to set in filesystem. Set the maximum filename length. (not including \0) Note; this option may have limited support, if any. FSA_ActivityFlushTimeoutW (uint32) -- New value to set in filesystem. Set the time in milliseconds before a flush while active occurs. ( 1000mS = 1 second) FSA_InactivityFlushTimeoutW (uint32) -- New value to set in filesystem. Set the time in milliseconds before a flush when inactive occurs. ( 1000mS = 1 second) FSA_MaxRecycledEntriesW (uint32) -- New value to set in filesystem. Set the number of recycled entries supported by the filesystem. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. taglist - (struct TagItem *) Pointer to the taglist. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_FILESYSTEM_ATTR dp_Arg1 - (struct TagItem *) taglist RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES If the filesystem does not support a particular option, it will return FALSE in RESULT1 and ERROR_NOT_IMPLEMENTED in RESULT2. This function will return FALSE if a file system option requested could not be obtained or an option is not relevant for the specified filesystem, or the value specified in a (W)rite operation was illegal. From DOS 51.50 the input source tags are filtered out before calling the filesystem. The dos.library will pre-test common errors such as a NULL buffer pointer and zero length parameter for FSA_VersionStringR, which will result in the function being aborted before calling the filesystem. If the filesystem does not support a particular option, it should immediately return FALSE, with ERROR_NOT_IMPLEMENTED in RESULT2. Other errors that may abort processing, have different error codes that should be specific for the type of option used. For example, if a (W)rite operation supplied an illegal value, a value of ERROR_BAD_NUMBER should be returned. If the packet is returned with RESULT1 == FALSE, and the RESULT2 code is set to ERROR_ACTION_NOT_KNOWN, dos.library will attempt to extrapolate only the nominated items of information mentioned above. SEE ALSO IDOS->FileSystemAttr() dos.library/ACTION_FINDxxxx dos.library/ACTION_FINDxxxx NAME ACTION_FINDxxxx - FSOpen() ACTION_FINDINPUT aka MODE_OLDFILE ACTION_FINDOUTPUT aka MODE_NEWFILE ACTION_FINDUPDATE aka MODE_READWRITE SYNOPSIS int32 RESULT1 = FSOpen(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *fh, struct Lock *rel, CONST_STRPTR name, int32 mode); FUNCTION This action opens a stream to a file or a stream handler, and will use the supplied 'fh' (filehandle) to do so. For filesystems, the 'rel' lock and a 'name' arguments identify the object to open, this action must correctly support all argument methods currently in use, by using the relative arguments example code that can be found in the autodoc for ACTION_LOCATE_OBJECT / FSLock(), maximum compatibility for all string input functions will be guaranteed. The input arguments may appear in any of the following ways to identify a filesystem object, all three methods must be supported: (1) If the 'rel' lock is NULL, then the file 'name' is to be taken as being relative to the root directory of this filesystem. (2) If the 'rel' lock is NON-NULL, this usually identifies the directory where the file 'name' is to be located, providing the 'rel' lock is really a directory lock, never assume this lock will always be so. (3) If the 'name' is an empty string (""), and the 'rel' lock is a NON-NULL lock on a file, then that file shall be the object opened. The 'rel' lock is not consumed, it remains a valid reference lock and therefore this mode will fail if used with the exclusive open mode. (MODE_NEWFILE). For all Vector-Port function calls, 'name' never has path components, the dos.library parses it completely to the single final component name before calling the vector-port function. For DosPacket callers (only), file names are not limited to a single file name but instead can include a volume name (followed by a colon) and multiple slashes requiring the file system to resolve the object name. This eliminated the need for AmigaDOS or the application to parse names before sending them to the file system, unfortunately this also means that every filesystem must parse every dospacket name string to resolve it to a single object name. The calling program owns the file handle. In the case of a call to the DOS Open() function, AmigaDOS allocates the file handle automatically and then frees it in Close(). The file handle must be initialized before trying to open anything, the Open() function will initialise the fh_MsgPort field with a pointer to the MsgPort (Vector-Port) of the handler process, don't clear it.!! Lastly, the handler itself must initialize ONLY fh_Arg1/fh_Arg2 with something that allows the handler to identify the object being opened, this value is an implementation specific kind of "lock", but for various compatibility and interoperability purposes, fh_Arg1 should always be used as a BPTR to this custom "lock", while fh_Arg2 should always be an APTR to the same "lock". The reason for this is because for DosPacket based operations, only fh_Arg1 is passed as the primary argument to locate the object for the operations that perform various READ/WRITE/CHANGE/END/TRUNCATE functions, only this value was available and not the file handle itself. However, for Vector-Port calls, the original file handle pointer is supplied, therefore to avoid the BPTR conversions for non-dospacket based filesystems, the internal "lock" should be stored in fh_Arg2. The filesystem should also store the file handle pointer itself in the internal "lock" structure too, so it can be found from the filesystems "lock" list, for dismounting purposes.(if supported). FINDINPUT (MODE_OLDFILE) will only succeed if the file already exists, the file will be opened with a shared lock. Failure to locate the file must return failure plus the error code ERROR_OBJECT_NOT_FOUND. This opening mode is not affected by the protection bits or the disk write protection status. FINDUPDATE (MODE_READWRITE) will also open it with a shared lock but if the file doesn't exist, FINDUPDATE will create a new file. The disk write protection status must be observed with this mode when creating new files, the protection bits and the disk write protection status have no effect on opening an existing file. FINDOUTPUT (MODE_NEWFILE) will open a new file with an exclusive lock. It will effectively delete an existing file before creating a new file. (See; NOTES regarding semantics for hardlinks) With this mode, the disk write protection status must first be observed, along with the existing files (D)elete protection status. If the existing file is delete protected, failure shall be returned with a error code of ERROR_DELETE_PROTECTED. If the disk is write protected the error code shall be ERROR_DISK_WRITE_PROTECTED. All modes attempting to open on a directory object shall always return failure, the error code must be ERROR_OBJECT_WRONG_TYPE. All modes attempting to open a softlink shall always return failure, the error code must be ERROR_IS_SOFT_LINK. On success, all modes above will place the internal file position pointer at the beginning of the file. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. fh - (struct FileHandle *) Pointer to the filehandle struct. rel - (struct Lock *) Pointer to the reference lock for 'name'. name - (CONST_STRPTR) Pointer to the object name.(no path component) mode - (int32) MODE_OLDFILE, MODE_NEWFILE, MODE_READWRITE. RESULT1 - (int32) Boolean Success/Failure - (DOSTRUE or FALSE) RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_FINDxxxx dp_Arg1 - (BPTR) fh (filehandle). dp_Arg2 - (BPTR) rel (lock) dp_Arg3 - (BSTR) name. (string) dp_Arg4 - 0 dp_Arg5 - (BSTR) nameformat - name format indicator value. if(dp_Arg3==dp_Arg5) then BSTR's are guaranteed to be a nul-terminated extended BSTR. (53.23) RESULT1 - (int32) Boolean Success/Failure - (DOSTRUE or FALSE) RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES When using MODE_NEWFILE on filesystems that support hard file links, be aware that doing so with an existing hard file link name is equivalent to opening the target file itself in MODE_NEWFILE. However, because that target file has hardlinks bound to it, the implied "delete first" behaviour of MODE_NEWFILE means that the target file itself must not be physically "deleted" in the conventional sense, as that would disconnect the hard file linkage. Therefore only the content and associated data of the target file will be reset to that of a newly created file, where it has the default protection attributes set to EXDF_DEFAULT, a size of zero bytes, no comment string and a fresh creation datestamp, without affecting the existing hard file linkage. The default owner and user values for new files shall be inherited from the parent directory. SEE ALSO IDOS->Open(), ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_FLUSH dos.library/ACTION_FLUSH NAME ACTION_FLUSH - FSFlush() SYNOPSIS int32 RESULT1 = FSFlush(struct FileSystemVectorPort *fsvp, int32 *result2); FUNCTION This action causes the file system to flush out all buffers to disk. If any writes are pending, this must be completed before responding to this request. This action allows an application to make sure that the data that is supposed to be on the disk is actually written to the disk instead of waiting in a buffer. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. RESULT1 - (int32) DOSTRUE. RESULT2 - (int32) 0 INPUTS (DosPacket method) dp_Type - (int32) ACTION_FLUSH dp_Arg1 - 0. RESULT1 - (int32) DOSTRUE. RESULT2 - (int32) 0 SEE ALSO IDOS->FlushVolume(), IDOS->FlushVolumePort(), InhibitPort() dos.library/ACTION_FORMAT dos.library/ACTION_FORMAT NAME ACTION_FORMAT - FSFormat() SYNOPSIS int32 RESULT1 = FSFormat(struct FileSystemVectorPort *fsvp, int32 *result2, CONST_STRPTR volname, uint32 dostype); FUNCTION This function tells a file system to perform any device or file system specific formatting on any newly initialized media. Upon receiving this action, a file system can assume that the media has already been low level formatted and should proceed to write out any high level disk structure necessary to create an empty volume. The filesystem absolutely MUST be in an inhibited state before this action is called, otherwise a failure code of ERROR_OBJECT_IN_USE must be returned by the filesystem, this is also used as a safety interlock, so the filesystem must never do anything destructive to the volume if this action is called when uninhibited. This function shall also freshly serialize the new empty volume to perform the functionality of FSSerialize() / ACTION_SERIALIZE_DISK, this prevents DOS volume name conflicts with pre-existing volumes. Volumes of the same name are permitted, but the datestamps of the volume nodes must be different. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. volname - (CONST_STRPTR) Pointer to the new volume name. dostype - (uint32) DosType signature longword. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_FORMAT dp_Arg1 - (BSTR) Name for volume (if supported). dp_Arg2 - (uint32) DosType of format (file system specific) dp_Arg3 - 0 dp_Arg4 - 0 dp_Arg5 - (BSTR) nametype - name format indicator. if(dp_Arg1==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE dos.library/ACTION_FREE_DISK_FSSM dos.library/ACTION_FREE_DISK_FSSM NAME ACTION_FREE_DISK_FSSM (DEPRECATED) FUNCTION This packet is deprecated. This action frees the structure returned from ACTION_GET_DISK_FSSM. INPUTS (DosPacket method) dp_Type - (int32) ACTION_FILESYSTEM_ATTR dp_Arg1 - (struct FileSysStartupMsg *) Fssm data structure to free. RESULT1 - (int32) Success / Failure code, FALSE on failure. RESULT2 - (int32) Failure code if RESULT1 == FALSE. dos.library/ACTION_FREE_LOCK dos.library/ACTION_FREE_LOCK NAME ACTION_FREE_LOCK - FSUnLock() SYNOPSIS int32 RESULT1 = FSUnLock(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *lock); FUNCTION This action frees the lock passed to it. If passed a ZERO lock, the handler must also return success (DOSTRUE). INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. lock - (struct Lock *) Pointer to the lock to unlock. RESULT1 - (int32) Boolean Success/Failure code, FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket method) dp_Type - (int32) ACTION_FREE_LOCK dp_Arg1 - (BPTR) lock. RESULT1 - (int32) Success/Failure code, FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->UnLock() dos.library/ACTION_FREE_RECORD64 dos.library/ACTION_FREE_RECORD64 NAME ACTION_FREE_RECORD64 - FSUnLockRecord() SYNOPSIS int32 RESULT1 = FSUnLockRecord(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, int64 offset, int64 length); FUNCTION For filesystems, this function is optional, it would generally be implemented only for networked filesystems. From dos.library 53.102, this function will be emulated if you supply a NULL pointer for FSUnLockRecord(), or reject the action with FALSE and result2=ERROR_ACTION_NOT_KNOWN. (The prefered method.) This function unlocks any previous record lock. If the given range does not represent one that is currently locked in the file, this action returns FALSE along with ERROR_RECORD_NOT_LOCKED. In the event of multiple locks on a given area, all locks made by the same filehandle specified are freed. 'offset' is the start position (in bytes) of the record in the file. 'length' is the size (in bytes) of the record to be unlocked. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open filehandle. offset - (int64) Byte offset into file of record start. length - (int64) Byte length of the record. RESULT1 - (int32) Boolean Success/Failure code, FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket64 method) dp_Type - (int32) ACTION_FREE_RECORD64 dp_Arg1 - (struct FileHandle *) file dp_Arg2 - (int64) offset dp_Arg3 - (int32) 0 dp_Arg4 - (int32) 0 dp_Arg5 - (int64) length RESULT1 - (int64) Success/Failure (DOSTRUE/FALSE) RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES For old filesystems updating to the new 64 bit DosPacket method, be warned that besides the argument size difference, the argument order has also been changed. DOS callers to OBSOLETEUnLockRecord32() will be redirected to the new function slot if the old packet is rejected. SEE ALSO IDOS->UnLockRecord() dos.library/ACTION_GET_DISK_FSSM dos.library/ACTION_GET_DISK_FSSM NAME ACTION_GET_DISK_FSSM (DEPRECATED) FUNCTION This packet is deprecated. dos.library V50+ can extrapolates this information directly from the DosList device node. This function returns a copy of the filesystems FileSysStartupMsg data structure, it is freed with the ACTION_FREE_DISK_FSSM DosPacket. INPUTS (DosPacket method) dp_Type - (int32) ACTION_GET_DISK_FSSM dp_Arg1 - (int32) 0 - RESULT1 - (struct FileSysStartupMsg *) Data structure or 0 on error. RESULT2 - (int32) Failure code if RESULT1 == 0 dos.library/ACTION_GET_FILE_POSITION64 dos.library/ACTION_GET_FILE_POSITION64 NAME ACTION_GET_FILE_POSITION64 (NB: DosPacket64) - FSGetFilePosition() SYNOPSIS int64 RESULT1 = FSGetFilePosition(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file); FUNCTION ACTION_GET_FILE_POSITION64 returns the current absolute file cursor position of an open file, or the value of -1LL if an error occured. For packet callers, this call will use a struct DosPacket64. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. RESULT1 - (int64) Current File Position, -1LL on failure. RESULT2 - (int32) Failure code if RESULT1 == -1LL. INPUTS (DosPacket64 method) dp_Type - (int32) ACTION_GET_FILE_POSITION64 dp_Arg1 - (APTR) filehandle->fh_Arg1 dp_Arg2 - (int64) 0. dp_Arg3 - (struct FileHandle *) filehandle (added 53.49, previously 0) RESULT1 - (int64) Current file position (-1LL on failure). RESULT2 - (int32) Failure code if RESULT1 == -1LL SEE ALSO IDOS->GetFilePosition() dos.library/ACTION_GET_FILE_SIZE64 dos.library/ACTION_GET_FILE_SIZE64 NAME ACTION_GET_FILE_SIZE64 (NB: DosPacket64) - FSGetFileSize() SYNOPSIS int64 RESULT1 = FSGetFileSize(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file); FUNCTION ACTION_GET_FILE_SIZE64 returns the current size of an open file, or the value of -1LL if an error occured. This call may also cause the filesystem to flush any pending write buffers first, to obtain accurate and up to date information. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. RESULT1 - (int64) Current file size, -1LL on failure. RESULT2 - (int32) Failure code if RESULT1 == -1LL. INPUTS (DosPacket64 method) dp_Type - (int32) ACTION_GET_FILE_SIZE64 dp_Arg1 - (APTR) file->fh_Arg1 dp_Arg2 - (int64) 0. dp_Arg3 - (struct FileHandle *) file (added 53.49, previously 0) RESULT1 - (int64) Current file size, (-1LL on failure). RESULT2 - (int32) Failure code if RESULT1 == -1LL SEE ALSO IDOS->GetFileSize() dos.library/ACTION_INFO dos.library/ACTION_INFO NAME ACTION_INFO - FSVolumeInfoData() SYNOPSIS int32 RESULT1 = FSVolumeInfoData(struct FileSystemVectorPort *fsvp, int32 *result2, struct InfoData *infodat); FUNCTION ACTION_INFO is used to fill in an InfoData structure for the volume the lock (dp_Arg1) is on for DOSPacket callers. If the lock is ZERO the root directory of the current volume is used. For vector-port callers, there is no lock argument. This function is generally expected to return DOSTRUE if the volume is mounted, otherwise it may post a requester and return failure if the volume is not currently mounted, or if a disk is not currently inserted. The InfoData struct will always be longword aligned for DOSPacket calls due to the BPTR conversions that are required. For a vector-port call, default alignment is satisfactory. The contents of the InfoData structure are arranged as follows: id_NumSoftErrors ( -- Deprecated field ) Typically was for the number of media read/write errors encountered on this volume. This number increased for every error, regardless of which disk may be currently inserted, which means it's of little use for anything at all. Few file systems ever provided this information, it is generally always set to zero. This field will likely be reused in future for some other purpose, until then, please leave it set to zero. id_UnitNumber ( -- Deprecated field ) This can be the low level device driver unit number responsible for this disk drive, it also may not be. Few file systems ever provided this information, and the operating system itself no longer uses it as of AmigaOS 2.04 and beyond. This field is generally set to zero and will most likely be reused in future for some other purpose, until then, please leave it set to zero. id_DiskState This indicates the state of the media in this device, it should always be one of the following values: ID_DISKSTATE_VALIDATED Medium is readable and writable. ID_DISKSTATE_WRITE_PROTECTED Medium is readable, but cannot be written to. ID_DISKSTATE_VALIDATING Medium may be readable and is currently being prepared to make it writable again. This is also the default "parking" state used when the filesystem is waiting for media to be inserted, or the file system is in an unknown state and unable return meaningfull information about the medium, Always refer to id_DiskType for device state info. id_NumBlocks The number of storage units ("blocks") which this file system consists of. NOTE: This value can be zero! id_NumBlocksUsed The number of storage units currently in use by the file system. NOTE: This value can be zero or identical to the id_NumBlocks value! id_BytesPerBlock The number of bytes that make up a single storage unit ("block"). Note that this number may not match the physical size of the storage block, as used by the underlying storage device. The file system might return the size of a single data block instead, which can be shorter. id_DiskType This field indicates both the state of the file system and what kind of file system is involved. The following values indicate file system state: ID_NO_DISK_PRESENT No medium is currently present. ID_UNREADABLE_DISK A medium is present, but low level read errors have prevented the file system from figuring out what is stored on it. This medium may not be formatted or simply defective. ID_NOT_REALLY_DOS A medium is present, its contents are readable, but they are of no use for this file system. ID_BUSY The file system is currently "offline" and cannot access the medium. This may be because commands such as "Format" or "DiskCopy" are accessing the low level disk data and do not want the file system to interfere. The following values indicate what type of file system is involved: ID_DOS_DISK ID_FFS_DISK ID_INTER_DOS_DISK ID_INTER_FFS_DISK ID_FASTDIR_DOS_DISK ID_FASTDIR_FFS_DISK ID_LONGNAME_DOS_DISK ID_LONGNAME_FFS_DISK ID_MSDOS_DISK ID_VP255_DOS_DISK Each of these values stands for a particular type of file system and disk data format. The con-handler may return one of the following types, which indicate the state it currently operates in: ID_CON Input is line-buffered, i.e. you have to hit the [Return] key to transfer your input to the client reading data from this console stream. ID_RAWCON Input is unbuffered, i.e. each key you hit that produces a character immediately transfers input to the client software. This is the so-called 'single character' mode which can be enabled via IDOS->SetMode(..,DOSTRUE). Last, but not least, you might very rarely encounter a so-called "Kickstart" disk which contains the operating system for the Amiga 1000 and Amiga 3000 computers. It is identified by the following value: ID_KICKSTART_DISK Other disk type values may exist, which represent the file system signature stored on the disk (often in the first sector) or might just be random data found on an unformatted storage medium. Be prepared to handle this: always check the id_DiskState field to verify if the file system considers itself responsible for this disk. Do not make decisions based solely on the file system type found in the id_DiskType field! A file system should never report an id_DiskState value of ID_DISKSTATE_VALIDATED for a medium it cannot use. id_VolumeNode This field is supposed to be a BCPL pointer to the volume node of the currently active filesystem volume. Not all file systems will supply this, or exactly this particular information. Non filesystems may use this field for other completely incompatible purposes, for example, the con-handler may return a pointer to the console window. This field should be treated with caution. Note that it can also be ZERO! id_InUse This field is supposed to be set to FALSE/ZERO if there are currently no locks or files bound to the handler. Otherwise, the non-zero value returned from some old file systems may infact be any arbitrary non-zero boolean value. The now prefered V50+ use for filesystems is that they should actually return an integer for the number of locks currently in force. Stream handlers should indicate the number of streams currently open. The con-handler also uses this field for a completely different and incompatible purpose, such as storing a pointer to the console I/O request. As with id_VolumeNode this field should be treated with caution. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. infodat - (struct InfoData *) Pointer to the InfoData structure. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_INFO dp_Arg1 - (BPTR) Lock. dp_Arg2 - (BPTR) InfoData structure. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->GetDiskInfo(), Info() dos.library/ACTION_INHIBIT dos.library/ACTION_INHIBIT NAME ACTION_INHIBIT - FSInhibit() SYNOPSIS int32 RESULT1 = FSInhibit(struct FileSystemVectorPort *fsvp, int32 *result2, int32 state); FUNCTION This action is probably one of the most dangerous that a file system has to handle. When inhibiting succeeds, (state = TRUTH), the file system must not access any underlying media and must return the error code; ERROR_OBJECT_IN_USE on all actions that attempt to access the device. The file system must flush all buffers before the inhibit is enacted, popping up a requester demanding that the user put back the current disk, if necessary, and attempt to complete a pending write request. Alternatively, a file system may simply reject an inhibit request if any files are currently open. The way this function is implemented is filesystem design dependant, but in all cases, access to the underlying media must be prevented after an inhibit request has been enacted. If an inhibit request cannot be enacted, this function shall return FALSE instead of DOSTRUE. Once uninhibited (state = FALSE), the file system MUST assume that the medium has been changed and generate the appropriate diskchange events, along with validating the medium again. When uninhibiting, the primary RESULT1 value shall always be DOSTRUE, there shall be no impediment or failure possible when uninhibiting. A handler must also nest inhibits. Prior to 2.0, the system handlers did not keep a nesting count and were subject to some obscure race conditions. The 2.0 ROM filing system introduced a nesting count. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. state - (int32) Inhibit state, (DOSTRUE/FALSE). RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_INHIBIT dp_Arg1 - (int32) DOSTRUE = inhibit, FALSE = uninhibit. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->Inhibit(), NonBlockingModifyDosEntry(). dos.library/ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_INHIBIT_DOS_LONGPATH_HANDLING NAME ACTION_INHIBIT_DOS_LONGPATH_HANDLING (V53.23) FUNCTION As of V53.23 with the ability to use extend BSTR strings (XBSTR) with lengths longer than 255 chars in dospackets, this action has been introduced to formally control the behaviour of the internal dos.library long path name handling code. If a filesystem or handler responds with DOSTRUE to this query packet, (which is only sent when dos.library encounters a long path name string off 256 characters or more), dos.library will inhibit the use of its internal long path handling code and pass the full length string as an XBSTR to the handler via the dospacket. If your handler is unprepared to accept extended BSTR's (XBSTR) in the dospackets, then you must return FALSE to this dospacket queery. As this packet is somewhat newer than many handlers, by default, these will reply with FALSE and RESULT2 = ERROR_ACTION_NOT_KNOWN which will make the dos.library supply only strings of 255 characters or shorter. INPUTS dp_Type - (int32) ACTION_INHIBIT_DOS_LONGPATH_HANDLING RESULT1 - (int32) Boolean - DOSTRUE or FALSE RESULT2 - (int32) Secondary indicator code if RESULT1 == FALSE. This will be: 0 or ERROR_ACTION_NOT_KNOWN depending on whether the handler supports this packet or not. NOTES Extended BSTR strings (XBSTR) are the same as normal BSTR strings other than they may extend to any length in excess of 255 characters and are also nul-terminated as per c-strings. The length byte of an XBSTR is correct only up to 255 characters, past that length, it will continue to read 255. The use of XBSTR's in dos.library dospacket calls are always indicated by a documented extra parameter in the dospacket. SEE ALSO IDOS->Open(). dos.library/ACTION_IS_FILESYSTEM dos.library/ACTION_IS_FILESYSTEM NAME ACTION_IS_FILESYSTEM FUNCTION Through this action, a handler can indicates whether or not it is a file system (whether or not it can support separate files for storing information). Programs will assume a handler can create multiple, distinct files through calls to Open() if the handler returns a DOSTRUE value to this queery. A handler does not need to support directories and subdirectories in order to qualify as a file system, but it must support the object examination functions calls. For Vector-Port implementors, there is no equivalent filesystem vector-port call for this dospacket simply because only filesystems have filesystem vector-ports. If dos.library detects that the handler has a filesystem vector-port, it will return DOSTRUE for the IDOS->IsFileSystem[Port]() functions. INPUTS dp_Type - (int32) ACTION_IS_FILESYSTEM dp_Arg1 - 0 RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->IsFileSystem(), IDOS->IsFileSystemPort() dos.library/ACTION_LOCATE_OBJECT dos.library/ACTION_LOCATE_OBJECT NAME ACTION_LOCATE_OBJECT - FSLock() SYNOPSIS struct Lock * RESULT1 = FSLock(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name, int32 mode); FUNCTION The AmigaDOS functions Lock() and LockTags() use this action. Given a name for the object, (which can include a path for dospacket calls only), and a relative lock from which to look for the name, which can also be NULL for root directory references. This action will locate the object within the filesystem and create a Lock structure associated with the object. For vector-port calls, the 'name' will always be a single object name without any path component whatsoever, the reference lock 'rel' generally points to the directory where the object 'name' resides. When the 'rel' reference lock is NULL, then the reference shall always be taken as being the root directory of the volume. If the 'name' is a empty string (""), the returned lock shall be a copy of the reference lock. Therefore, if both the reference lock 'rel' is NULL, and the 'name' is an empty string, a copy of the root directory lock shall be returned. Never assume 'rel' is a directory lock, it may actually be on a file. See EXAMPLE section below for example code to handle this correctly. The memory for the Lock structure returned in RESULT1 shall be allocated by the IDOS->AllocDosObject(DOS_LOCK,...) function and freed by the IDOS->FreeDosObject(DOS_LOCK,...) function upon an ACTION_FREE_LOCK or a vector call to FSVP->FSUnLock(). A handler can create an exclusive lock only if there are no other outstanding locks on the given file. Once created, an exclusive lock prevents any other locks from being created for that file. As of V53, exclusive locks on directories have been deprecated, all requests for an exclusive directory lock MUST return a shared lock without causing an error, in effect, the exclusive lock mode request is simply ignored for directories. This is NOT optional, if you fail to implement only shared directory lock mode, then the dos.library vector-port and long path handling will simply not work in all circumstances. The fl_Volume field of the returned Lock structure shall point to the DOS device lists volume entry for the volume of the lock, as a BPTR. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' reference lock. name - (CONST_STRPTR) Pointer to the object name.(no path component) mode - (int32) SHARED_LOCK, EXCLUSIVE_LOCK. RESULT1 - (struct Lock *) Pointer to the lock, NULL on failure. RESULT2 - (int32) Failure code if RESULT1 == NULL INPUTS (DosPacket method) dp_Type - (int32) ACTION_LOCATE_OBJECT dp_Arg1 - (BPTR) lock. dp_Arg2 - (BSTR) object_name. (may also include path) dp_Arg3 - (int32) Mode. SHARED_LOCK or EXCLUSIVE_LOCK. dp_Arg4 - 0 dp_Arg5 - (BSTR) nameformat - name format indicator value. only if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (BPTR) Lock - (ZERO on failure.) RESULT2 - (int32) Failure code if RESULT1 == ZERO EXAMPLE This pseudocode demonstrates how to handle the supplied parameters inside the filesystem to cope with all possible argument variations. This method should be used in all filesystem functions that accept the standard paired relative lock with a string name descriptor. It is important to make no assumptions about the supplied arguments, failure to follow this resolution method will likely result in failure with some combinations, such as attempting to Open() an assignment to a file, or root relative specifications and using Lock() to obtain a copy of the relative reference lock, or locks on the root directory. struct ObjNode *handle_rel_args(struct ObjLock *rel, CONST_STRPTR name) { struct ObjNode *reference; struct ObjNode *object = NULL; /* ** Handle the 'rel' argument first, to get the reference. ** Make no assumptions about what object type it references. */ if( rel ) /* handle valid locks */ { reference = rel->node; /* the reference object from lock */ } else { reference = ROOT->node; /* use root directory when 'rel'=0 */ } /* ** Next, handle the string name argument. */ if( name[0] ) /* scan only with valid obj name here. */ { /* do the directory test in find() */ object = find(reference, name); } else { object = reference; /* "" name means use reference object */ } /* regardless of what it may be. */ return(object); } SEE ALSO IDOS->Lock(), IDOS->LockTags(), ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_LOCK_RECORD64 dos.library/ACTION_LOCK_RECORD64 NAME ACTION_LOCK_RECORD64 - FSLockRecord() SYNOPSIS int32 RESULT1 = FSLockRecord(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, int64 offset, int64 length, uint32 mode, uint32 timeout); FUNCTION For filesystems, this function is optional, it would generally be implemented only for networked filesystems. From dos.library 53.102, this function will be emulated if you supply a NULL pointer for FSLockRecord(), or preferably reject the action by returning FALSE and result2=ERROR_ACTION_NOT_KNOWN to avoid the DOS library dospacket fallback being tried. This function locks an area of a file in either a sharable (indicating read-only) or exclusive (indicating read/write) mode. Several sharable record locks from different file handles can exist simultaneously on a particular file area but only one file handle can have exclusive record locks on a particular area at a time. The exclusivity of an exclusive file lock only applies to record locks from other file handles, not to record locks with the same file handle. One file handle can have any number of overlapping exclusive or shared record locks. 'offset' is the start position (in bytes) of record in the file. 'length' is the size (in bytes) of the record to be locked. 'mode' is one of the following: REC_EXCLUSIVE (0) = Exclusive REC_EXCLUSIVE_IMMED (1) = Immediate Exclusive (timeout is ignored) REC_SHARED (2) = Shared REC_SHARED_IMMED (3) = Immediate Shared (timeout is ignored) 'timeout' is the period (in the number of AmigaDOS ticks @ 1/50 second) to wait for success, before failing the operation. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open filehandle. offset - (int64) Byte offset into file of record start. length - (int64) Byte length of the record. mode - (uint32) Mode for locking record. timeout - (uint32) Number of ticks to wait before failing. RESULT1 - (int32) Boolean Success/Failure code, FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket64 method) dp_Type - (int32) ACTION_LOCK_RECORD64 dp_Arg1 - (struct FileHandle *) file dp_Arg2 - (int64) offset dp_Arg3 - (int32) mode dp_Arg4 - (int32) timeout dp_Arg5 - (int64) length RESULT1 - (int64) Success/Failure (DOSTRUE/FALSE) RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES For old filesystems updating to the new 64 bit DosPacket method, be warned that besides the argument size difference, the argument order has also been changed. DOS callers to OBSOLETELockRecord32() will be redirected to the new function slot if the old dospacket is rejected by returning FALSE and result2=ERROR_ACTION_NOT_KNOWN. SEE ALSO IDOS->LockRecord() dos.library/ACTION_MAKE_LINK dos.library/ACTION_MAKE_LINK NAME ACTION_MAKE_LINK - FSCreateSoftLink() - FSCreateHardLink() SYNOPSIS int32 RESULT1 = FSCreateSoftLink(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR link, CONST_STRPTR target); int32 RESULT1 = FSCreateHardLink(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR link, struct Lock *target); FUNCTION Causes the file system to create a link to a file or directory. There are two kinds of links, hard links and soft links. The basic difference between them is that a file system resolves a hard link itself, while the file system passes a string back to DOS telling it where to find a soft linked file or directory. To the DOS level programmer, there is essentially no difference between referencing a file by its original name or by its link name. In the case of a hard link, `target' is a lock on the file or directory target that the link is `linked' to, while in a soft link, `target' is a pointer (CPTR) to a C-style path string. In an over-simplified model of the file system, when asked to locate a file, the system scans a disk looking for a file header with a specific (file) name. That file header points to the actual file data somewhere on the disk. With hard links, more than one file header can point to the same file data, so data can be referenced by more than one name. When the user tries to delete a hard link to a file, the system first checks to see if there are any other hard links to the file. If there are, only the hard link is deleted, the actual file data the hard link used to reference remains, so the existing hard links can still use it. In the case where the 'real' object (not a hard link) is deleted, the file system will make one of its hard links the new `real' object. Hard links can exist on directories as well. Because hard links `link' directly to the underlying media, hard links in one file system cannot reference objects in another file system. Also for hard directory links, the same precautions against creating directory loops (like FSRename()) should be observed, in that it should be impossible to create a hard directory link that points to a target directory above the level of the hard directory link itself, return ERROR_OBJECT_EXISTS if this is attempted. Soft links are resolved through DOS calls. When the file system scans a disk for a file or directory name and finds that the name is a soft link, it returns failure and an error code ERROR_IS_SOFT_LINK. If this happens, the dos.library asks the file system to tell it what the link refers to by calling ACTION_READ_SOFT_LINK or the new Vector-port function FSReadSoftLink() to obtain the target string. Soft Links are stored on the media just like a file, but instead of pointing directly to data on the disk, a soft link simply contains a string descriptor that is the path and name of the target object which may be a link directory relative path or an absolute path and may also contain the name of another volume, in which case, softlink can be used to reference objects on other disks. For vector-port callers, the maximum length of a softlink target string is set at 4000 bytes, the target string supplied to the filesystem is only stored and nothing more. INPUTS (FileSystemVectorPort method; FSCreateSoftLink() ) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'link' reference lock. link - (CONST_STRPTR) Pointer to the link name.(no path component) target - (CONST_STRPTR) Pointer to the target string. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE) FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (FileSystemVectorPort method; FSCreateHardLink() ) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'link' reference lock. link - (CONST_STRPTR) Pointer to the link name.(no path component) target - (struct Lock *) Pointer to the target reference lock. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE) FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. INPUTS (DosPacket method) dp_Type - (int32) ACTION_MAKE_LINK dp_Arg1 - (BPTR) relative lock (relative to dp_Arg2) dp_Arg2 - (BSTR) name of link to be created. dp_Arg3 - (int32) target object ( STRPTR or BPTR ) [*] dp_Arg4 - (int32) Boolean; -1=SOFTLINK or 0=HARDLINK. dp_Arg5 - (BSTR) nametype; name format indicator value. if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE) FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE. [*] For soft-link packets, dp_Arg3 = (STRPTR) Target object string. For hard-link packets, dp_Arg3 = (BPTR) A lock to the target object. NOTES Links are never permitted to destroy any object including other links. RESULT1=FALSE, RESULT2=ERROR_OBJECT_EXISTS shall be returned if this situation is encountered. For Hardlinks, the supplied object reference lock is not harmed in the making of this hardlink. Just like the examinations functions, it is only used to identify the object, it is never consumed. SEE ALSO IDOS->MakeLink(), ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_MORE_CACHE dos.library/ACTION_MORE_CACHE NAME ACTION_MORE_CACHE FUNCTION No newer filesystems support this function, the optimal buffer size is now determined automatically by the respective filesystem. Some stream handlers may still use this dospacket but don't expect it. For older dospacket based filesystems and handlers, this action may allows an application to change the number of internal buffers used by the filesystem for caching, generally via the AddBuffers() function. Note that a positive number increases the number of buffers while a negative number decreases the number of buffers. In all cases, the number of current buffers should be returned in RESULT1. This allows an application to inquire the number of buffers by sending in a value of 0 in dp_Arg1 (resulting in no change). INPUTS dp_Type - (int32) ACTION_MORE_CACHE dp_Arg1 - (int32) Number of buffers to add, may also be negative, or 0. RESULT1 - (int32) Total number of buffers used by the handler, or 0 upon failure. RESULT2 - (int32) Failure code if RESULT1 == 0 BUGS The V36 ROM filesystem (FFS/OFS) doesn't return the right number of buffers unless preceded by an AddBuffers(fs,-1) (in-use buffers aren't counted). This is fixed in V37. Practically no file system implemented this packet as documented in the oldest dos.library documentation, which required that the RESULT1 would indicate success and the total number of buffers should be returned via RESULT2. The canonical behaviour is now the official one and that is to return the total number of buffers in RESULT1, with 0 for an error, in the case of an error RESULT2 will hold the error number, if no error, RESULT2 shall be 0. SEE ALSO IDOS->AddBuffers() dos.library/ACTION_NIL dos.library/ACTION_NIL NAME ACTION_NIL FUNCTION Although not specifically an action, some returns can look like this value because the action field has not been filled in. This is also used as a "do nothing" packet. INPUTS dp_Type - (int32) ACTION_NIL SEE ALSO ACTION_STARTUP dos.library/ACTION_OBTAIN_CON_INFO dos.library/ACTION_OBTAIN_CON_INFO NAME ACTION_OBTAIN_CON_INFO FUNCTION ACTION_OBTAIN_CON_INFO is used to obtain information about a console handler window, this packet will also increment the use-count for the handler. The returned data shall be released with ACTION_RELEASE_CON_INFO. INPUTS dp_Type - (int32) ACTION_OBTAIN_CON_INFO dp_Arg1 - (struct ConsoleWindowData *) condata dp_Arg2 - (int32) sizeof(condata) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->ObtainConsoleData(), IDOS->ReleaseConsoleData() dos.library/ACTION_PARENT dos.library/ACTION_PARENT NAME ACTION_PARENT - FSParentDir() SYNOPSIS struct Lock *RESULT1 = FSParentDir(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *lock); FUNCTION This function uses a lock on an object and creates a shared lock on that object's parent directory. If the lock is for a directory, the RESULT1 will be a shared directory lock one directory level above. If lock is on a file, the RESULT1 will returns a shared directory lock to the directory level where the file is located. If the lock has no parent, then a lock of ZERO is returned. No secondary error code shall be returned for ZERO root locks. A lock of ZERO will return ZERO and a secondary error code of ERROR_REQUIRED_ARG_MISSING in RESULT2. Note that this case is currently handled in IDOS->ParentDir() but the filesystem should still be prepared for ZERO locks being supplied. Note that this operation is typically used in the process of building an absolute path name for a given object. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. lock - (struct Lock *) Pointer to a struct lock. RESULT1 - (struct Lock *) Parent dir lock, ZERO on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO. INPUTS (DosPacket method) dp_Type - (int32) ACTION_PARENT dp_Arg1 - (BPTR) Lock on the object to get the parent of. RESULT1 - (BPTR) Parent lock, ZERO on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO SEE ALSO IDOS->ParentDir() dos.library/ACTION_PARENT_FH dos.library/ACTION_PARENT_FH NAME ACTION_PARENT_FH - FSParentOfFH() SYNOPSIS struct Lock *RESULT1 = FSParentOfFH(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file); FUNCTION This function returns a lock on the parent directory for a currently opened file handle. The lock mode returned is always a shared lock. Note that unlike ACTION_COPY_LOCK_FH, the mode of the file handle is unimportant. For an open file, ACTION_PARENT_FH should return a lock under all circumstances. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to an open file. RESULT1 - (struct Lock *)Lock on the parent dir of file, ZERO on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO. INPUTS (DosPacket method) dp_Type - (int32) ACTION_PARENT_FH dp_Arg1 - (APTR) file->fh_Arg1. dp_Arg2 - (struct FileHandle *)file. (added 53.49, previously 0) RESULT1 - (BPTR) Lock on parent dir of file or ZERO on error. RESULT2 - (int32) Failure code if RESULT1 == ZERO SEE ALSO IDOS->ParentOfFH() dos.library/ACTION_READ dos.library/ACTION_READ NAME ACTION_READ - FSRead() SYNOPSIS int32 RESULT1 = FSRead(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, STRPTR buffer, int32 numchar); FUNCTION This function extracts data from the file (or input channel) at the current position. If fewer bytes remain in the file than requested, only those bytes remaining will be returned with the number of bytes actually read will be returned in RESULT1, this may also be zero if end-of-file has already been reached. The handler indicates errors with -1 in RESULT1 and the error code in RESULT2. An error would occur if attempting to read from a read protected file, in this particular case the RESULT2 error code = ERROR_READ_PROTECTED. If the read fails, the current file position remains unchanged. A handler may return a smaller number of bytes than requested, even if not at the end of a file. This can happen with interactive type file handles which may return one line at a time as the user hits return, for example the console handler CON:. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. buffer - (STRPTR) Pointer to the buffer to read data into. numchar - (int32) Number of bytes to read. RESULT1 - (int32) Number of bytes actually read. 0 for EOF, -1 on error. RESULT2 - (int32) Failure code if RESULT1 == -1. INPUTS (DosPacket method) dp_Type - (int32) ACTION_READ dp_Arg1 - (APTR) fh_Arg1 field of the open struct FileHandle. dp_Arg2 - (APTR) Buffer to put data into. dp_Arg3 - (int32) Number of bytes to read. dp_Arg4 - (APTR) struct FileHandle pointer (added 53.49, previously 0) RESULT1 - (int32) Number of bytes read. 0 indicates EOF, -1 on error. RESULT2 - (int32) Failure code if RESULT1 == -1 SEE ALSO IDOS->Read() dos.library/ACTION_READ_SOFT_LINK dos.library/ACTION_READ_SOFT_LINK NAME ACTION_READ_SOFT_LINK - FSReadSoftLink() SYNOPSIS int32 RESULT1 = FSReadSoftLink(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR linkname, STRPTR buffer, int32 bufsize); FUNCTION Returns the destination target object descriptor for a soft link. The softlink is identified by the relative lock 'rel' and 'linkname'. To handle the 'rel' and 'linkname' parameters correctly within the filesystem, use the example code in the ACTION_LOCATE_OBJECT / FSLock() autodoc. This operation requires the filesystem to do nothing else but copy the target string of the softlink into the destination buffer and return the string length of it in RESULT1, or a negative value upon error, as: -2 if there isn't enough space in 'buffer'. -1 for other errors, specified by the error code in RESULT2. (See NOTES for error codes) INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the soft linkname relative lock. linkname - (CONST_STRPTR) Pointer to the soft linkname string. buffer - (STRPTR) Buffer to hold the destination target string. bufsize - (int32) Size of the destination target string buffer. RESULT1 - (int32) Actual length of returned string, -2 if there isn't enough space in buffer, or -1 for other errors. RESULT2 - (int32) Failure code if RESULT1 is a negative value. INPUTS (DosPacket method) dp_Type - (int32) ACTION_READ_SOFT_LINK dp_Arg1 - (BPTR) lock on directory that dp_Arg2 is relative to. dp_Arg2 - (STRPTR) Linkname and path string. (relative to dp_Arg1). NOTE: This is a C string not a BSTR. dp_Arg3 - (STRPTR) Buffer for the target object destination string. NOTE: This is a C string not a BSTR. dp_Arg4 - (int32) Size of the destination buffer. (dp_Arg3). RESULT1 - (int32) Actual length of returned string, -2 if there isn't enough space in buffer, or -1 for other errors. RESULT2 - (int32) Failure code if RESULT1 is a negative value. NOTES For -2 error codes, the FS shall set RESULT2 = ERROR_LINE_TOO_LONG. For -1 error codes, the FS shall use a code appropriate for the error. SEE ALSO IDOS->ReadSoftLink() dos.library/ACTION_RELEASE_CON_INFO dos.library/ACTION_RELEASE_CON_INFO NAME ACTION_RELEASE_CON_INFO FUNCTION ACTION_RELEASE_CON_INFO is used to decrement the handler use-counter from a previous ACTION_OBTAIN_CON_INFO. INPUTS dp_Type - (int32) ACTION_RELEASE_CON_INFO dp_Arg1 - (struct ConsoleWindowData *) condata dp_Arg2 - (int32) sizeof(condata) RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->ObtainConsoleData(), IDOS->ReleaseConsoleData() dos.library/ACTION_REMOVE_NOTIFY dos.library/ACTION_REMOVE_NOTIFY NAME ACTION_REMOVE_NOTIFY - FSRemoveNotify() (OPTIONAL - Emulated by DOS V52.28+) SYNOPSIS int32 RESULT1 = FSRemoveNotify(struct FileSystemVectorPort *fsvp, int32 *result2, struct NotifyRequest *nreq); FUNCTION This optional action cancels a notification (see ACTION_ADD_NOTIFY). the notifyrequest argument is the NotifyRequest structure used to start the notification, it does not delete the actual NotifyRequest structure, See FreeDosObject() for this. The handler should abandon any pending notification messages. Note that it is possible for a file system to receive a reply from a previously sent notification message even after the notification has been terminated. It should accept these messages silently and throw them away. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. nreq - (struct NotifyRequest *) Pointer to the notify request. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_REMOVE_NOTIFY dp_Arg1 - (struct NotifyRequest *) notifyrequest. RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->EndNotify() dos.library/ACTION_RENAME_DISK dos.library/ACTION_RENAME_DISK NAME ACTION_RENAME_DISK - FSRelabel() SYNOPSIS int32 RESULT1 = FSRelabel(struct FileSystemVectorPort *fsvp, int32 *result2 CONST_STRPTR newname); FUNCTION This action allows an application to change the name of the current volume. A file system implementing this function must also change the name stored in the volume node of the DOS device list and the name of the root directory. Be prepared for failure from RenameDosEntry() if a name conflicts. After the relabel succeeds, issue a DISKINSERTED event for anyone waiting for IDCMP_DISKINSERTED, this can be done by simply calling; IDOS->NonBlockingModifyDosEntry(0, NBM_DISKINSERTED, 0, 0); INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. newname - (CONST_STRPTR) Pointer to the new volume name string. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_RENAME_DISK dp_Arg1 - (BSTR) newname (without colon) dp_Arg2 - 0 dp_Arg3 - 0 dp_Arg4 - 0 dp_Arg5 - (BSTR) nametype - name format indicator value. if(dp_Arg1==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->Relabel(), IDOS->NonBlockingModifyDosEntry(). dos.library/ACTION_RENAME_OBJECT dos.library/ACTION_RENAME_OBJECT NAME ACTION_RENAME_OBJECT - FSRename() SYNOPSIS int32 RESULT1 = FSRename(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *src_rel, CONST_STRPTR src, struct Lock *dst_rel, CONST_STRPTR dst); FUNCTION This function renames the file, directory or symbolic link specified. An error is returned if the operation fails. There is a responsibility of the file system to ensure that the operation is not going to cause adverse effects. If the volume itself is write protected, (check this first) return failure and set the error code to; ERROR_DISK_WRITE_PROTECTED. The renaming action allows moving files across directory bounds and as such must ensure that it doesn't create hidden directory loops by renaming a directory into a child of itself. To accomplish this, simply iterate backwards (towards the root directory) starting at the 'dst_rel' relative directory, if the 'src_rel' directory is one of the 'dst_rel' parents, abort and return failure with the error code set to; ERROR_OBJECT_IN_USE. This function must also fail if a destination object already exists providing it is a different object from the one being renamed, return failure with the error code set to; ERROR_OBJECT_EXISTS. It is perfectly legal to specify the same object for the source and destination strings, but with different case, by default, AmigaDOS is case insensitive, so an operation to change case must succeed. EG: IDOS->Rename("sys:foo","sys:FoO"); Renaming softlinks may not be supported by some dospacket based filesystems, some may simply fail a softlink renaming request by returning FALSE with the secondary error code ERROR_IS_SOFT_LINK. It is mandatory that vector-port based filesystems support both changing the name of a softlink and moving it outside its original directory if requested, regardless of whether it adversely affects the softlink target path validity. To handle the relative dir and name string parameters correctly, use the example code shown in ACTION_LOCATE_OBJECT / FSLock() autodoc. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. src_rel - (struct Lock *) Pointer to the source dir lock. src - (CONST_STRPTR) Pointer to the name of the source object. dst_rel - (struct Lock *) Pointer to the destination dir lock. dst - (CONST_STRPTR) Pointer to the name of the destination object. RESULT1 - (int32) Boolean Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_RENAME_OBJECT dp_Arg1 - (BPTR) relative lock for dp_Arg2. (source) dp_Arg2 - (BSTR) source object name. (may also include path) dp_Arg3 - (BPTR) relative lock for dp_Arg4. (destination) dp_Arg4 - (BSTR) destination object name. (may also include path) dp_Arg5 - (BSTR) nameformat - name format indicator value, only if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be a nul-terminated string. (53.23) RESULT1 - (int32) Boolean Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES The fast file system currently checks the write protection bit of the respective directories and fails the operation if they have the write protection bit enabled. However, only the (D)elete protection bit has any meaning for directories on the old ROM filesystem and other third party filesystems. SEE ALSO IDOS->Rename(), IDOS->SetProtection() dos.library/ACTION_SAME_FH dos.library/ACTION_SAME_FH NAME ACTION_SAME_FH - FSSameFile() SYNOPSIS int32 RESULT1 = FSSameFile(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *fh1, struct FileHandle *fh2); FUNCTION This action compares the targets of two filehandles, if they are on the same file, ACTION_SAME_FH will return DOSTRUE. If the two filehandles are on different objects, it returns FALSE. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. fh1 - (struct FileHandle *) Pointer to the first filehandle. fh2 - (struct FileHandle *) Pointer to the second filehandle. RESULT1 - (int32) DOSTRUE / FALSE (DOSTRUE for same file) RESULT2 - (int32) Failure code if RESULT1==FALSE and an error occured. INPUTS (DosPacket method) dp_Type - (int32) ACTION_SAME_FH dp_Arg1 - (APTR) fh1->fh_Arg1. dp_Arg2 - (APTR) fh2->fh_Arg1. dp_Arg3 - (struct FileHandle *)fh1. dp_Arg4 - (struct FileHandle *)fh2. RESULT1 - (int32) DOSTRUE / FALSE (DOSTRUE for same file) RESULT2 - (int32) Failure code if RESULT1 == FALSE, otherwise 0. NOTES This packet was introduced in dos.library 53.71 If the filesystem does not support this packet yet, dos.library will provide emulation using SameLock() and DupLockFromFH(). SEE ALSO IDOS->SameFH() dos.library/ACTION_SAME_LOCK dos.library/ACTION_SAME_LOCK NAME ACTION_SAME_LOCK - FSSameLock() SYNOPSIS int32 RESULT1 = FSSameLock(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *lock1, struct Lock *lock2); FUNCTION This action compares the targets of two locks, if they are on the same object, ACTION_SAME_LOCK will return DOSTRUE. If the two locks are on different objects, return FALSE. Both locks are guaranteed to never be NULL. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. lock1 - (struct Lock *) Pointer to the first object lock. lock2 - (struct Lock *) Pointer to the second object lock. RESULT1 - (int32) DOSTRUE / FALSE (DOSTRUE for same object) RESULT2 - (int32) Failure code if RESULT1==FALSE and an error occured. INPUTS (DosPacket method) dp_Type - (int32) ACTION_SAME_LOCK dp_Arg1 - (BPTR) lock 1. dp_Arg2 - (BPTR) lock 2. RESULT1 - (int32) DOSTRUE / FALSE (DOSTRUE for same object) RESULT2 - (int32) Failure code if RESULT1==FALSE and an error occured. SEE ALSO IDOS->SameLock() dos.library/ACTION_SEEK dos.library/ACTION_SEEK NAME ACTION_SEEK (DEPRECATED) FUNCTION This function is deprecated. Use ACTION_CHANGE_FILE_POSITION64. When this old packet is unsupported, dos.library will fall forward to using ACTION_CHANGE_FILE_POSITION64 and ACTION_GET_FILE_POSITION64 (for the returncode), so you need to support those instead. Your filesystem can still be probed by this packet, but should always return 0 with result2 set to ERROR_ACTION_NOT_KNOWN to cause the dos.library emulation to handle lagacy callers. This packet sets the current file position. The new position is is relative to either the beginning of the file (OFFSET_BEGINNING), the end of the file (OFFSET_END), or the current file position (OFFSET_CURRENT), depending on the mode set in dp_Arg3. Note that dp_Arg2 can be negative. The handler returns the previous file position in RESULT1. Any attempt to seek past the end of the file will result in an error and will leave the current file position in an unknown location. INPUTS dp_Type - (int32) ACTION_SEEK dp_Arg1 - (APTR) fh_Arg1 field of the opened struct FileHandle. dp_Arg2 - (int32) New Position. dp_Arg3 - (int32) Mode.(OFFSET_BEGINNING,OFFSET_END,or OFFSET_CURRENT) dp_Arg4 - (struct FileHandle *) filehandle. (added 53.49, previously 0) RESULT1 - (int32) Old position, -1 indicates an error. RESULT2 - (int32) Failure code if RESULT1 == -1 NOTES For this packet, the dos.library will also accept 0 as a failing return code but only if the secondary result is set to ERROR_ACTION_NOT_KNOWN. SEE ALSO IDOS->Seek() dos.library/ACTION_SERIALIZE_DISK dos.library/ACTION_SERIALIZE_DISK NAME ACTION_SERIALIZE_DISK - FSSerialize() SYNOPSIS int32 RESULT1 = FSSerialize(struct FileSystemVectorPort *fsvp, int32 *result2); FUNCTION This function will tell a file system to serialize the current volume. This is typically done by updating the creation date in the disk data and by also updating the current datestamp for the volume node. At the discretion of the filesystem programmer, other serializing features may be employed internally, but the minimum action required is setting the current datestamp in the volume node. DOS uses the volume node datestamp as a second tier check against volume name collisions in the doslist. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_SERIALIZE_DISK dp_Arg1 - 0 RESULT1 - (int32) Success/Failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->Serialize() dos.library/ACTION_SET_BLOCKING_MODE dos.library/ACTION_SET_BLOCKING_MODE NAME ACTION_SET_BLOCKING_MODE FUNCTION Interactive streams (console) or pipes may buffer input or output until a certain condition arrives (e.g. the user hitting the 'Return' key or the pipe reader consuming more data). A pending read/write access may be delayed until that condition has arrived, blocking the application which is trying to perform it. The purpose of the ACTION_SET_BLOCKING_MODE packet is to control how the handler is to respond to a read/write access: either accept it and delay its processing if necessary (blocking mode) or return it immediately if it cannot be processed immediately (non-blocking mode). new_mode -- Selects the new blocking (SBM_BLOCKING) or non-blocking (SBM_NON_BLOCKING) mode the stream should operate in. result -- This is either the old blocking mode in effect before you selected the new mode, or 0 or -1 (see notes). If it is 0, then the new mode could not be selected, possibly because the handler does not support the ACTION_SET_BLOCKING_MODE packet. If a stream is operating in non-blocking mode and the requested Read() or Write() action cannot be performed immediately, it will return with result == -1 and RESULT2 == ERROR_WOULD_BLOCK. INPUTS dp_Type - (int32) ACTION_SET_BLOCKING_MODE dp_Arg1 - (APTR) filehandle->fh_Arg1 dp_Arg2 - (int32) new_mode dp_Arg3 - (struct FileHandle *) filehandle (added 53.49, previously 0) RESULT1 - (int32) Result = old_mode, 0 or -1 RESULT2 - (int32) Secondary code. SEE ALSO IDOS->SetBlockingMode() dos.library/ACTION_SET_COMMENT dos.library/ACTION_SET_COMMENT NAME ACTION_SET_COMMENT - FSSetComment() SYNOPSIS int32 RESULT1 = FSSetComment(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name, CONST_STRPTR comment); FUNCTION This action sets the comment string for a filesystem object. If the object does not exist or any other error occured then FALSE will be returned in RESULT1 with the failure code in RESULT2. The comment string was limited to 79 characters in earlier filesystems, this is no longer the case, note that not all filesystems will support comments, for example, NFS usually will not, or the size of comment supported may vary, but they can not exceed 255 bytes, so be prepared to handle this size. To handle the 'rel' and 'name' parameters correctly, use the example code shown in ACTION_LOCATE_OBJECT / FSLock() autodoc. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' reference lock. name - (CONST_STRPTR) Pointer to the object name.(no path component) comment - (CONST_STRPTR) Pointer to the comment string. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_SET_COMMENT dp_Arg1 - 0 dp_Arg2 - (BPTR) Lock to which dp_Arg3 is relative. dp_Arg3 - (BSTR) Name of object relative to dp_Arg2 dp_Arg4 - (BSTR) New comment string. dp_Arg5 - (BSTR) Nametype - name format indicator value. if(dp_Arg3==dp_Arg5) then all BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->SetComment(), ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_SET_DATE dos.library/ACTION_SET_DATE NAME ACTION_SET_DATE - FSSetDate() SYNOPSIS int32 RESULT1 = FSSetDate(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name, const struct DateStamp *date); FUNCTION This action allows an application to set an object's creation date. Sets the date for a file or directory. To handle the 'rel' and 'name' parameters correctly, use the example code shown in ACTION_LOCATE_OBJECT / FSLock() autodoc. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' reference dir lock. name - (CONST_STRPTR) Pointer to the object name.(no path component) date - (const struct DateStamp *) Pointer to a struct DateStamp. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_SET_DATE dp_Arg1 - 0 dp_Arg2 - (BPTR) Lock to which dp_Arg3 is relative. dp_Arg3 - (BSTR) Name of object relative to dp_Arg2 dp_Arg4 - (struct DateStamp *) Datestamp to set object to. (Not a BPTR). dp_Arg5 - (BSTR) Nametype - name format indicator value. if(dp_Arg3==dp_Arg5) then all BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->SetDate() dos.library/ACTION_SET_FILE_SIZE dos.library/ACTION_SET_FILE_SIZE NAME ACTION_SET_FILE_SIZE (DEPRECATED) FUNCTION This function is deprecated. Use ACTION_CHANGE_FILE_SIZE64 from V50+ If this old packet is unsupported, dos.library will fall forward to using ACTION_CHANGE_FILE_SIZE64, so you need to support that instead. This function is used to change the physical size of an opened file. dp_Arg2, the new end-of-file position, is relative to either the current file position (OFFSET_CURRENT), the beginning of the file (OFFSET_BEGINNING), or the end of the file (OFFSET_END), depending on the mode set in dp_Arg3. The current file position will not change unless the current file position is past the new end-of-file position. In this case, the new file position will move to the new end of the file. If there are other open file handles on this file, ACTION_SET_FILE_SIZE sets the end-of-file for these alternate file handles to either their respective current file position or to the new end-of-file position of the file handle in dp_Arg1, whichever makes the file appear longer. 'offset' is the new end of file location based on mode. 'mode' is one of: OFFSET_CURRENT, OFFSET_BEGINNING or OFFSET_END. INPUTS dp_Type - (int32) ACTION_SET_FILE_SIZE dp_Arg1 - (APTR) fh_Arg1 field of the opened struct FileHandle. dp_Arg2 - (int32) offset. dp_Arg3 - (int32) mode. dp_Arg4 - (APTR) struct FileHandle pointer (added 53.49, previously 0) RESULT1 - (int32) Newsize - position of new end-of-file or -1 for error. RESULT2 - (int32) Failure code if RESULT1 == -1 NOTES For this packet, the dos.library will also accept 0 as a failing return code but only if the secondary result is set to ERROR_ACTION_NOT_KNOWN. SEE ALSO IDOS->SetFileSize() dos.library/ACTION_SET_OWNER dos.library/ACTION_SET_OWNER NAME ACTION_SET_OWNER (DEPRECATED) FUNCTION This action is deprecated. Now use ACTION_SET_OWNER_INFO Do not implement this packet when ACTION_SET_OWNER_INFO is supported by the handler, because dos.library V53+ will emulate this function. Note that handlers may still be probed by this old packet but should always return RESULT1=FALSE, and RESULT2=ERROR_ACTION_NOT_KNOWN so the dos.library emulation code will take over. SetOwner() sets the owner information for the file or directory. This value is a 32-bit value that is normally split into 16 bits of owner user id (bits 31-16), and 16 bits of owner group id (bits 15-0). However, other than returning them as shown by Examine()/ ExNext()/ExAll(), the filesystem take no interest in the values. These are primarily for use by networking software (clients and hosts), in conjunction with the FIBF_OTR_xxx and FIBF_GRP_xxx protection bits. INPUTS dp_Type - (int32) ACTION_SET_OWNER dp_Arg1 - 0 dp_Arg2 - (BPTR) Relative Lock dp_Arg3 - (BSTR) name dp_Arg4 - (uint32) owner mask dp_Arg5 - (BSTR) nametype - name format indicator value. if(dp_Arg3==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES From V53.87 DOS will emulate ACTION_SET_OWNER by using the new packet ACTION_SET_OWNER_INFO (or the filesystem vector-port function) if the handler in question does not support this old ACTION_SET_OWNER packet. SEE ALSO IDOS->SetOwner(), IDOS->SetOwnerInfo(), dos.library/ACTION_SET_OWNER_INFO dos.library/ACTION_SET_OWNER_INFO NAME ACTION_SET_OWNER_INFO - FSSetGroup() - FSSetOwner() int32 RESULT1 = FSSetGroup(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name, uint32 mask); int32 RESULT1 = FSSetOwner(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name, uint32 mask); FUNCTION These functions replace the deprecated V39 ACTION_SET_OWNER. It allows the caller to set the owner or group information for the file or directory. A filesystem takes no interest in the values other than storing (and returning) them, for the respective filesystem objects, these are primarily for use by networking software (clients and hosts), in conjunction with the ExamineData EXDF_OTR_xxx and EXDF_GRP_xxx protection bits. Some filesystems previously stored the mask for both group and owner in the same 32 bit longword as; owner uid (31:16) and group id (15:0) if the filesystem has room, these two masks should be stored in their own separate 32 bit wide fields. For dospacket calls, there are two tags of interest to the filesystem, these are; OI_OwnerUID (uint32) -- Owner UID value. Set the value for the objects UID field. By not specifying this tag, the UID field will remain unchanged. OI_OwnerGID (uint32) -- Group GID value. Set the value for the objects GID field. By not specifying this tag, the GID field will remain unchanged. There are no default values for these tags, the caller must specify at least one of OI_OwnerUID or OI_OwnerGID tags, or it shall fail. The dos.library will check for this before calling the filesystem as well as testing for a NULL 'tags' arg. The dos.library source tags are NOT filtered from the taglist, so the filesystem must ignore all tags other than the two listed above. For vector-port callers, FSSetGroup() and/or FSSetOwner() will be called depending on the arguments supplied by the caller. To handle the 'rel' and 'name' parameters correctly, use the example code shown in ACTION_LOCATE_OBJECT / FSLock() autodoc. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' reference dir lock. name - (CONST_STRPTR) Pointer to the object name.(no path component) mask - (uint32) The group or owner bitmask, each are 32 bits wide. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_SET_OWNER_INFO dp_Arg1 - (BPTR) Relative Lock dp_Arg2 - (BSTR) name dp_Arg3 - (struct TagItem *) taglist dp_Arg4 - 0 dp_Arg5 - (BSTR) nametype - name format indicator value. if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->SetOwnerInfo(), ACTION_INHIBIT_DOS_LONGPATH_HANDLING dos.library/ACTION_SET_PROTECT dos.library/ACTION_SET_PROTECT NAME ACTION_SET_PROTECT - FSSetProtection() SYNOPSIS int32 RESULT1 = FSSetProtection(struct FileSystemVectorPort *fsvp, int32 *result2, struct Lock *rel, CONST_STRPTR name, uint32 mask); FUNCTION This action allows the caller to modify the protection bits of a file or directory. The 4 lowest order bits (RWED) are a bit peculiar due to ancient compatibility issues. If their respective bit is set, that operation is not allowed (i.e. if a file's delete bit is set the file is not deleteable). By default, objects are created with a mask value of EXDF_DEFAULT, this is currently a value of zero for a mask that defines an object as; (R)eadable, (W)riteable, (E)xecutable, (D)eletable. Any operation which modifies an object is required to clear the (A)rchive bit, this includes at least the immediate parent directory for the modified object. For files, the (R)ead, (W)rite and (D)elete bits control filesystem functionality for their respective operations. For directories, the (D)elete bit is the ONLY bit that has any defined function for filesystems, the other bits shall not have any affect on any filesystem operations until new functionality is formally ratified. Do NOT cook-up your own (however well intensioned) functionality for the undocumented bits, it is guaranteed to break application compatibility. To handle the 'rel' and 'name' parameters correctly, use the example code shown in ACTION_LOCATE_OBJECT / FSLock() autodoc. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. rel - (struct Lock *) Pointer to the 'name' reference dir lock. name - (CONST_STRPTR) Pointer to the object name.(no path component) mask - (uint32) Protection bitmask. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_SET_PROTECT dp_Arg1 - 0 dp_Arg2 - (BPTR) Lock to which dp_Arg3 is relative. dp_Arg3 - (BSTR) Name of object (relative to dp_Arg2) dp_Arg4 - (uint32) Mask of new protection bits. dp_Arg5 - (BSTR) Nametype - name format indicator value. if(dp_Arg3==dp_Arg5) then BSTR's are guaranteed to be nul-terminated. (53.23) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE) (FALSE on error). RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->SetProtection() dos.library/ACTION_SHUTDOWN dos.library/ACTION_SHUTDOWN NAME ACTION_SHUTDOWN FUNCTION This action dismounts a filesystem or handler. The IDOS->DismountDevice() function will send ACTION_SHUTDOWN to the filesystem/handler message port, if the handler does not support this packet, it should reply immediately with FALSE in RESULT1 and the code ERROR_ACTION_NOT_KNOWN in RESULT2. If the handler supports ACTION_SHUTDOWN, it must NOT reply to this packet until after the following operations have completed... The filesystem should remove the volume node from the DosList and issue a diskchange to notify everyone interested. ( NB: Example code for this is available at the start of this file. ) The filesystem should then obtain the dos library lockhandler public message port with; port = IExec->FindPort("dos_lock_handler_port"); then send the ACTION_COLLECT packets to it, (with IDOS->DoPkt()), one packet for each and every public lock, filehandle or notifyrequest that the filesystem still has currently active. These will be collected by the lockhandler which will effectively service any remaining packets being sent to them. The lockhander will currently respond to these packets successfully: ACTION_FREE_LOCK, ACTION_END, ACTION_REMOVE_NOTIFY, ACTION_INHIBIT, and of course ACTION_COLLECT. All remaining packets will respond with ERROR_ACTION_NOT_KNOWN. This is currently sufficient to allow the original opener to be able to close/free the particular object in question, when the original opener decides to do so. The format for sending an ACTION_COLLECT packet to the lockhandler is; dp_Type=ACTION_COLLECT, dp_Arg1=ID_COLLECT_xxx, dp_Arg2=(APTR)object. The ID_COLLECT_xxx values identify the type of object being collected and are described next. Locks; For public DOS ONLY allocated Locks, (via AllocDosObject()) dp_Arg1=ID_COLLECT_LOCK, dp_Arg2=(struct Lock *). The lockhandler will set the fl->fl_Port field to point to the DOS lockhandlers message port, the fl->Volume will be set to point to a special private volume node. It will then respond with DOSTRUE. If the Lock structure was NOT allocated by AllocDosObject(), this packet will be rejected and fail with FALSE being returned. FileHandles; For public DOS ONLY allocated FileHandles, (via AllocDosObject()) dp_Arg1=ID_COLLECT_FILEHANDLE, dp_Arg2=(struct FileHandle *). NB: The filesystem will need to store the original FileHandle pointer somewhere in the internal filesystem lock structure so it can be accessed from the lock list upon dismounting. The lockhandler will set the fh->fh_MsgPort field to point to the DOS lockhandler's port, it will also set fh->fh_Arg1 to point back to the struct FileHandle, it will then respond with DOSTRUE. Note that the filesystem will still need to free its internal lock structure memory after handing over the public filehandle structure. Notifications; For public DOS ONLY allocated NotifyRequests, (via AllocDosObject()) dp_Arg1=ID_COLLECT_NOTIFICATION, dp_Arg2=(struct NotifyRequest *). NB: The filesystem will need to store the original NotifyRequest structure pointer which was supplied by DOS when called with ACTION_ADD_NOTIFY to start the notification. The lockhandler will set only the nreq->nr_Handler field to point to the lockhandlers message port, it will then respond with DOSTRUE. Once all public objects have been successfull relinquished to the DOS lockhandler, the filesystem should clean up any remaining allocations just as if the object had been freed/unlocked/closed normally, with the exception of the public Lock/FileHandle/NotifyStruct structure itself which now belongs to the DOS lockhandler, this will be deallocated when someone attempts to UnLock/Free/End this object. Note that a filehandle represents the public filehandle structure with an associated internal private filesystem lock structure. The private internal lock structure must still be freed by the filesystem after handing over the filehandle structure to the DOS lockhandler. Finally, after the above has completed, the filesystem must reply to the initial ACTION_SHUTDOWN packet with a DOSTRUE and zero in Result2, then the filesystem task may exit, otherwise if something went wrong, reply FALSE with a suitable error code in Result2. Only replying to the original ACTION_SHUTDOWN packet will release the caller of the IDOS->DismountDevice() function, doing so is mandatory. If a successfull result is obtained, the IDOS->DismountDevice() function may only then remove and free the DOS device node if requested by the function caller with option flag DMDF_REMOVEDEVICE being set. If DMDF_KEEPDEVICE is specified, the device node will not be removed. The dn_Port field of the device node will always be cleared by DOS on a successful operation, but only if it still points to the dying handler message port, before returning from IDOS->DisMountDevice(). LOCKHANDLER FUNCTIONALITY. Knowing about the internal functionality of the DOS lockhandler is not required to be able to use it, nevertheless, the following information will document how it currently works incase access is required for debugging or statistical purposes. The DOS lockhandler stores collected objects in nodes on an exec list. The associated node fields that are currently in use, are as follows: Node structure field ln_Type holds the ID_COLLECT_xxx value. Node structure field ln_Name holds the object pointer as an APTR. Deleting a node from the DOS lockhandlers internal list requires only that the ln_Name and ln_Type members be set to zero. The lockhandler will take care of freeing or reusing the empty node/s. Do not attempt to Remove() or deallocate the memory yourself. The list must be accessed ONLY when inhibited, do this by sending an ACTION_INHIBIT,DOSTRUE to the lockhandler first, it will respond with a DOSTRUE value and return a pointer to its struct List in Result2, a zero value will be returned in Result2 when uninhibiting. All lockhandler list access is suspended during inhibit, don't loiter. Each successfull DosPacket transaction to the DOS lockhandler will cause a DosList change signal to occur, this may be used to cause a list monitor program to auto-refresh. See; IDOS->NotifyDosListChange(). INPUTS (DosPacket method) dp_Type - (int32) ACTION_SHUTDOWN dp_Arg1 - 0 RESULT1 - (int32) Success/Failure indicator, (FALSE on failure.) RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->DisMountDevice(), ACTION_COLLECT dos.library/ACTION_SINGLE_CHARACTER_MODE dos.library/ACTION_SINGLE_CHARACTER_MODE NAME ACTION_SINGLE_CHARACTER_MODE (was ACTION_SCREEN_MODE) FUNCTION This used to be called ACTION_SCREEN_MODE which is really a misnomer, so it was changed to ACTION_SINGLE_CHARACTER_MODE to reflect the real purpose of this function. What this packet does is to change the console's mode of operation between single character (mode==1) and line buffered (mode==0) input mode. In other words, switches the console to and from RAW mode, a 'mode' of TRUE indicates the unprocessed, raw (char) mode, while a 'mode' of FALSE indicates the processed, "cooked" (line) mode. INPUTS dp_Type - (int32) ACTION_SINGLE_CHARACTER_MODE dp_Arg1 - (int32) mode. (1 or 0) RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->SetMode() dos.library/ACTION_STARTUP dos.library/ACTION_STARTUP NAME ACTION_STARTUP FUNCTION This action has the same value as ACTION_NIL (0) however it is always used by dos.library as a handshake mechanism to start up handlers and filesystems. When dos.library sends this packet to the process message port of a handler or filesystem, the following sequence will occur. (1) DOS will first check if this handler is already running by looking to see if devicenode->dn_Port != NULL then (6), otherwise ... (2) DOS library will check if the module requires loading by looking to see if the devicenode->dn_SegList != ZERO, if it is already loaded then (4), otherwise ... (3) DOS will obtain the loadable name from devicenode->dn_Handler, if that is valid, DOS will attempt to IDOS->LoadSeg() it, once loaded, the devicenode->dn_SegList will be initialised. (4) A DOS process will be started for this handler device, the name of this process will default to the same as the devicenode->dn_Name, from V53.102 handler version information is appended to the name. (5) The ACTION_STARTUP packet will be sent to the default process message port, DOS will wait for the packet to return. (6) The message port will be extracted from either the result of the startup packet (from dp_Arg4) or the devicenode->dn_Port. (See notes below). INPUTS dp_Type - (int32) ACTION_STARTUP dp_Arg1 - (BSTR) MKBADDR(startup_name); //can be an extended BSTR dp_Arg2 - (uint32) devicenode->dn_Startup; dp_Arg3 - (BPTR) MKBADDR(devicenode); dp_Arg4 - (APTR) 0; // this may return an alternate messageport. dp_Arg5 - (BSTR) dp_Arg1; // == extended BSTR + nul-terminated.(53.23) dp_Arg6 - 0; dp_Arg7 - 0; RESULT1 - (int32) BOOLEAN Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES Upon success and before the handler returns the startup packet, dp_Arg4 can have special use as an optional secondary return message port pointer to allow handlers to keep their process message port for sync DOS I/O, therefore DOS will preferably use dp_Arg4 as the result struct MsgPort if it is returned as non-zero, otherwise the devicenode->dn_Port will be used, which implies that the dn_Port should be initialised by the handler upon startup (in normal usage), otherwise a new handler process will be started for every new device access thereafter, (like CON: does). If the filesystem or handler sees dp_Arg5==dp_Arg1 then the BSTR strings passed in this startup packet are guaranteed to be nul-terminated and may also be longer that 255 chars. (available from DOS 53.23+) The 'startup_name' passed in dp_Arg1 is a copy of the string passed into the GetDeviceProcFlags() call by the process accessing the device. SEE ALSO IDOS->GetDeviceProcFlags() dos.library/ACTION_WAIT_CHAR dos.library/ACTION_WAIT_CHAR NAME ACTION_WAIT_CHAR FUNCTION If a character is available to be read from 'file' within the time (in microseconds) indicated by 'timeout', ACTION_WAIT_CHAR returns DOSTRUE. If a character is available, you can use ACTION_READ to read it. Note that ACTION_WAIT_CHAR is only valid if the I/O stream is connected to a virtual terminal device. If a character is not available within 'timeout', FALSE is returned. INPUTS dp_Type - (int32) ACTION_WAIT_CHAR dp_Arg1 - (uint32) Timeout in microseconds. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE NOTES Only stream handlers support this functionality, filesystems do not. SEE ALSO IDOS->WaitForChar(), IDOS->IsFileSystem() dos.library/ACTION_WAIT_FOR_DATA dos.library/ACTION_WAIT_FOR_DATA NAME ACTION_WAIT_FOR_DATA FUNCTION ACTION_WAIT_FOR_DATA is a superset of ACTION_WAIT_CHAR in that it can check if a stream is ready to supply or accept more data. This is typically used for pipes which may not be ready to deliver more data to the other end at all times. data_direction -- A combination of the flags WFDF_READ and WFDF_WRITE. If WFDF_READ is set, then the handler will check if data is ready to be read. If WFDF_WRITE is set, then the handler will check if it can accept further data to be written. If none of these flags is set, the ACTION_WAIT_FOR_DATA will return immediately. timeout -- Number of milliseconds to wait until the conditions set by the data_direction parameter are satisfied. A value of 0 is a valid choice. (1000mS = 1 second) INPUTS dp_Type - (int32) ACTION_WAIT_FOR_DATA dp_Arg1 - (APTR) filehandle->fh_Arg1 dp_Arg2 - (int32) data_direction dp_Arg3 - (int32) timeout dp_Arg4 - (struct FileHandle *) filehandle (added 53.49, previously 0) RESULT1 - (int32) Result -- A combination of the flags WFDF_READ and WFDF_WRITE or 0 if the timeout has elapsed without any of the requested conditions being satisfied. Also, if RESULT1=0 and RESULT2=ERROR_ACTION_NOT_KNOWN then the handler does not understand this request. RESULT2 - (int32) Failure code if RESULT1 == 0 NOTES Only stream handlers support this functionality, filesystems do not. SEE ALSO IDOS->WaitForData(), IDOS->IsFileSystemPort() dos.library/ACTION_WRITE dos.library/ACTION_WRITE NAME ACTION_WRITE - FSWrite() SYNOPSIS int32 RESULT1 = FSWrite(struct FileSystemVectorPort *fsvp, int32 *result2, struct FileHandle *file, STRPTR buffer, int32 numchar); FUNCTION This function copies data into the file at the current position. The file is automatically extended when the write passes the end of the file. The handler returns the number of bytes written in RESULT1 which should always be the same as the "numchar' value, with zero in RESULT2. When any failure occurs, the handler returns -1 in RESULT1 along with the appropriate error code in RESULT2. (See dos/ErrorReport() for info) The handler is also responsible for checking the usual issues, such as checking for attempts to write to a write protected file, or attempting to write on a write protected volume, or writing to a full disk. In the case of a failure, the handler does not update the current file position (although the file may have been extended and some data overwritten) so that an application can safely retry the operation. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. file - (struct FileHandle *) Pointer to the open file handle. buffer - (STRPTR) Pointer to the buffer to be written. numchar - (int32) Number of bytes to write. RESULT1 - (int32) Number of bytes actually written or -1 on error. RESULT2 - (int32) Failure code if RESULT1 != numchar. INPUTS (DosPacket method) dp_Type - (int32) ACTION_WRITE dp_Arg1 - (APTR) fh_Arg1 field of the opened struct FileHandle. dp_Arg2 - (APTR) Buffer to write to the file handle. dp_Arg3 - (int32) Number of bytes to write. dp_Arg4 - (struct FileHandle *) FileHandle. (added 53.49, previously 0) RESULT1 - (int32) Number of bytes actually written or -1 on error. RESULT2 - (int32) Failure code if RESULT1 != dp_Arg3 SEE ALSO IDOS->Write(); dos.library/ACTION_WRITE_PROTECT dos.library/ACTION_WRITE_PROTECT NAME ACTION_WRITE_PROTECT - FSWriteProtect() SYNOPSIS int32 RESULT1 = FSWriteProtect(struct FileSystemVectorPort *fsvp, int32 *result2, int32 wp_state, uint32 passkey); FUNCTION This action allows an application to change the write protect flag of a disk (if possible - applications cannot write to floppies that have their write-protect tabs set). This action is primarily intended to allow write-protecting non-removable media such as hard disks. The value in wp_state toggles the write status. The 32-bit passkey allows a program to prevent other programs from unwrite-protecting a disk. To unlock a disk, 'passkey' must match the passkey of the action that locked the disk, unless the disk was locked with a passkey value of 0. In this case, no passkey is necessary to unlock the disk. On failure with a passkey mismatch, return RESULT1=FALSE along with RESULT2 = ERROR_BAD_NUMBER. INPUTS (FileSystemVectorPort method) fsvp - (struct FileSystemVectorPort *) Pointer to the vector port. result2 - (int32 *) Pointer to the storage area for RESULT2. wp_state - (int32) Inhibit state, (DOSTRUE/FALSE). passkey - (uint32) Passkey value, (use zero for no passkey). RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE INPUTS (DosPacket method) dp_Type - (int32) ACTION_WRITE_PROTECT dp_Arg1 - (int32) DOSTRUE/FALSE (write protect/un-write protect). dp_Arg2 - (int32) 32 Bit pass key. RESULT1 - (int32) Success/failure (DOSTRUE/FALSE), FALSE on error. RESULT2 - (int32) Failure code if RESULT1 == FALSE SEE ALSO IDOS->WriteProtectVolume()