This page is "http://www.cs.tut.fi/~albert/BOAR/dos.html".

dos.library Functions

All dos.library calls use C calling conventions (parameters on stack).

Where not otherwise stated, functions return DOS_FALSE for failure, in which case more information about the reason for the failure can be obtained using the IoErr() call. PrintFault() can be used to display a human-readable error string.

One reason for a failed call may be that the handler in question does not implement or recognize the action. In these cases IoErr() should return ERROR_NOT_IMPLEMENTED or ERROR_ACTION_NOT_KNOWN.

Section Index

Simple Input/Output and File Operations

APTR Open( const char *filename, ULONG mode );

Open filename for reading (MODE_OLDFILE), for writing (MODE_NEWFILE) or for both read and write (MODE_READWRITE). Returns NULL if the file can't be opened in the desired mode.

MODE_NEWFILE will create a new file and delete the old version if any exists. MODE_READWRITE will open an existing file for writing. Open in this mode will fail if the file does not already exist or the file is already opened by anyone else.

LONG Close( APTR handle );

Closes a file handle previously opened by Open(). May return DOS_FALSE if the close fails. Normally this can only happen on storage media error.

LONG Read( APTR handle, char *buffer, LONG size );

Reads data from a handle and places it into the buffer. size is the number of characters to read. Read() returns the number of characters actually read, 0 for an EOF condition and negative values if there was a fatal error (such as protection violation).

Interactive handlers are allowed to return less data than requested. This does not mean that there is no more data to be read ! In raw mode Read() does not block if WaitForChar() returned DOS_TRUE.

LONG Write( APTR handle, const char *buffer, LONG size );

Writes size characters from the buffer to the file handle. Returns the number of characters actually written or 0 for an error.

LONG Seek( APTR handle, LONG offset, LONG direction );

Changes the current reading/writing position in the file. direction specifies the way offset is interpreted. For OFFSET_CURRENT it is relative to the current position, with OFFSET_BEGINNING it is relative to the beginning of the file and with OFFSET_END relative to the end of the file.

If you try to seek out of the bounds of the file, DOS_FALSE (0) is returned. If the seek was successful, DOS_TRUE (non-0) is returned and the old position is returned as a secondary error, which can be read with IoErr().

LONG IoErr( void );

Returns the secondary result code from the last dos.library call. Normally the code returned identifies why the previous operation failed (if it did fail). However, the secondary result can also be used to return useful information, such as the number of characters waiting (WaitForChar()) or the old seek position (Seek()).

void SetIoErr( LONG code );

Sets the secondary result code of the current process.

LONG PrintFault( LONG code, const char *header );

Displays a human-readable version of the secondary result code. header is a string that is printed after the error message and is usually the filename used in the previously failed call.

Special Streams

APTR Input( void );

Returns the current standard input stream handle.

APTR Output( void );

Returns the current standard output stream handle.

APTR Error( void );

Returns the current standard error stream handle.

LONG SetMode( APTR handle, LONG mode );

Changes the operating mode of the handle. Different handlers may have different ideas about how to interpret mode, but all handlers should use 0 (MODE_CONSOLE) for console editing mode and -1 for raw mode.

The serial handler translates single newlines and carriage returns to CR+LF pairs, even in raw mode. To bypass this, use SetMode(handle, MODE_RAW | MODE_NOCRLF);.

LONG IsInteractive( APTR handle );

Returns DOS_TRUE for interactive streams.

LONG WaitForChar( APTR handle, ULONG time );

Waits maximum of time ticks for a character to arrive. Works only with interactive streams (in raw mode). If characters are already waiting, returns immediately. Returns DOS_FALSE if the timeout is reached.

After a successful WaitForChar() IoErr() can be used to find out about how many characters (at least) are waiting to be read. The next Read() will NOT block if there are any characters waiting and the stream is in raw mode.

File Manipulation Functions

LONG DeleteFile( const char *file );

Deletes a file or a directory. If there are locks held to the file or directory, or the directory is not empty, the delete fails (DOS_FALSE is returned).

LONG Rename( const char *oldName, const char *newName );

Changes a file/directory's name from oldName to newName. If newName exists, but it can't be deleted Rename() fails. Full paths can be used, but renaming across different handlers may not be supported. However, moving files inside the same filesystem is possible.

APTR SetComment( const char *name, const char *comment );

Attaches a comment string to a file or directory. comment may be upto 79 characters long. Longer comment strings will be silently truncated.

APTR SetProtection( const char *name, ULONG protection );

Sets the protection flags for a file or directory. Can only be used by the owner of the directory entry.

ULONG SetOwner( const char *name, ULONG ownerinfo );

Sets the owner ID and group ID for a file. User ID is the top 16 bits in ownerinfo, while group ID uses the lower 16 bits. Can only be used by the owner of the directory entry.

LONG SetFileDate( const char *name, const struct DateStamp *date );

Sets the creation date of a file. Can only be used by the owner of the directory entry.

File Locking and Directory Functions

APTR Lock( const char *name, LONG mode );

Creates a shared (ACCESS_READ) or an exclusive lock (ACCESS_WRITE) on a file or a directory. Only one exclusive lock can be held on an object simultaneously. If the object can't be locked, NULL is returned.

LONG UnLock( APTR lock );

Releases a previously created lock.

APTR DupLock( APTR oldLock );

Makes a duplicate of a lock.

LONG SameLock( APTR lockA, APTR lockB );

Returns DOS_TRUE if the locks are for the same object, DOS_FALSE otherwise.

LONG Examine( APTR lock, struct FileInfoBlock *fib );

Fills in the structure with information about the locked object. Returns DOS_FALSE for failure.

LONG ExNext( APTR lock, struct FileInfoBlock *fib );

Fills in the structure with information about the next object in the directory. Returns DOS_FALSE for error. If IoErr() reports ERROR_NO_MORE_ENTRIES, the previous directory entry was the last one.

Examine() should be always called with the lock before using ExNext() or the results may be uncorrect. If the original lock was for a file, ExNext() always fails.

LONG ExamineEnd( APTR lock, struct FileInfoBlock *fib );

Ends the directory scanning.

APTR CreateDir( const char *name );

Creates a directory and returns an exclusive lock to it. If the directory can't be created, NULL is returned.

APTR CurrentDir( APTR newCurrentDir );

Changes the current working directory to the directory referenced by the lock newCurrentDir.

Returns NULL if the lock is not suitable or for example the directory does not have execute permissions for the user. If successful, returns the lock to the old current directory. This lock should be UnLock():ed by the user.

APTR ParentDir( APTR lock );

Returns a lock to the parent directory of an object lock. If the lock is for a root directory of a handler, NULL is returned.

Disk Functions

LONG Format( const char *disk, ULONG flags );

Formats a disk. The disk must be 'owned' by the user.

LONG DiskInfo( APTR lock, struct InfoData *info );

Fills in the structure with information about the disk the object referenced by the lock resides in.

LONG Relabel( const char *handler, const char *newname );

Gives a new name to a disk.

LONG IsFileSystem( const char *handlername );

Determines if a handler is a filesystem or a special handler.

Program Loading and Running

struct SegList *ROMLoadSeg( const char *name );

Loads a relocatable program named name from the internal list of commands, initializes and relocates the code and data segments and reserves a BSS section. If name is not found or there is an error (memory allocation or relocation failed), NULL is returned.

struct SegList *LoadSeg( const char *name );

Loads a relocatable program from a file name, initializes and relocates the code and data segments and reserves a BSS section. If name is not found or there is an error (memory allocation or relocation failed), NULL is returned.

LONG UnLoadSeg( struct SegList *segList );

Unloads code, data and BSS created by ROMLoadSeg() or LoadSeg(). It is safe to call UnLoadSeg() with a NULL segList.

LONG RunCommand( struct SegList *segList, ULONG stacksize, const char *args, ULONG arglen );

Synchronously runs a program previously loaded by ROMLoadSeg() or LoadSeg().

struct Process *CreateProc( const char *name, LONG pri, struct SegList *segList, ULONG stackSize, const char *argString );

Creates a new process and run a program previously loaded by ROMLoadSeg() or LoadSeg().

struct Process *CreateNewProcTags( ULONG tag1type, ... );

Creates a new process and run a program previously loaded by ROMLoadSeg() or LoadSeg().

Many kinds of parameters can be set if the default values do not fit the purpose:

Example: 
	CreateNewProcTags( NP_Seglist, segl,
			   NP_Name, "MyChild",
			   NP_CopyVars, FALSE,
			   TAG_DONE );

LONG SystemTags( const char *command, ULONG tag1type, ... );

Currently always fails (not implemented).

Local Variables

LONG DeleteVar( const char *name, ULONG flags );

Remove a variable.

struct LocalVar *FindVar( const char *name, ULONG flags );

Find a variable.

LONG GetVar( const char *name, char *buffer, LONG bufsize, ULONG flags );

Get the contents of a variable name. If the variable does not exist, -1 is returned, otherwise the size of the value is returned. bufsize+1 is returned if the value does not fit into the buffer.

LONG SetVar( const char *name, const char *buffer, LONG size, ULONG flags );

Create or change a variable name contents. If you are creating string variables (as opposed to binary), size should be strlen(buffer)+1. flags is used to differentiate local variables (0) and aliases (VAR_ALIAS).

DOS Packets

struct DevProc *GetDeviceProc( const char *handler, struct DevProc *old );

Get an instance of a handlers messageport and lock of the handlers root directory (if a filesystem). Pass NULL for old, or the structure previously returned by GetDeviceProc() to get the next handler/lock combination in a multiassign.

void FreeDeviceProc( struct DevProc *dev );

Free the structure allocated by GetDeviceProc().

struct MsgPort *DeviceProc( const char *handler );

Obsolete: DO NOT USE! Use GetDeviceProc() and FreeDeviceProc() instead.

LONG DoPkt4( struct MsgPort *port, LONG type, ULONG arg1, ULONG arg2, ULONG arg3, ULONG arg4 );

Sends a DOSPacket to a message port. All I/O operations are performed by sending and receiving DOSPackets (DoPkt4() is called internally). type is the action to be performed, arg1..4 are the arguments.

LONG DoPkt4Safe( const char *handler, LONG type, ULONG arg1, ULONG arg2, ULONG arg3, ULONG arg4 );

Sends a DOSPacket to a named handler.

Assigns

LONG AssignLock( const char *assign, APTR lock );

Creates an assign (logical device) with the name assign and makes it point to the supplied lock. Any previous assign with the same name is first discarded.

If the call succeeds, the lock becomes the property of the dos.library and may not be freed or otherwise used by the program.

LONG AssignLate( const char *assign, const char *path );

Creates a late-binding assign. The supplied path is resolved only when the assign is first accessed. If path does not point to a valid object, access through the assign fails and resolving is again attempted when the assign is next accessed. Any previous assign with the same name is discarded.

LONG AssignAdd( const char *assign, APTR lock );

Adds objects to an already existing assign.

If the call succeeds, the lock becomes the property of the dos.library and may not be freed or otherwise used by the program.

Also, assigns can be created to point to files also, but it may be quite confusing to see them used that way.

Output Formatting

LONG PrintFmt( va_list ap, void *fp, int (*cf)(int, void *), const char *fmt );

Format a string using a callback function (cf). fp is passed to the callback.

LONG FPrintF( APTR handle, const char *fmt, ... );

Prints formatted strings to a filehandle. Currently this is VERY slow, because each character in the format string is displayed separately and each Write() causes at least two context switches.

Until buffering is added you should only use format commands in the format string to get the best performace. 

	FPrintF(Output(), "%s%d\n", "Hello ", count);

LONG PrintF( const char *fmt, ... );

Prints formatted strings to the standard output stream. Currently VERY slow.

Miscellaneous

struct ArgList *ParseArgs( const char *line );

Parses an argument string into the ANSI-C format, where each argument is in its own string.

void FreeArgs( struct ArgList *args );

Frees the structure created by ParseArgs.

void Delay( ULONG ticks );

Makes the process wait for at least ticks-1 number of 1/100 seconds.

Function Index