Home / Autodocs / dos.library
NAME
- Open
-
Open a file for input or output
SYNOPSIS
file = Open( name, accessMode )
D0 D1 D2
BPTR Open(STRPTR, LONG)
D0 D1 D2
BPTR Open(STRPTR, LONG)
FUNCTION
The named file is opened and a FileHandle returned. The 'accessMode' defines what happens before the file is opened:
Regardless of which file access mode you choose, both read and write operations will be possible for the FileHandle. Just because there is a mode by the name of MODE_READWRITE, it does not mean that MODE_NEWFILE and MODE_OLDFILE will restrict file operations to either reading or writing.
Write access may be denied if the storage medium is not writable or if the access policy for the file system denies the access. Some handlers may only support write or read operations, but not necessarily both. For example, the PRT: device is intended for sending output to the printer but not to receive responses from the printer.
The 'name' can be a file name (optionally prefaced by a device name), a simple device such as "NIL:", a window specification such as CON: or RAW: followed by window parameters, or "*", representing the current console whose port is found in the pr_ConsoleTask field of the Process calling Open(). From V36 onwards, the current console can also be reached at "CONSOLE:" or "CONSOLE:spec", where the interpretation of the specification behind "CONSOLE:" is specific to the handler implementing the console. The ROM con-handler ignores this optional string.
If the file cannot be opened for any reason, the value returned will be zero, and a secondary error code will be available by calling the function IoErr().
Opening an existing file or creating a new file 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.
- MODE_NEWFILE
-
Creates a new file if the file does not yet exist. If the file already exists, it will be truncated.
MODE_NEWFILE implies exclusive access to the file.
- MODE_OLDFILE
-
Opens an existing file.
MODE_OLDFILE implies shared access to the file.
- MODE_READWRITE
-
Creates a new file if the file does not yet exist. If the file already exists, it will not be truncated, in contrast to the MODE_NEWFILE access mode.
MODE_READWRITE implies shared access to the file.
Regardless of which file access mode you choose, both read and write operations will be possible for the FileHandle. Just because there is a mode by the name of MODE_READWRITE, it does not mean that MODE_NEWFILE and MODE_OLDFILE will restrict file operations to either reading or writing.
Write access may be denied if the storage medium is not writable or if the access policy for the file system denies the access. Some handlers may only support write or read operations, but not necessarily both. For example, the PRT: device is intended for sending output to the printer but not to receive responses from the printer.
The 'name' can be a file name (optionally prefaced by a device name), a simple device such as "NIL:", a window specification such as CON: or RAW: followed by window parameters, or "*", representing the current console whose port is found in the pr_ConsoleTask field of the Process calling Open(). From V36 onwards, the current console can also be reached at "CONSOLE:" or "CONSOLE:spec", where the interpretation of the specification behind "CONSOLE:" is specific to the handler implementing the console. The ROM con-handler ignores this optional string.
If the file cannot be opened for any reason, the value returned will be zero, and a secondary error code will be available by calling the function IoErr().
Opening an existing file or creating a new file 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.
INPUTS
- name
-
pointer to a null-terminated string
- accessMode
-
integer; must be one of MODE_OLDFILE, MODE_NEWFILE or MODE_READWRITE
RESULT
- file
-
BCPL pointer to a FileHandle; NULL is returned for failure. Call IoErr() to find out why Open() failed.
WARNING
It is unsafe to call Open() with a path name longer than 255 characters. The path name is likely to be truncated, which may lead to unpredictable behaviour (V36). Furthermore, soft link resolution for the path may corrupt the path buffer contents (V36).
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. For example, 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 create or truncate a file whose name exceeds the maximum name length will end up truncating the wrong file. For example, opening "supercalifragilisticexpialidocious.info" with MODE_NEWFILE may end up truncating a different file 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 truncating 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.
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. For example, 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 create or truncate a file whose name exceeds the maximum name length will end up truncating the wrong file. For example, opening "supercalifragilisticexpialidocious.info" with MODE_NEWFILE may end up truncating a different file 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 truncating 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.
NOTES
The Open() function returns a BCPL pointer to a FileHandle, which is defined in the <dos/dosextens.h> header file. As with the FileLock (see the Lock() documentation), only a short restricted public version of the FileHandle is defined. Most of the data structure members have undocumented purposes and/or are misnamed, as well as feature the wrong type of information.
The FileHandle structure looks as follows:
The FileHandle structure members serve the following purposes:
fh_Link (struct Message *)
Generally, you need not access any of these FileHandle structure members. The dos.library Read(), Write(), Seek(), Close() and IsInteractive() functions provide a complete set of robust file operations on top of data structures which dos.library manages almost entirely on its own.
The FileHandle structure looks as follows:
struct FileHandle {
};
struct Message *fh_Link;
struct MsgPort *fh_Port;
struct MsgPort *fh_Type;
BPTR fh_Buf;
LONG fh_Pos;
LONG fh_End;
LONG fh_Funcs;
LONG fh_Func2;
LONG fh_Func3;
LONG fh_Args;
LONG fh_Arg2;
struct MsgPort *fh_Port;
struct MsgPort *fh_Type;
BPTR fh_Buf;
LONG fh_Pos;
LONG fh_End;
LONG fh_Funcs;
LONG fh_Func2;
LONG fh_Func3;
LONG fh_Args;
LONG fh_Arg2;
fh_Link (struct Message *)
This is a reserved structure member which is used by dos.library and should not be modified. It does not contain a pointer to a Message, and it is not used for linking FileHandles or Messages.
fh_Port (struct MsgPort *)
This structure member indicates whether the associated file is interactive, such as the CON: and RAW: devices. It does not contain a pointer to a MsgPort. What it does contain is a boolean value which is either NULL or non-zero. The fh_Port structure member is used by the IsInteractive() function.
fh_Type (struct MsgPort *)
This is the MsgPort address of the file system Process responsible for this file. If you call the Close(), Read() and Write() functions, for example, this is where the command messages will be sent which implement these commands.
- Note:
-
The fh_Type member may be NULL, such as is the case for the NIL: device. If you must access the fh_Type structure member, always first check if it is not NULL!
- fh_Buf (BPTR)
-
See next
- fh_Pos (LONG)
-
See next
- fh_End (LONG)
-
FileHandles are created with a minute buffer which can be filled with data, to be retrieved with the Read() operation. These structure members manage the read position as well as the amount of data left in the buffer. Beyond this feature, which is used internally by dos.library, the buffer may be managed (size, mode of buffering) with the SetVBuf() function.
- fh_Funcs (LONG)
-
See next
- fh_Func2 (LONG)
-
See next
- fh_Func3 (LONG)
-
These three members contain 32 bit pointers to the functions which are used by the buffered read and write functions (FGetC(), FRead(), FPutC(), FWrite()) and Close() operations.
- fh_Args (LONG)
-
See next
- fh_Args2 (LONG)
-
This information is used by the file system to find out about its internal representation of the file data structures. It is initialized when the Open() function is called.
Generally, you need not access any of these FileHandle structure members. The dos.library Read(), Write(), Seek(), Close() and IsInteractive() functions provide a complete set of robust file operations on top of data structures which dos.library manages almost entirely on its own.
NOTES
The file access mode MODE_NEWFILE cannot be used to overwrite an existing directory. It can only be used to truncate an existing file.
All file access modes imply a Lock:
You may change the Lock implied by the file you opened later, using the ChangeMode() function.
You can obtain a duplicate of the Lock implied by the file you opened, provided it is a shared Lock (opened with MODE_OLDFILE or MODE_READWRITE), through the DupLockFromFH() function.
A file may be protected against writing and deletion, which limits what the file access mode MODE_NEWFILE can achieve. The file system may deny truncating an existing file if it is protected against deletion, or it may deny it if the file is protected against writing. The actual behaviour is inconsistent among file systems.
Prior to the introduction of the FastFileSystem (V34), the Amiga ROM file system ignored the file write/delete protection if Open(name, MODE_NEWFILE) was used.
Writing to a write-protected file may be denied by the file system, regardless of whether it was opened with the MODE_NEWFILE, MODE_OLDFILE and MODE_READWRITE access modes. Prior to the introduction of the FastFileSystem (V34), the Amiga ROM file system ignored the file write protection if Write() was used.
Opening a linked file has different effects if the file in question is a soft link, rather than a hard link. A soft link is resolved transparently when you use Open() on it. If the resolution attempt is successful, you will have opened the file which the soft link would reference. Hence, you are not opening the soft link but its target.
A Process may share the same file with a different Process, by opening it with the MODE_READWRITE mode, creating the file if it does not yet exist. You may need to coordinate read and write accesses to the file for consistency. The advisory record locking functions LockRecord(), UnLockRecord(), etc. can provide the means to accomplish this.
All file access modes are somewhat misnamed. The DosPacket types underlying the file open access modes say a little more about the intent behind them:
All file access modes imply a Lock:
- MODE_NEWFILE
-
Will use an EXCLUSIVE_LOCK
- MODE_OLDFILE
-
Will use a SHARED_LOCK
- MODE_READWRITE
-
Will use a SHARED_LOCK
You may change the Lock implied by the file you opened later, using the ChangeMode() function.
You can obtain a duplicate of the Lock implied by the file you opened, provided it is a shared Lock (opened with MODE_OLDFILE or MODE_READWRITE), through the DupLockFromFH() function.
A file may be protected against writing and deletion, which limits what the file access mode MODE_NEWFILE can achieve. The file system may deny truncating an existing file if it is protected against deletion, or it may deny it if the file is protected against writing. The actual behaviour is inconsistent among file systems.
Prior to the introduction of the FastFileSystem (V34), the Amiga ROM file system ignored the file write/delete protection if Open(name, MODE_NEWFILE) was used.
Writing to a write-protected file may be denied by the file system, regardless of whether it was opened with the MODE_NEWFILE, MODE_OLDFILE and MODE_READWRITE access modes. Prior to the introduction of the FastFileSystem (V34), the Amiga ROM file system ignored the file write protection if Write() was used.
Opening a linked file has different effects if the file in question is a soft link, rather than a hard link. A soft link is resolved transparently when you use Open() on it. If the resolution attempt is successful, you will have opened the file which the soft link would reference. Hence, you are not opening the soft link but its target.
A Process may share the same file with a different Process, by opening it with the MODE_READWRITE mode, creating the file if it does not yet exist. You may need to coordinate read and write accesses to the file for consistency. The advisory record locking functions LockRecord(), UnLockRecord(), etc. can provide the means to accomplish this.
All file access modes are somewhat misnamed. The DosPacket types underlying the file open access modes say a little more about the intent behind them:
- MODE_NEWFILE
-
The DosPacket type ACTION_FINDOUTPUT suggests that data is to be stored or transmitted.
- MODE_OLDFILE
-
The DosPacket type ACTION_FINDINPUT suggests that data will be read or received and then processed.
- MODE_READWRITE
-
The DosPacket type ACTION_FINDUPDATE suggests that existing data is to be modified or augmented.
EXAMPLE
The following example code shows how a front-end for the Open()
may be implemented, permitting path names for files 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,
{
}
/* Create a file or open an existing file, even if the total length of
BPTR
MyOpen(CONST TEXT * path_name, LONG access_mode)
{
}
may be implemented, permitting path names for files 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;
/* Create a file or open an existing file, even if the total length of
* the path name exceeds 255 characters. Returns a BPTR to the file
* handle of the open file, or NULL for failure.
*/
* handle of the open file, or NULL for failure.
*/
MyOpen(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 file = (BPTR)NULL;
BPTR lock;
path_name_len = strlen(path_name);
/* If this is not a file system, such as "NIL:" or "CON:", or if
if (IsFileSystem(path_name) && path_name_len > 255)
{
}
else
{
}
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 file = (BPTR)NULL;
BPTR lock;
path_name_len = strlen(path_name);
/* If this is not a file system, such as "NIL:" or "CON:", or if
* the path name does not exceed 255 characters, just use the
* standard Open() function instead.
*/
* standard Open() function instead.
*/
{
/* 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)
{
}
* 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
{
/* 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
if (reference_dir != (BPTR)NULL)
/* Unless this is the final part of the path
if (position != -1)
{
}
else
{
}
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
{
else
{
/* Time to open that file. */
file = Open(part, access_mode);
lock = (BPTR)NULL;
file = Open(part, access_mode);
lock = (BPTR)NULL;
if (reference_dir != (BPTR)NULL)
break;
UnLock(reference_dir);
reference_dir = lock;
else
{
file = Open(path_name, access_mode);
out:
BUGS
The 2nd edition AmigaDOS manual documentation for Open() would claim that MODE_READWRITE will open an existing file using an exclusive lock. This was never the case. MODE_READWRITE always uses a shared lock.
The 3rd edition AmigaDOS manual documentation for Open() would claim that a file opened using MODE_OLDFILE will open an existing file using a shared lock, which will change to an exclusive lock when writing to the file. This was never the case. The file would keep using a shared lock even if a write access was made.
If the name of the file or device to open is longer than 255 characters, V36 will clip the name. Instead of copying up to 255 characters, thereby truncating it, Open() will use an empty string instead. Fixed in V47.30.
If the path name contains soft links, V36 will fail to allocate enough memory for the entire soft link resolution result to fit, which can result in memory corruption. Fixed in V47.30.
The 3rd edition AmigaDOS manual documentation for Open() would claim that a file opened using MODE_OLDFILE will open an existing file using a shared lock, which will change to an exclusive lock when writing to the file. This was never the case. The file would keep using a shared lock even if a write access was made.
If the name of the file or device to open is longer than 255 characters, V36 will clip the name. Instead of copying up to 255 characters, thereby truncating it, Open() will use an empty string instead. Fixed in V47.30.
If the path name contains soft links, V36 will fail to allocate enough memory for the entire soft link resolution result to fit, which can result in memory corruption. Fixed in V47.30.