Home / Autodocs / dos.library
NAME
- Lock
-
Lock a directory or file
SYNOPSIS
lock = Lock( name, accessMode )
D0 D1 D2
BPTR Lock(STRPTR, LONG)
D0 D1 D2
BPTR Lock(STRPTR, LONG)
FUNCTION
A file system Lock on the file or directory 'name' is returned if possible.
If 'accessMode' is ACCESS_READ, the Lock is a shared read Lock; if 'accessMode' is ACCESS_WRITE then it is an exclusive write Lock. Do not use any other values for 'accessMode'.
If Lock() fails (that is, if it cannot obtain a file system Lock on the file or directory), it returns a zero.
Tricky assumptions about the internal format of a Lock are unwise, as are any attempts to use the FileLock fl_Link or fl_Access fields.
If 'accessMode' is ACCESS_READ, the Lock is a shared read Lock; if 'accessMode' is ACCESS_WRITE then it is an exclusive write Lock. Do not use any other values for 'accessMode'.
If Lock() fails (that is, if it cannot obtain a file system Lock on the file or directory), it returns a zero.
Tricky assumptions about the internal format of a Lock are unwise, as are any attempts to use the FileLock fl_Link or fl_Access fields.
INPUTS
- name
-
pointer to a NUL-terminated string
- accessMode
-
integer (either SHARED_LOCK or EXCLUSIVE_LOCK)
NOTES
File system operations such as Open(), Delete(), Rename(), CreateDir(), SetProtection() or LoadSeg() require that you provide the name or a path for the respective file, directory or link involved. This name or path is resolved relative to the current directory of the Process which calls these functions. The current directory of a Process is a Lock on a directory.
Locks are used not just for restricting and granting access to directories and directory entries, they also assist in resolving ambiguities in path names and provide a work-around for the 255 character limit on path names, which is present in almost every dos.library function.
For example, a volume name such as "Workbench" need not be unique, but by obtaining a shared Lock on the specific volume you can guarantee that the file system operations affect only it, and no other volume which shares the same name.
A Lock is an arbitration mechanism which permits either shared or exclusive access to a file, directory or volume. Successfully obtaining an exclusive Lock does not necessarily prevent other Processes from making use of the file system object the Lock refers to. An exclusive Lock on a directory may not keep programs from changing the contents of that directory, or from accessing the files and subdirectories within this directory. If anything, a Lock protects the file system object it references from deletion.
File systems do not allow for more than one exclusive Lock to be active for a file, directory or volume. If your Process asks for an exclusive Lock on an object for which you have already acquired an exclusive Lock, it will reject the attempt. The same is true for a file successfully opened using MODE_NEWFILE for which any attempt to obtain an exclusive Lock will be denied.
If you attempt to obtain a Lock, the request is generally granted or rejected immediately. Your Lock request is not delayed until it can be satisfied. There is generally no risk of deadlocking your Process by trying to obtain a Lock.
Successfully obtaining an exclusive Lock on a file, directory or volume does not imply that the associated volume is write-enabled.
The maximum length limit for path names of 255 characters can be worked around by preparsing the path, to break it down into sections which do not exceed the limit, then using Lock() on the last directory path component and repeating this process until a Lock() on the parent of the path's final part is found. See the EXAMPLE section for an example of how this may be done.
You may change the type of a Lock later by using the ChangeMode() function.
You may open a file based upon the Lock on that file using the OpenFromLock() function.
Obtaining a Lock on a linked file or directory has different effects if the object in question is a soft link, rather than a hard link. A soft link is resolved transparently when you obtain a Lock on it. If the resolution attempt is successful, you will have obtained a Lock on the object which the soft link would reference. Hence, you are not receiving a Lock on the soft link.
Obtaining a Lock on a file, directory or volume is subject to limitations imposed upon the path name passed in the 'name' parameter. If the path name length exceeds 255 characters, undefined behaviour is likely to follow. If you must use path names longer than 255 characters, please consult the EXAMPLE section. It contains a complete example which shows how to work around the path length limitation.
Locks are used not just for restricting and granting access to directories and directory entries, they also assist in resolving ambiguities in path names and provide a work-around for the 255 character limit on path names, which is present in almost every dos.library function.
For example, a volume name such as "Workbench" need not be unique, but by obtaining a shared Lock on the specific volume you can guarantee that the file system operations affect only it, and no other volume which shares the same name.
A Lock is an arbitration mechanism which permits either shared or exclusive access to a file, directory or volume. Successfully obtaining an exclusive Lock does not necessarily prevent other Processes from making use of the file system object the Lock refers to. An exclusive Lock on a directory may not keep programs from changing the contents of that directory, or from accessing the files and subdirectories within this directory. If anything, a Lock protects the file system object it references from deletion.
File systems do not allow for more than one exclusive Lock to be active for a file, directory or volume. If your Process asks for an exclusive Lock on an object for which you have already acquired an exclusive Lock, it will reject the attempt. The same is true for a file successfully opened using MODE_NEWFILE for which any attempt to obtain an exclusive Lock will be denied.
If you attempt to obtain a Lock, the request is generally granted or rejected immediately. Your Lock request is not delayed until it can be satisfied. There is generally no risk of deadlocking your Process by trying to obtain a Lock.
Successfully obtaining an exclusive Lock on a file, directory or volume does not imply that the associated volume is write-enabled.
The maximum length limit for path names of 255 characters can be worked around by preparsing the path, to break it down into sections which do not exceed the limit, then using Lock() on the last directory path component and repeating this process until a Lock() on the parent of the path's final part is found. See the EXAMPLE section for an example of how this may be done.
You may change the type of a Lock later by using the ChangeMode() function.
You may open a file based upon the Lock on that file using the OpenFromLock() function.
Obtaining a Lock on a linked file or directory has different effects if the object in question is a soft link, rather than a hard link. A soft link is resolved transparently when you obtain a Lock on it. If the resolution attempt is successful, you will have obtained a Lock on the object which the soft link would reference. Hence, you are not receiving a Lock on the soft link.
Obtaining a Lock on a file, directory or volume is subject to limitations imposed upon the path name passed in the 'name' parameter. If the path name length exceeds 255 characters, undefined behaviour is likely to follow. If you must use path names longer than 255 characters, please consult the EXAMPLE section. It contains a complete example which shows how to work around the path length limitation.
WARNING
The Amiga ROM file system as well as the RAM: file system will truncate path and file names to the maximum supported length instead of rejecting an overly long name with an error. A file with the unlikely name of "supercalifragilisticexpialidocious" (34 characters) may be considered identical to "supercalifragilisticexpialidoc" (30 characters).
There is a certain risk that by trying to obtain a Lock on a directory or directory entry whose name exceeds the maximum name length will end up accessing the wrong file. For example, trying to access "supercalifragilisticexpialidocious.info" may end up finding an existing directory entry whose name begins with the 30 character "short" "supercalifragilisticexpialidoc" instead. You may end up accessing the wrong file, or you may end up accessing the wrong type of directory entry which just so it happens has the "right" wrong name.
A possible workaround to detect the risk of accessing the wrong file involves the use of the SameLock() function. Begin by obtaining Locks on the "supercalifragilisticexpialidocious.info" icon file and its associated "supercalifragilisticexpialidocious" file. If these are distinct files, SameLock() will return LOCK_DIFFERENT. Check if the destination is what you expected, which should be a file and not a directory.
There is a certain risk that by trying to obtain a Lock on a directory or directory entry whose name exceeds the maximum name length will end up accessing the wrong file. For example, trying to access "supercalifragilisticexpialidocious.info" may end up finding an existing directory entry whose name begins with the 30 character "short" "supercalifragilisticexpialidoc" instead. You may end up accessing the wrong file, or you may end up accessing the wrong type of directory entry which just so it happens has the "right" wrong name.
A possible workaround to detect the risk of accessing the wrong file involves the use of the SameLock() function. Begin by obtaining Locks on the "supercalifragilisticexpialidocious.info" icon file and its associated "supercalifragilisticexpialidocious" file. If these are distinct files, SameLock() will return LOCK_DIFFERENT. Check if the destination is what you expected, which should be a file and not a directory.
EXAMPLE
The following example code shows how a front-end for the Lock()
function may be implemented, permitting path names to be used which
exceed the 255 character limit.
Please note that this example depends upon a function which parses
the path name and breaks it into its parts. This function is called
split_path() and is provided as part of the example code.
#include <proto/exec.h>
#include <proto/dos.h>
#include <string.h>
/* Split an AmigaDOS path name into a sequence of the individual path
LONG
split_path(CONST TEXT * path, TEXT * piece, LONG old_position,
{
}
/* Obtain a Lock() on an object, even if the total length of the
BPTR
MyLock(CONST TEXT * path_name, LONG access_mode)
{
}
function may be implemented, permitting path names to be used which
exceed the 255 character limit.
Please note that this example depends upon a function which parses
the path name and breaks it into its parts. This function is called
split_path() and is provided as part of the example code.
#include <proto/exec.h>
#include <proto/dos.h>
#include <string.h>
/* Split an AmigaDOS path name into a sequence of the individual path
* pieces. A path name may be empty, it may include a device name,
* a series of directory names or even "/" references to the
* parent directory and a file, directory or link name.
*
* split_path() is modeled on the SplitName() function in that it
* will copy each path piece into the supplied buffer, returning -1
* if the last piece has been copied. If -2 is returned, it means
* that the piece buffer is too short for the path piece to be
* copied.
*/
* a series of directory names or even "/" references to the
* parent directory and a file, directory or link name.
*
* split_path() is modeled on the SplitName() function in that it
* will copy each path piece into the supplied buffer, returning -1
* if the last piece has been copied. If -2 is returned, it means
* that the piece buffer is too short for the path piece to be
* copied.
*/
split_path(CONST TEXT * path, TEXT * piece, LONG old_position,
LONG size)
LONG length_copied = 0;
TEXT c;
/* The piece has to be NUL-terminated, which reduces the
size--;
/* Is the piece buffer too short? */
if (size <= 0)
/* Is this not an empty string, which stands for the
if (path[0] != '\0')
{
}
/* Make sure that the piece is NUL-terminated. */
(*piece) = '\0';
/* Is the separator character at the end of the path name,
if (path[length_copied] == '\0')
/* Continue path processing at this position. */
return old_position + length_copied;
TEXT c;
/* The piece has to be NUL-terminated, which reduces the
* usable size of the piece buffer.
*/
*/
/* Is the piece buffer too short? */
if (size <= 0)
return -2;
* current directory?
*/
*/
{
/* Adjust the starting position for scanning the path name,
path += old_position;
while (size-- >= 0)
{
}
/* Is the piece buffer too short? */
if (size < 0)
* which simplifies the loop below.
*/
*/
while (size-- >= 0)
{
c = path[length_copied];
/* Was this the end of the path name? */
if (c == '\0')
(*piece++) = c;
length_copied++;
/* Is this a device name separator, which may appear
if (c == ':' && old_position == 0)
{
}
/* Is there a '/' at the end of this path piece? */
else if (c == '/')
{
}
/* Was this the end of the path name? */
if (c == '\0')
break;
length_copied++;
/* Is this a device name separator, which may appear
* exactly once in a path name? Then we will have to
* keep it.
*/
* keep it.
*/
{
break;
/* Is there a '/' at the end of this path piece? */
else if (c == '/')
{
/* Is this in fact a single '/' which represents a
if (length_copied > 1)
{
}
break;
* reference to the parent directory? Then we need
* to keep it, otherwise it will have to be removed.
*/
* to keep it, otherwise it will have to be removed.
*/
{
/* Make sure that the trailing '/' will
piece--;
size++;
* be removed from the piece.
*/
*/
size++;
break;
/* Is the piece buffer too short? */
if (size < 0)
return -2;
/* Make sure that the piece is NUL-terminated. */
(*piece) = '\0';
/* Is the separator character at the end of the path name,
* or is this an empty string (with path_length == 0)?
*/
*/
return -1; /* This is the last piece of the path name. */
return old_position + length_copied;
/* Obtain a Lock() on an object, even if the total length of the
* path name exceeds 255 characters. Returns a BPTR to the Lock
* on the object or NULL for failure.
*/
* on the object or NULL for failure.
*/
MyLock(CONST TEXT * path_name, LONG access_mode)
{
TEXT part[256];
LONG path_name_len;
LONG len;
CONST TEXT * colon;
BPTR reference_dir = (BPTR)NULL;
BPTR old_current_dir = (BPTR)NULL;
LONG position = 0;
BPTR lock = (BPTR)NULL;
/* If the path name does not exceed a total length of 255
path_name_len = strlen(path_name);
if (path_name_len <= 255)
/* Does the path begin with a device name, or a reference
colon = strchr(path_name, ':');
if (colon != NULL)
{
}
/* Process the path name, one part at a time, relative
while (TRUE)
{
}
out:
LONG path_name_len;
LONG len;
CONST TEXT * colon;
BPTR reference_dir = (BPTR)NULL;
BPTR old_current_dir = (BPTR)NULL;
LONG position = 0;
BPTR lock = (BPTR)NULL;
/* If the path name does not exceed a total length of 255
* characters, just use the standard Lock() function.
*/
*/
if (path_name_len <= 255)
return Lock(path_name, access_mode);
* to the root directory of a volume?
*/
*/
if (colon != NULL)
{
/* We need to copy the name of the device, which must
len = (LONG)(colon - path_name) + 1;
if (len > 255)
{
}
/* Obtain a shared lock on the device or root
CopyMem(path_name, part, len);
part[len] = '\0';
reference_dir = Lock(part, SHARED_LOCK);
if (reference_dir == (BPTR)NULL)
/* We took care of the device or root directory name. */
path_name += len;
* not exceed 255 characters, including the colon
* character. Volume and device names should never
* exceed 30 characters, but accidents may still
* happen...
*/
* character. Volume and device names should never
* exceed 30 characters, but accidents may still
* happen...
*/
if (len > 255)
{
/* Obtain a shared lock on the device or root
* directory. We are using Lock() because it
* implies that the handler is a file system
* and not, for example, "NIL:" or "CON:".
*/
* implies that the handler is a file system
* and not, for example, "NIL:" or "CON:".
*/
part[len] = '\0';
reference_dir = Lock(part, SHARED_LOCK);
if (reference_dir == (BPTR)NULL)
goto out;
path_name += len;
/* Process the path name, one part at a time, relative
* to a Lock on its parent directory. This repeats
* until the last part of the path has been found.
* Each loop iteration will reuse the Lock of the
* previous iteration as the parent directory.
*/
* until the last part of the path has been found.
* Each loop iteration will reuse the Lock of the
* previous iteration as the parent directory.
*/
{
/* Obtain the next part of the path. */
position = split_path(path_name, part,
/* Is the part too long? */
if (position == -2)
{
}
/* Access the next part of the path relative to a specific
if (reference_dir != (BPTR)NULL)
/* If this is the final part of the path (split_path() will
lock = Lock(part,
if (reference_dir != (BPTR)NULL)
/* Stop as soon as we reach the end of the path or
if (position == -1 || lock == (BPTR)NULL)
/* Look at the next part of the remaining path. */
UnLock(reference_dir);
reference_dir = lock;
position = split_path(path_name, part,
position, sizeof(part));
if (position == -2)
{
/* Access the next part of the path relative to a specific
* directory? Otherwise, we use the current directory of
* the current Process. Because the current directory may
* be an exclusive lock we cannot conveniently fall back
* onto DupLock() or Lock("", SHARED_LOCK) instead.
*/
* the current Process. Because the current directory may
* be an exclusive lock we cannot conveniently fall back
* onto DupLock() or Lock("", SHARED_LOCK) instead.
*/
* return -1), we will need to use the requested access mode.
* Up until then it was safe to use shared locks.
*/
* Up until then it was safe to use shared locks.
*/
(position == -1) ? access_mode : SHARED_LOCK);
* if the Lock could not be obtained.
*/
*/
break;
UnLock(reference_dir);
reference_dir = lock;
out:
BUGS
File systems may not validate the access mode parameter other than by comparing it only against SHARED_LOCK or EXCLUSIVE_LOCK and then store the mode parameter value as is. If you accidentally use a mode value which is neither SHARED_LOCK nor EXCLUSIVE_LOCK you may discover that functions such as DupLock() or NameFromLock() will show unpredictable behaviour.
RESULT
- lock
-
BCPL pointer to a Lock if successful, or zero for failure
DATA STRUCTURES
The data structure underlying the Lock, as produced by the Lock() or DupLock() functions is defined in the <dos/dosextens.h> header file. It is called FileLock, and you can have FileLocks referencing any volume, directory or file. Hence, the name does not imply you will only find it applied to files.
Typically, dos.library functions will return a BCPL pointer to a FileLock. This BCPL pointer is used as a parameter for a function such as CurrentDir() or stored in a larger data structure.
A BCPL pointer cannot be directly used from 'C' or assembly language code and must be converted into a 32-bit address first, such as by using the BADDR() macro which is defined in the <dos/dos.h> header file:
The FileLock structure referenced by the pointer looks as follows:
Note that this data structure definition is merely the "public" portion of what a file system stores along with this information. The information stored with a FileLock is read-only, and different kinds of file systems are generally unable to share or exchange FileLocks. However, the Amiga ROM file system can share FileLocks and active FileHandles with other Amiga ROM file system Processes. This feature makes it possible, for example, to remove a floppy disk from one drive and insert it into a different drive and to keep using the files opened and Locks obtained when the disk was still present in the original drive.
The public FileLock structure members serve the following purposes:
Because FileLocks are associated with volumes and the DeviceList data structure, it makes sense to briefly cover what to find in a DeviceList entry.
Access to the DeviceList is performed by using the LockDosList() and NextDosEntry() functions. Each NextDosEntry() call returns the address of a DosList entry (or NULL), of which the DeviceList is a subset.
The DeviceList structure looks as follows:
The DeviceList structure members serve the following purposes:
Typically, dos.library functions will return a BCPL pointer to a FileLock. This BCPL pointer is used as a parameter for a function such as CurrentDir() or stored in a larger data structure.
A BCPL pointer cannot be directly used from 'C' or assembly language code and must be converted into a 32-bit address first, such as by using the BADDR() macro which is defined in the <dos/dos.h> header file:
struct FileLock * lock = BADDR(bcpl_pointer)
The name 'BADDR' stands for "BCPL address".
The FileLock structure referenced by the pointer looks as follows:
struct FileLock {
};
BPTR fl_Link;
LONG fl_Key;
LONG fl_Access;
BPTR fl_Volume;
struct MsgPort * fl_Task;
LONG fl_Key;
LONG fl_Access;
BPTR fl_Volume;
struct MsgPort * fl_Task;
The public FileLock structure members serve the following purposes:
- fl_Link (BPTR)
-
The file system which produced this FileLock keeps a list of all currently active locks. The list members are linked through the fl_Link member. Note that the file system which manages this Lock does not offer any means by which you could obtain the first Lock of the list. The fl_Link member therefore is of limited use.
- fl_Key (LONG)
-
The contents of the fl_Key field are typically related to what the Examine() function will store in the FileInfoBlock.fib_DiskKey structure member. This is, however, not guaranteed to be always the case. A file system is free to use the fl_Key field for its own needs, or even to not use it at all.
- fl_Access (LONG)
-
The file system may store here whether the Lock is of the shared (SHARED_LOCK) or the exclusive (EXCLUSIVE_LOCK) kind. This is, however, not guaranteed to be always the case. A file system is free to use the fl_Access field for its own needs, or even not to use it at all.
- fl_Volume (BPTR)
-
A FileLock is always associated with a volume, which represents the entirety of the file system data structures containing the directory or directory entry the Lock is referencing. The fl_Volume member is a BCPL pointer to the 'struct DeviceList' data structure (see <dos/dosextens.h>).
- fl_Task (struct MsgPort *)
-
This is the address of the MsgPort of the file system Process which created this FileLock structure and which manages the resources associated with it. Any operation performed on a FileLock or on a file name/path associated with a FileLock will involve sending a DosPacket to this MsgPort, with instructions on what should be done.
Because FileLocks are associated with volumes and the DeviceList data structure, it makes sense to briefly cover what to find in a DeviceList entry.
Access to the DeviceList is performed by using the LockDosList() and NextDosEntry() functions. Each NextDosEntry() call returns the address of a DosList entry (or NULL), of which the DeviceList is a subset.
The DeviceList structure looks as follows:
struct DeviceList {
};
BPTR dl_Next;
LONG dl_Type;
struct MsgPort * dl_Task;
BPTR dl_Lock;
struct DateStamp dl_VolumeDate;
BPTR dl_LockList;
LONG dl_DiskType;
LONG dl_unused;
BSTR dl_Name;
LONG dl_Type;
struct MsgPort * dl_Task;
BPTR dl_Lock;
struct DateStamp dl_VolumeDate;
BPTR dl_LockList;
LONG dl_DiskType;
LONG dl_unused;
BSTR dl_Name;
- dl_Next (BPTR)
-
Just like FileLocks, the DeviceList entries are linked through a BCPL pointer referencing the next following entry. A NULL pointer terminates the list.
- dl_Type (LONG)
-
This member is set to DLT_VOLUME for volumes (DeviceList).
- dl_Task (struct MsgPort *)
-
If the storage medium associated with this volume is currently present and a file system Process is tending to it, this will be the address of the file system MsgPort. Otherwise, dl_Task will be NULL.
- dl_Lock (BPTR)
-
The dl_Lock member is not used by the volume. The structure member is, along with dl_Next, dl_Type and dl_Task part of the common header data which all DosList entries share.
- dl_VolumeDate (struct DateStamp)
-
see next.
- dl_Name (BSTR)
-
The name and the date and time when the file system of the volume was initialized are supposed to uniquely identify a volume which shares the same name with others. Volume names need not be unique.
The dl_Name member contains a BCPL pointer to a string of characters, which begins with a length prefix byte. The length byte can specify a string length of 0..255 characters. The length byte is then followed by as many characters as indicated.
- dl_LockList (BPTR)
-
This member may contain a BCPL pointer to the first FileLock associated with this volume, but only if the file system responsible for them has given up its responsibility, such because the storage medium was removed. In such a case, the file system stores the FileLock list in the volume. It should also set the dl_Task member to NULL.
If a file system still actively manages the FileLock list, then dl_LockList will be NULL. Note that you cannot really tell precisely whether a file system is active and just has no FileLocks to manage yet, or whether a file system has given up responsibility for the FileLocks.
- dl_DiskType (LONG)
-
This member contains the same information as you would find in the InfoData.id_DiskType member. The most common practice among Amiga file systems is to store either one of the ID_DOS_DISK..ID_FASTDIR_FFS_DISK file system type IDs here (which is what the Amiga ROM file system does), or to use ID_DOS_DISK instead. For example, RAM: always uses and reports the disk type as ID_DOS_DISK.
- dl_unused (LONG)
-
In spite of its name, this member is being used by file systems which implement features such as file change notification. This feature requires that the supporting data structures which enable notification move with the FileLocks to the volume if the file system gives up responsibility for the FileLocks.
SEE ALSO
UnLock(), DupLock(), ChangeMode(), NameFromLock(), DupLockFromFH(), OpenFromLock(), <dos/dosextens.h>, LockDosList(), NextDosEntry(), MakeDosEntry()