LockDosList

Locks the specified DOS Lists for use (V36)

Locks the DOS device list in preparation to walk the list. If the list is busy then this function will not return until it is available.

This function "nests": you can call it multiple times, and then must unlock it the same number of times. The 'dlist' returned is NOT a valid entry: it is a special value.

Note that for Kickstart 1.3 compatibility, LockDosList() also calls Forbid(). This was originally intended to be removed in Kickstart 2.0 (V36) but was never done.

flags

Flags stating which types of nodes you want to lock, and whether you want to modify the DosList or just want to search it (see <dos/dosextens.h> for the flag definitions):

These flags define the types of entries which you are interested in; you can combine these and search for/access multiple types:

• LDF_DEVICES
  
  
• LDF_VOLUMES
  
  
• LDF_ASSIGNS
  
  

You must choose an access mode; only one of these may be used:

• LDF_READ
  
  
• LDF_WRITE
  
  

Note:

LockDosList() and AttemptLockDosList() will return NULL if unsupported entry types are requested or if you ask for both read and write access at the same time.

dlist

Pointer to the head of the list or NULL. NOT a valid node!

The pointer returned by LockDosList() is NOT an actual DosList pointer - you should use on of the other DosEntry calls to get actual pointers to DosList structures (such as NextDosEntry()), passing the value returned by LockDosList() as the 'dlist' value.

LockDosList() and AttemptLockDosList() are built around SignalSemaphores. LDF_READ locking allows for shared access to be performed whereas LDF_WRITE locking enforces exclusive access.

Note for file system and handler writers: you should never call this function with LDF_WRITE, since it can deadlock you (if someone has it read-locked and they're trying to send you a packet). Use AttemptLockDosList() instead, and effectively busy-wait with delays for the list to be available. The other option is that you can spawn a Process to add the entry safely.

The name "DosList" stands for the collection of AmigaDOS devices which are stored in a list that requires special functions to access, modify or extend it with new entries:

AttemptLockDosList ()

see next

LockDosList ()

These functions provide exclusive access to the DosList.

You must call one of these before you may call the FindDosEntry(), NextDosEntry() and RemDosEntry() functions.

When calling AttemptLockDosList() make sure that the attempt has succeeded before you proceed!

UnLockDosList ()

This is the counterpart to the AttemptLockDosList() and LockDosList() functions. Call it when you no longer need the DosList to be locked.

MakeDosEntry ()

This function creates a new DosList entry, to be added with the AddDosEntry() function.

FreeDosEntry ()

This function frees a DosList entry which was created by MakeDosEntry() and which must have first been removed from the DosList, if it had been added in the first place.

AddDosEntry ()

This function will add a new DosEntry, provided it does not conflict with an existing entry.

RemDosEntry ()

This is the counterpart to the AddDosEntry() function.

NextDosEntry ()

This function will find the next DosList entry which matches the entry types you want to access.

FindDosEntry ()

This function will search the DosList for an entry whose name and entry type matches your requirements.

These special functions are provided for convenience and also to insure the consistency of the DosList, e.g. devices and assigns must have unique names.

The DosList entries are represented by a common data structure known as 'struct DosList' which is defined in the <dos/dosextens.h> header file. This common data structure encapsulates three different types of entries:

• A device, such as "df0:" or "RAM:" (DLT_DEVICE)
  
  
• A volume, such as "Work:" (DLT_VOLUME)
  
  
• An assign, such as "S:" or "LIBS:" (DLT_DIRECTORY, DLT_LATE or DLT_NONBINDING)
  
  

The common DosList data structure was introduced with the Native Developer Kit (NDK) for Workbench and Kickstart 1.3. Prior to that, there were three data structures which covered this ground which you might still find in legacy code. You should not use these in modern code and make use of 'struct DosList' instead.

For reference, these are the (only) data structures which were available during the Kickstart 1.1-1.2 era:

DLT_DEVICE

DLT_VOLUME

DLT_DIRECTORY

Note that directly modifying the DosList contents is strongly discouraged. Use the dos.library (V36) functions which were provided for this purpose:

If you must examine DosList entries, here follows a description of the individual entry types.

Every DosList entry has the same size as the 'struct DevInfo' structure. Depending upon the entry type, not all of the data structure will be used. For example, a DLT_DIRECTORY type entry makes use only of the dol_Next, dol_Type, dol_Task, dol_Lock and dol_Name structure members, while a DLT_DEVICE type entry does not use the dol_Lock entry, it makes use of the dol_Handler, dol_StackSize, dol_Priority, dol_Startup, dol_SegList and dol_GlobVec members.

Note:

The following data structure descriptions omit the structure members which are not used by the respective directory entry type.

DLT_DEVICE (volume)

DLT_DIRECTORY (assign)

DLT_VOLUME (volume)

DLT_LATE (late-binding assign, V36)

DLT_NONBINDING (non-binding assign, V36)

AttemptLockDosList(), UnLockDosList(), Forbid(), NextDosEntry(), FindDosEntry(), utility.library/Stricmp