dos.library Reference¶

Comprehensive function reference for dos.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/dos).

This page documents 161 functions of dos.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index¶

AbortPkt()
AddBuffers()
AddDosEntry()
AddPart()
AddSegment()
AllocDosObject()
AssignAdd()
AssignLate()
AssignLock()
AssignPath()
AttemptLockDosList()
ChangeMode()
CheckSignal()
Cli()
CliInitNewcli()
CliInitRun()
Close()
CompareDates()
CreateDir()
CreateNewProc()
CreateProc()
CurrentDir()
DateStamp()
DateToStr()
Delay()
DeleteFile()
DeleteVar()
DeviceProc()
DoPkt()
DoShellMethod()
DupLock()
DupLockFromFH()
EndNotify()
ErrorOutput()
ErrorReport()
ExAll()
ExAllEnd()
Examine()
ExamineFH()
Execute()
Exit()
ExNext()
Fault()
FGetC()
FGets()
FilePart()
FindArg()
FindCliProc()
FindDosEntry()
FindSegment()
FindVar()
Flush()
Format()
FPutC()
FPuts()
FRead()
FreeArgs()
FreeDeviceProc()
FreeDosEntry()
FreeDosObject()
FWrite()
GetArgStr()
GetConsoleTask()
GetCurrentDir()
GetCurrentDirName()
GetDeviceProc()
GetFileSysTask()
GetProgramDir()
GetProgramName()
GetPrompt()
GetVar()
Info()
Inhibit()
Input()
InternalLoadSeg()
InternalUnLoadSeg()
IoErr()
IsFileSystem()
IsInteractive()
LoadSeg()
Lock()
LockDosList()
LockRecord()
LockRecords()
MakeDosEntry()
MakeLink()
MatchEnd()
MatchFirst()
MatchNext()
MatchPattern()
MatchPatternNoCase()
MaxCli()
NameFromFH()
NameFromLock()
NewLoadSeg()
NextDosEntry()
Open()
OpenFromLock()
Output()
ParentDir()
ParentOfFH()
ParsePattern()
ParsePatternNoCase()
PathPart()
PrintFault()
PutErrStr()
PutStr()
Read()
ReadArgs()
ReadItem()
ReadLink()
Relabel()
RemAssignList()
RemDosEntry()
RemSegment()
Rename()
ReplyPkt()
RunCommand()
SameDevice()
SameLock()
ScanStackToken()
Seek()
SelectError()
SelectInput()
SelectOutput()
SendPkt()
SetArgStr()
SetComment()
SetConsoleTask()
SetCurrentDirName()
SetFileDate()
SetFileSize()
SetFileSysTask()
SetIoErr()
SetMode()
SetOwner()
SetProgramDir()
SetProgramName()
SetPrompt()
SetProtection()
SetVar()
SetVBuf()
SplitName()
StartNotify()
StrToDate()
StrToLong()
SystemTagList()
UnGetC()
UnLoadSeg()
UnLock()
UnLockDosList()
UnLockRecord()
UnLockRecords()
VFPrintf()
VFWritef()
VolumeRequestHook()
VPrintf()
WaitForChar()
WaitPkt()
Write()
WriteChars()

`AbortPkt()`¶

AbortPkt -- Aborts an asynchronous packet, if possible. (V36)

Synopsis

AbortPkt(port, pkt) D1 D2

void AbortPkt(MsgPort*,DosPacket*)

Function

This attempts to abort a packet sent earlier with SendPkt to a handler. There is no guarantee that any given handler will allow a packet to be aborted, or if it is aborted whether function requested completed first or completely. After calling AbortPkt(), you must wait for the packet to return before reusing it or deallocating it.

Inputs

port - port the packet was sent to pkt - the packet you wish aborted

Bugs

As of V37 to V47, this function does nothing, and it is unlikely that it will be ever implemented.

See also

SendPkt(), DoPkt(), WaitPkt()

`AddBuffers()`¶

AddBuffers -- Changes the number of buffers for a filesystem (V36)

Synopsis

success = AddBuffers(filesystem, number) D0 D1 D2

BOOL AddBuffers(STRPTR, LONG)

Function

Adds buffers to a filesystem. If it succeeds, the number of current buffers is returned in IoErr(). Note that "number" may be negative. The amount of memory used per buffer, and any limits on the number of buffers, are dependant on the filesystem in question. If the call succeeds, the number of buffers in use on the filesystem will be returned by IoErr().

Inputs

filesystem - Name of device to add buffers to (with ':'). number - Number of buffers to add. May be negative.

Results

success - Success or failure of command.

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.

The V37 and before ROM filesystem doesn't return success, it returns
the number of buffers.  The best way to test for this is to consider
0 (FALSE) failure, -1 (DOSTRUE) to mean that IoErr() will have the
number of buffers, and any other positive value to be the number of
buffers.  It may be fixed in some future ROM revision.

See also

IoErr()

`AddDosEntry()`¶

AddDosEntry -- Add a Dos List entry to the lists (V36)

Synopsis

success = AddDosEntry(dlist) D0 D1

LONG AddDosEntry(DosList*)

Function

Adds a device, volume or assign to the dos devicelist. Can fail if it conflicts with an existing entry (such as another assign to the same name or another device of the same name). Volume nodes with different dates and the same name CAN be added, or with names that conflict with devices or assigns. Note: the dos list does NOT have to be locked to call this. Do not access dlist after adding unless you have locked the Dos Device list.

An additional note concerning calling this from within a handler:
in order to avoid deadlocks, your handler must either be multi-
threaded, or it must attempt to lock the list before calling this
function.  The code would look something like this:

if (AttemptLockDosList(LDF_xxx|LDF_WRITE))
{
    rc = AddDosEntry(...);
    UnLockDosList(LDF_xxx|LDF_WRITE);
}

If AttemptLockDosList() fails (i.e. it's locked already), check for
messages at your filesystem port (don't wait!) and try the
AttemptLockDosList() again.

Inputs

dlist - Device list entry to be added.

Results

success - Success/Failure indicator

`AddPart()`¶

AddPart -- Appends a file/dir to the end of a path (V36)

Synopsis

success = AddPart( dirname, filename, size ) D0 D1 D2 D3

BOOL AddPart( STRPTR, STRPTR, ULONG )

Function

This function adds a file, directory, or subpath name to a directory path name taking into account any required separator characters. If filename is a fully-qualified path it will totally replace the current value of dirname.

Inputs

dirname - the path to add a file/directory name to. filename - the filename or directory name to add. May be a relative pathname from the current directory (example: foo/bar). Can deal with leading '/'(s), indicating one directory up per '/', or with a ':', indicating it's relative to the root of the appropriate volume. size - size in bytes of the space allocated for dirname. Must not be 0.

Results

success - non-zero for ok, FALSE if the buffer would have overflowed. If an overflow would have occured, dirname will not be changed.

Bugs

Doesn't check if a subpath is legal (i.e. doesn't check for ':'s) and doesn't handle leading '/'s in 2.0 through 2.02 (V36). V37 fixes this, allowing filename to be any path, including absolute.

See also

Filepart(), PathPart()

`AddSegment()`¶

AddSegment - Adds a resident segment to the resident list (V36)

Synopsis

success = AddSegment(name, seglist, type) D0 D1 D2 D3

BOOL AddSegment(STRPTR, BPTR, LONG)

Function

Adds a segment to the Dos resident list, with the specified Seglist and type (stored in seg_UC - normally 0). NOTE: currently unused types may cause it to interpret other registers (d4-?) as additional parameters in the future.

Do NOT build Segment structures yourself!

Inputs

name - name for the segment seglist - Dos seglist of code for segment type - initial usecount, normally 0

Results

success - success or failure

`AllocDosObject()`¶

AllocDosObject -- Creates a dos object (V36)

Synopsis

ptr = AllocDosObject(type, tags) D0 D1 D2

void *AllocDosObject(ULONG,TagItem*)

ptr = AllocDosObjectTagList(type, tags) D0 D1 D2

void *AllocDosObjectTagList(ULONG,TagItem*)

ptr = AllocDosObjectTags(type, Tag1, ...)

void *AllocDosObjectTags(ULONG, ULONG, ...)

Function

Create one of several dos objects, initializes it, and returns it to you. Note the DOS_STDPKT returns a pointer to the sp_Pkt of the structure.

This function may be called by a task for all types and tags defined
in the V37 includes. As V47, the following dos objects can be
created, see <dos/dos.h>:

DOS_FILEHANDLE   a struct FileHandle, see <dos/dosextens.h>.
         Only few people should require this. Note that
         the dos.library uses a a somewhat larger internal
         structure that is intentially not documented.
DOS_EXALLCONTROL a struct ExAllControl that is used for ExAll,
         see <dos/exall.h>. You MUST use this call to
         allocate this structure.
DOS_FIB      a struct FileInfoBlock, see <dos/dos.h>.
DOS_STDPKT   a struct StandardPacket, see <dos/dosextens.h>
DOS_CLI      a struct CommandLineInterface, see also
         <dos/dosextens.h>. Note that the shell uses
         internally a somewhat larger structure, and
         only shells equipped with this larger structure
         will be able to handle DoShellMethod().
         You must use AllocDosObject() to create a valid
         CLI structure, creating this structure yourself
         is no longer acceptable.
DOS_RDARGS   A struct RDArgs, see <dos/rdargs.h>

Inputs

type - type of object requested tags - pointer to taglist with additional information

Results

packet - pointer to the object or NULL

Bugs

Before V39, DOS_CLI should be used with care since FreeDosObject() can't free it.

See also

FreeDosObject()

`AssignAdd()`¶

AssignAdd -- Adds a lock to an assign for multi-directory assigns (V36)

Synopsis

success = AssignAdd(name,lock) D0 D1 D2

BOOL AssignAdd(STRPTR,BPTR)

Function

Adds a lock to an assign, making or adding to a multi-directory assign. Note that this only will succeed on an assign created with AssignLock(), or an assign created with AssignLate() which has been resolved (converted into a AssignLock()-assign).

NOTE: you should not use the lock in any way after making this call
successfully.  It becomes the part of the assign, and will be unlocked
by the system when the assign is removed.  If you need to keep the
lock, pass a lock from DupLock() to AssignLock().

Inputs

name - Name of device to assign lock to (without trailing ':') lock - Lock associated with the assigned name

Results

success - Success/failure indicator. On failure, the lock is not unlocked.

`AssignLate()`¶

AssignLate -- Creates an assignment to a specified path later (V36)

Synopsis

success = AssignLate(name,path) D0 D1 D2

BOOL AssignLate(STRPTR,STRPTR)

Function

Sets up a assignment that is expanded upon the FIRST reference to the name. The path (a string) would be attached to the node. When the name is referenced (Open("FOO:xyzzy"...), the string will be used to determine where to set the assign to, and if the directory can be locked, the assign will act from that point on as if it had been created by AssignLock().

A major advantage is assigning things to unmounted volumes, which
will be requested upon access (useful in startup sequences).

Inputs

name - Name of device to be assigned (without trailing ':') path - Name of late assignment to be resolved on the first reference.

Results

success - Success/failure indicator of the operation

`AssignLock()`¶

AssignLock -- Creates an assignment to a locked object (V36)

Synopsis

success = AssignLock(name,lock) D0 D1 D2

BOOL AssignLock(STRPTR,BPTR)

Function

Sets up an assign of a name to a given lock. Passing NULL for a lock cancels any outstanding assign to that name. If an assign entry of that name is already on the list, this routine replaces that entry. If an entry is on the list that conflicts with the new assign, then a failure code is returned.

NOTE: you should not use the lock in any way after making this call
successfully.  It becomes the assign, and will be unlocked by the
system when the assign is removed.  If you need to keep the lock,
pass a lock from DupLock() to AssignLock().

Inputs

name - Name of device to assign lock to (without trailing ':') lock - Lock associated with the assigned name

Results

success - Success/failure indicator. On failure, the lock is not unlocked.

`AssignPath()`¶

AssignPath -- Creates an assignment to a specified path (V36)

Synopsis

success = AssignPath(name,path) D0 D1 D2

BOOL AssignPath(STRPTR,STRPTR)

Function

Sets up a assignment that is expanded upon EACH reference to the name. This is implemented through a new device list type (DLT_ASSIGNPATH, or some such). The path (a string) would be attached to the node. When the name is referenced (Open("FOO:xyzzy"...), the string will be used to determine where to do the open. No permanent lock will be part of it. For example, you could AssignPath() c2: to df2:c, and references to c2: would go to df2:c, even if you change disks.

The other major advantage is assigning things to unmounted volumes,
which will be requested upon access (useful in startup sequences).

Inputs

name - Name of device to be assigned (without trailing ':') path - Name of late assignment to be resolved at each reference

Results

success - Success/failure indicator of the operation

`AttemptLockDosList()`¶

AttemptLockDosList -- Attempt to lock the Dos Lists for use (V36)

Synopsis

dlist = AttemptLockDosList(flags) D0 D1

DosList*AttemptLockDosList(ULONG)

Function

Locks the dos device list in preparation to walk the list. If the list is 'busy' then this routine will return NULL. See LockDosList() for more information.

Inputs

flags - Flags stating which types of nodes you want to lock.

Results

dlist - Pointer to the beginning of the list or NULL. Not a valid node!

Bugs

In V36 through V39.23 dos, this would return NULL or 0x00000001 for failure. Fixed in V39.24 dos (after kickstart 39.106).

`ChangeMode()`¶

ChangeMode - Change the current mode of a lock or filehandle (V36)

Synopsis

success = ChangeMode(type, object, newmode) D0 D1 D2 D3

BOOL ChangeMode(ULONG, BPTR, ULONG)

Function

This allows you to attempt to change the mode in use by a lock or filehandle. For example, you could attempt to turn a shared lock into an exclusive lock. The handler may well reject this request. Warning: if you use the wrong type for the object, the system may crash.

Inputs

type - Either CHANGE_FH or CHANGE_LOCK object - A lock or filehandle newmode - The new mode you want

Results

success - Boolean

Bugs

Did not work in 2.02 or before (V36). Works in V37. In the earlier versions, it can crash the machine.

Will crash in V36-V47.23 if type == CHANGE_FH and the object is
a file handle opened on "NIL:". Works in V47.24.

See also

Lock(), Open()

`CheckSignal()`¶

CheckSignal -- Checks for break signals (V36)

Synopsis

signals = CheckSignal(mask) D0 D1

ULONG CheckSignal(ULONG)

Function

This function checks to see if any signals specified in the mask have been set and if so, returns them. Otherwise it returns FALSE. All signals specified in mask will be cleared.

Inputs

mask - Signals to check for.

Results

signals - Signals specified in mask that were set.

`Cli()`¶

Cli -- Returns a pointer to the CLI structure of the process (V36)

Synopsis

cli_ptr = Cli() D0

CommandLineInterface*Cli(void)

Function

Returns a pointer to the CLI structure of the current process, or NULL if the process has no CLI structure.

Results

cli_ptr - pointer to the CLI structure, or NULL.

Notes

Manipulating or reading fields from the struct CommandLineInterface structure is discouraged, use the appropriate interface functions. Also, the shell may have additional parameters or functions that are not accessible through this structure, but only through DoShellMethod().

See also

DoShellMethod()

`CliInitNewcli()`¶

CliInitNewcli -- Set up a process to be a shell from initial packet OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

Synopsis

OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE flags = CliInitNewcli( packet ) D0 A0

LONG CliInitNewcli(DosPacket* ) OBSOLETE OBSOLETE OBSOLETE OBSOLETE OBSOLETE

Function

As of V47, this function does nothing and just runs into an Alert(). NewShell or NewCLI no longer go through this function, but instead sends a startup packet to the shell that will request the shell to get initialized through CliInitRun() instead in all cases. A shell will thus never need to call this function as using it is never requested by the operating system.

Inputs

packet - the initial packet sent to your process MsgPort

Results

fn - flags or a pointer

`CliInitRun()`¶

CliInitRun -- Set up a process to be a shell from initial packet

Synopsis

flags = CliInitRun( packet ) D0 A0

LONG CliInitRun(DosPacket* )

Function

This function initializes a process and CLI structure for a new shell, from parameters in an initial packet passed by the system (Run, System(), Execute()). As of V47, also the initial CLI and a shell created through NewCLI is initialized through this vector, and all other forms of shell initialization are obsolete and not requested by the Os anymore. The format of the data in the packet is purposely not defined. The setup includes all the normal fields in the structures that are required for proper operation (current directory, paths, input streams, etc).

It returns a set of flags containing information about what type
of shell invocation this is.

Definitions for the values of fn:
    Bit 31     Set to indicate flags are valid
    Bit  3     Set to indicate asynch system call
    Bit  2     Set if this is a System() call
    Bit  1     Set if user provided input stream
    Bit  0     Set if RUN provided output stream

If Bit 31 is 0, then you must check IoErr() to determine if an error
occurred.  If IoErr() returns a pointer to your process, there has
been an error, and you should clean up and exit.  The packet will
have already been returned by CliInitRun().  If it isn't a pointer
to your process and Bit 31 is 0, you should wait before replying
the packet until after you've loaded the first command (or when you
exit).  This helps avoid disk "gronking" with the Run command.

If Bit 31 is 1, then if Bit 3 is one, ReplyPkt() the packet
immediately (Asynch System()), otherwise wait until your shell exits
(Sync System(), Execute()).

Inputs

packet - the initial packet sent to your process MsgPort

Results

fn - flags or a pointer

`Close()`¶

Close -- Close an open file

Synopsis

success = Close( file ) D0 D1

BOOL Close(BPTR)

Function

The file specified by the file handle is closed. You must close all files you explicitly opened, but you must not close inherited file handles that are passed to you (each filehandle must be closed once and ONLY once). If Close() fails, the file handle is still deallocated and should not be used.

Inputs

file - BCPL pointer to a file handle

Results

success - returns if Close() succeeded. Note that it might fail depending on buffering and whatever IO must be done to close a file being written to. NOTE: this return value did not exist before V36! In case of success, Close() restores the value of IoErr() to the value it had before the call. IoErr() is only touched in case of failure.

Notes

Starting from V47 onwards, Close(0) does nothing and returns immediately.

See also

Open(), OpenFromLock()

`CompareDates()`¶

CompareDates -- Compares two datestamps (V36)

Synopsis

result = CompareDates(date1,date2) D0 D1 D2

LONG CompareDates(DateStamp*,DateStamp*)

Function

Compares two times for relative magnitide. <0 is returned if date1 is later than date2, 0 if they are equal, or >0 if date2 is later than date1. NOTE: this is NOT the same ordering as strcmp!

Inputs

date1, date2 - DateStamps to compare

Results

result - <0, 0, or >0 based on comparison of two date stamps

`CreateDir()`¶

CreateDir -- Create a new directory

Synopsis

lock = CreateDir( name ) D0 D1

BPTR CreateDir(STRPTR)

Function

CreateDir 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. CreateDir returns an exclusive lock on the new directory if it succeeds.

Inputs

name - pointer to a null-terminated string

Results

lock - BCPL pointer to a lock or NULL for failure.

See also

Lock(), UnLock()

`CreateNewProc()`¶

CreateNewProc -- Create a new process (V36)

Synopsis

process = CreateNewProc(tags) D0 D1

Process*CreateNewProc(TagItem*)

process = CreateNewProcTagList(tags) D0 D1

Process*CreateNewProcTagList(TagItem*)

process = CreateNewProcTags(Tag1, ...)

Process*CreateNewProcTags(ULONG, ...)

Function

This creates a new process according to the tags passed in. See dos/dostags.h for the tags.

You must specify one of NP_Seglist or NP_Entry.  NP_Seglist takes a
seglist (as returned by LoadSeg()).  NP_Entry takes a function
pointer for the routine to call.

There are many options, as you can see by examining dos/dostags.h.
The defaults are for a non-CLI process, with copies of your
CurrentDir, HomeDir (used for PROGDIR:), priority, consoletask,
windowptr, and variables.  The input and output filehandles default
to opens of NIL:, stack to 4000, and others as shown in dostags.h.
This is a fairly reasonable default setting for creating threads,
though you may wish to modify it (for example, to give a descriptive
name to the process.)

CreateNewProc() is callable from a task, though any actions that
require doing Dos I/O (DupLock() of currentdir, for example) will not
occur.

NOTE: if you call CreateNewProc() with both NP_Arguments, you must
not specify an NP_Input of NULL.  When NP_Arguments is specified, it
needs to modify the input filehandle to make ReadArgs() work properly.

Inputs

tags - a pointer to a TagItem array. The following tags are supported as of V47, see also :

NP_Seglist  (BPTR)  Seglist of the code to run
NP_FreeSeglist  (BOOL)  A flag that indicates whether the seglist
        provided by NP_Seglist is to be released on exit.
        Default is FALSE.
NP_Entry    (APTR)  Entry point of the code to run, mutually
        exclusive to NP_Seglist. Do NOT specify NP_FreeSegList
        with this tag.
NP_Input    (BPTR)  Filehandle to use as pr_CIS, default is
        Open("NIL:",MODE_OLDFILE).
NP_Output   (BPTR)  Filehandle to use as pr_COS, default is
        Open("NIL:",MODE_NEWFILE).
NP_CloseInput   (BOOL)  Close pr_CIS on exit. Default is TRUE. Make
        sure not to reset this tag if you do not specify
        NP_Input.
NP_CloseOutput  (BOOL)  Close pr_COS on exit. Default is TRUE. Make
        sure not to reset this tag if you do not specify
        NP_Output.
NP_Error    (BPTR)  Filehandle to use as pr_CES, default is 0,
        i.e. error output will be redirected to pr_COS.
NP_CloseError   (BOOL)  Close pr_CES on exit. Default is FALSE.
NP_CurrentDir   (BPTR)  Lock to use as current directory. Default
        is DupLock() of the current directory of the caller,
        or 0 if the caller is a task, not a process.
NP_StackSize    (ULONG) Stack size for the process. Defaults to
        4000 bytes.
NP_Name     (const UBYTE *) Name for the new process. Default
        is "New Process".
NP_Priority (BYTE) Priority of the new process. Default is the
        same as the parent.
NP_ConsoleTask  (struct MsgPort *) Message port of the process
        handling "*" and "CONSOLE:". Default is the same
        as the caller, or NULL if the caller is a task.
NP_WindowPtr    (struct Window *) Pointer to the window in which
        context error requesters will be displayed.
        Default is the same as the caller, or NULL if the
        caller is a task.
NP_HomeDir  (BPTR) Lock to the home directory of the process,
        used to resolve PROGDIR:, default is DupLock() of
        home directory of the caller, or 0 of the caller
        is a task.
NP_CopyVars (BOOL) Copy local shell variables if they exist.
        Default is TRUE.
NP_Cli      (BOOL) Create a struct CommandLineInterface and
        attach it to the caller. Default is FALSE.
NP_Path     (BPTR) Singly BPTR-linked list of locks to be used
        for searching for commands. Only used if NP_Cli is
        set. Default is to copy the path of the caller, if
        it exists.
NP_CommandName  (const UBYTE *) Pointer to a string of at most
        104 characters, to be used as command name of the
        shell to be created. Used only if NP_Cli is set.
        Default is the command name of the caller. Note
        that the input string is a NUL-terminated C style
        string, not a BSTR.
NP_Arguments    (const UBYTE *) Pointer to command line arguments,
        passed into the process created, both through the
        registers a0 (pointer) and d0 (length) as well as
        in the buffer of pr_CIS, which therefore shall
        exist, either by default (NP_Input unspecified) or
        by a non-zero value of NP_Input. The arguments are
        copied before they are passed in, and the copy is
        released on exit. Default is not to setup any
        arguments and to keep the buffer of pr_CIS
        untouched.
NP_ExitCode Code to be called when process dies down, receives
        the return code in d0, and NP_ExitData in d1.
NP_ExitData Data to be forwarded to NP_ExitCode in register d1.

Results

process - The created process, or NULL. Note that if it returns NULL, you must free any items that were passed in via tags, such as if you passed in a new current directory with NP_CurrentDir.

Bugs

In V36, NP_Arguments was broken in a number of ways, and probably should be avoided (instead you should start a small piece of your own code, which calls RunCommand() to run the actual code you wish to run). In V37, NP_Arguments works, though see the note above.

NP_FreeSeglist was erraneously documented to have the default TRUE,
but the default was always FALSE.

NP_Error was documented in V40, but was disfuntional until V47.
It is supported in V47.

NP_CloseError was documented to have the default TRUE, but pr_CES
was never closed, nor populated (see above). In fact, the tag
was ignored completely. To avoid problems, the default for
NP_CloseError is FALSE in V47.

NP_CurrentDir, NP_HomeDir and NP_Path copy by default the
corresponding fields of the caller, by DupLock() or by a series
of DupLocks(). While this was always true, the include file
<dos/dostags.h> may have suggested that the lock(s) were
used for the new process without creating copies.

NP_Synchronous and NP_NotifyOnDeath were never implemented,
even though they are documented. Do not use, and do not expect to
work.

`CreateProc()`¶

CreateProc -- Create a new process

Synopsis

process = CreateProc( name, pri, seglist, stackSize ) D0 D1 D2 D3 D4

MsgPort*CreateProc(STRPTR, LONG, BPTR, LONG)

Function

CreateProc() creates a new AmigaDOS process of name 'name'. AmigaDOS processes are a superset of exec tasks.

A seglist, as returned by LoadSeg(), is passed as 'seglist'.
This represents a section of code which is to be run as a new
process. The code is entered at the first hunk in the segment list,
which should contain suitable initialization code or a jump to
such.  A process control structure is allocated from memory and
initialized.  If you wish to fake a seglist (that will never
have DOS UnLoadSeg() called on it), use this code:

        DS.L    0   ;Align to longword
        DC.L    16  ;Segment "length" (faked)
        DC.L    0   ;Pointer to next segment
        ...start of code...

The size of the root stack upon activation is passed as
'stackSize'.  'pri' specifies the required priority of the new
process.  The result will be the process msgport address of the new
process, or zero if the routine failed.  The argument 'name'
specifies the new process name.  A zero return code indicates
error.

The seglist passed to CreateProc() is not freed when it exits; it
is up to the parent process to free it, or for the code to unload
itself.

Under V36 and later, you probably should use CreateNewProc() instead.

Inputs

name - pointer to a null-terminated string pri - signed long (range -128 to +127) seglist - BCPL pointer to a seglist stackSize - integer (must be a multiple of 4 bytes)

Results

process - pointer to new process msgport

`CurrentDir()`¶

CurrentDir -- Make a directory lock the current directory

Synopsis

oldLock = CurrentDir( lock ) D0 D1

BPTR CurrentDir(BPTR)

Function

CurrentDir() causes a directory associated with a lock to be made the current directory. The old current directory lock is returned.

A value of zero is a valid result here, this 0 lock represents the
root of file system that you booted from.

Any call that has to Open() or Lock() files (etc) requires that
the current directory be a valid lock or 0.

Inputs

lock - BCPL pointer to a lock

Results

oldLock - BCPL pointer to a lock

`DateStamp()`¶

DateStamp -- Obtain the date and time in internal format

Synopsis

ds = DateStamp( ds ); D0 D1

DateStamp*DateStamp(DateStamp*)

Function

DateStamp() takes a structure of the same name and fills it in:

   struct DateStamp {
      LONG ds_Days;
      LONG ds_Minute;
      LONG ds_Tick;
   };

The first element is a count of the number of days since January 1, 1978.
The second element is the number of minutes elapsed in the day, past
midnight. The third is the number of ticks elapsed in the current minute.

A tick happens 50 times a second. Note that the number of ticks per
second is a preset constant and not in any way affected by the display
refresh rate (vertical blanking frequency) or the AC power supply
frequency.

DateStamp() ensures that the day and minute are consistent. All three
elements are zero if the date is unset.

Inputs

ds - pointer a struct DateStamp

Results

The DateStamp structure is filled as described and its address is returned (for pre-V36 compatibility).

Notes

Prior to V36 DateStamp() would only return even multiples of 50 ticks. Therefore the time you got was always an even number of ticks. This is no longer the case with V36 and beyond.

`DateToStr()`¶

DateToStr -- Converts a DateStamp to a string (V36)

Synopsis

success = DateToStr( datetime ) D0 D1

BOOL DateToStr(DateTime*)

Function

StamptoStr converts an AmigaDOS DateStamp to a human readable text string as requested by your settings in the DateTime structure.

Inputs

DateTime - a pointer to an initialized DateTime structure.

The DateTime structure should be initialized as follows:

dat_Stamp - a copy of the DateStamp you wish to convert to
      a text string.

dat_Format - a format byte which specifies the format of the
      dat_StrDate. This can be any of the following
      (Note: If the value used is something other than those
      below, the default of FORMAT_DOS will be used):

      FORMAT_DOS:     AmigaDOS format (dd-mmm-yy).

      FORMAT_INT:     International format (yy-mmm-dd).

      FORMAT_USA:     American format (mm-dd-yy).

      FORMAT_CDN:     Canadian format (dd-mm-yy).

      FORMAT_DEF:     default format for locale.

dat_Flags - a flags byte.  The only flag which affects this
      function is:

      DTF_SUBST:      If set, a string such as Today,
              Monday, etc., will be used instead
              of the dat_Format specification if
              possible.

      DTF_FUTURE:     Ignored by this function.

dat_StrDay - pointer to a buffer to receive the day of the
      week string (Monday, Tuesday, etc.). If NULL, this
      string will not be generated. See NOTES below for
      minimum size of the string buffer.

dat_StrDate - pointer to a buffer to receive the date
      string, in the format requested by dat_Format,
      subject to possible modifications by DTF_SUBST.
      If NULL, this string will not be generated.
      See NOTES below for minimum size of the string
      buffer.

dat_StrTime - pointer to a buffer to receive the time of day
      string. If NULL, this string will not be generated.
      See NOTES below for minimum size of the string
      buffer.

Results

success - a zero return indicates that the DateStamp was invalid, and could not be converted. Non-zero indicates that the call succeeded.

Notes

The string buffers pointed to by the dat_StrDay, dat_StrDate and dat_StrTime members must be at least LEN_DATSTRING bytes in size (including the terminating NUL byte).

The dat_Format FORMAT_DEF option will only be supported if the
locale.library is currently active. Otherwise, FORMAT_DOS will
be used instead.

See also

DateStamp(), StrtoDate()

`Delay()`¶

Delay -- Delay a process for a specified time

Synopsis

Delay( ticks ) D1

void Delay(ULONG)

Function

The argument 'ticks' specifies how many ticks (50 per second) to wait before returning control.

Inputs

ticks - integer

Bugs

Due to a bug in the timer.device in V1.2/V1.3, specifying a timeout of zero for Delay() can cause the unreliable timer & floppy disk operation. This is fixed in V36 and later.

`DeleteFile()`¶

DeleteFile -- Delete a file or directory

Synopsis

success = DeleteFile( name ) D0 D1

BOOL DeleteFile(STRPTR)

Function

This attempts to delete the file or directory specified by 'name'. An error is returned if the deletion fails. Note that all the files within a directory must be deleted before the directory itself can be deleted.

Inputs

name - pointer to a null-terminated string

Results

success - boolean

`DeleteVar()`¶

DeleteVar -- Deletes a local or environment variable (V36)

Synopsis

success = DeleteVar( name, flags ) D0 D1 D2

BOOL DeleteVar(STRPTR, ULONG )

Function

Deletes a local or environment variable.

Inputs

name - pointer to an variable name. Note variable names follow filesystem syntax and semantics. flags - combination of type of var to delete (low 8 bits), and flags to control the behavior of this routine. Currently defined flags include:

     GVF_LOCAL_ONLY  - delete a local (to your process) variable.
     GVF_GLOBAL_ONLY - delete a global environment variable.

     The default is to delete a local variable if found, otherwise
     a global environment variable if found (only for LV_VAR).

Results

success - If non-zero, the variable was sucessfully deleted, FALSE indicates failure.

Bugs

LV_VAR is the only type that can be global

`DeviceProc()`¶

DeviceProc -- Return the process MsgPort of specific I/O handler

Synopsis

process = DeviceProc( name ) D0 D1

MsgPort*DeviceProc (STRPTR)

Function

DeviceProc() returns the process identifier of the process which handles the device associated with the specified name. If no process handler can be found then the result is zero. If the name refers to an assign then a directory lock is returned in IoErr(). This lock should not be UnLock()ed or Examine()ed (if you wish to do so, DupLock() it first).

Bugs

In V36, if you try to DeviceProc() something relative to an assign made with AssignPath(), it will fail. This is because there's no way to know when to unlock the lock. If you're writing code for V36 or later, it is highly advised you use GetDeviceProc() instead, or make your code conditional on V36 to use GetDeviceProc()/ FreeDeviceProc().

`DoPkt()`¶

DoPkt -- Send a dos packet and wait for reply (V36)

Synopsis

result1 = DoPkt(port,action,arg1,arg2,arg3,arg4,arg5) D0 D1 D2 D3 D4 D5 D6 D7

LONG DoPkt(MsgPort*,LONG,LONG,LONG,LONG,LONG,LONG)

Function

Sends a packet to a handler and waits for it to return. Any secondary return will be available in D1 AND from IoErr(). DoPkt() will work even if the caller is an exec task and not a process; however it will be slower, and may fail for some additional reasons, such as being unable to allocate a signal. DoPkt() uses your pr_MsgPort for the reply, and will call pr_PktWait. (See BUGS regarding tasks, though).

Only allows 5 arguments to be specified.  For more arguments (packets
support a maximum of 7) create a packet and use SendPkt()/WaitPkt().

Inputs

port - pr_MsgPort of the handler process to send to. action - the action requested of the filesystem/handler arg1, arg2, arg3, arg4,arg5 - arguments, depend on the action, may not be required.

Results

result1 - the value returned in dp_Res1, or FALSE if there was some problem in sending the packet or recieving it. result2 - Available from IoErr() AND in register D1.

Notes

Callable from a task (under V37 and above). The prototypes in also define the functions DoPkt1() through DoPkt5() which supply only the indicated number of arguments. This allows somewhat more compact programs.

Bugs

Using DoPkt() from tasks doesn't work in V36. Use AllocDosObject(), PutMsg(), and WaitPort()/GetMsg() for a workaround, or you can call CreateNewProc() to start a process to do Dos I/O for you. In V37, DoPkt() will allocate, use, and free the MsgPort required.

`DoShellMethod()`¶

DoShellMethod -- Run a method of the shell (V47)

Synopsis

ptr = DoShellMethodTagList(method, tags) D0 D0 A0

APTR DoShellMethodTagList(ULONG,TagItem*)

ptr = DoShellMethod(method, Tag1, ...)

APTR DoShellMethod(ULONG, ULONG, ...)

Function

Request and run a function of a V47 extended shell. The method ID specifies which feature of the shell is to be run, the tags provide arguments to the method. The return code is either a pointer, or an integer casted to a pointer. If the current process is not run from a shell, or the shell is not extended, the function returns NULL and ERROR_OBJECT_WRONG_TYPE in IoErr().

The following methods are implemented by the V47 ROM shell, see
also <dos/shell.h>:

SHELL_METH_METHODS: Returns a pointer to a 0L terminated list
of ULONGs that lists all methods the shell supports.

SHELL_METH_GETHIST: Return a pointer to the command history.
The result code is a pointer to a struct MinList whose nodes are
of type struct HistoryNode, see <dos/shell.h>. This method does
not take any arguments.

SHELL_METH_CLRHIST: Erase the current history. This method
does not take any arguments. Returns a boolean success indicator.

SHELL_METH_ADDHIST: Adds a line to the history. The line
to be added is provided by the tag SHELL_ADDH_LINE as a NUL-
terminated C style string. A terminating '\n' is NOT required.
Returns a boolean success indicator.

SHELL_METH_FGETS:   Request input from the console, allowing
TAB expansion of the arguments. This method returns a pointer to
a NUL terminated C string. The memory of the string is handled
by the shell and MUST NOT be released by the caller. It is valid
until the next DoShellMethod() function or until the application
terminates.
The following tags are accepted: SHELL_FGETS_FULL is a boolean
tag that is set to TRUE if the requested line is a full command
line, and the first argument is a command. The shell will scan
the full command line search path for its expansion, and may
print the regular prompt. If FALSE, only files in the current
directory are scanned, and an abbreviated prompt is printed.
This tag defaults to FALSE.

Inputs

method - method requested from the shell tags - pointer to taglist with additional information

Results

ptr - result or NULL.

Notes

SHELL_FGETS_FULL is used by ReadArgs() if more parameters are required from the caller. If a custom shell supports TAB expansion, it is recommended that such a shell also implements the above method.

`DupLock()`¶

DupLock -- Duplicate a lock

Synopsis

lock = DupLock( lock ) D0 D1

BPTR DupLock(BPTR)

Function

DupLock() is passed a shared filing system lock. This is the ONLY way to obtain a duplicate of a lock... simply copying is not allowed.

Another lock to the same object is then returned.  It is not
possible to create a copy of a exclusive lock.

A zero return indicates failure.

Inputs

lock - BCPL pointer to a lock

Results

newLock - BCPL pointer to a lock

`DupLockFromFH()`¶

DupLockFromFH -- Gets a lock on an open file (V36)

Synopsis

lock = DupLockFromFH(fh) D0 D1

BPTR DupLockFromFH(BPTR)

Function

Obtain a lock on the object associated with fh. Only works if the file was opened using a non-exclusive mode. Other restrictions may be placed on success by the filesystem.

Inputs

fh - Opened file for which to obtain the lock

Results

lock - Obtained lock or NULL for failure

See also

DupLock(), Lock(), UnLock()

`EndNotify()`¶

EndNotify -- Ends a notification request (V36)

Synopsis

EndNotify(notifystructure) D1

VOID EndNotify(NotifyRequest*)

Function

Removes a notification request. Safe to call even if StartNotify() failed. For NRF_SEND_MESSAGE, it searches your port for any messages about the object in question and removes and replies them before returning.

Inputs

notifystructure - a structure passed to StartNotify()

Notes

From V47 on, passing in NULL is a no-op.

See also

StartNotify()

`ErrorOutput()`¶

ErrorOutput -- Identify the programs' error output file handle (V47)

Synopsis

file = ErrorOutput() D0

BPTR ErrorOutput(void)

Function

ErrorOutput() is used to identify the error output stream allocated when the program was initiated. It may or may not be identical to the stream returned by Output(). Shell commands shall use this output for diagnostic messages.

Results

file - BCPL pointer to a file handle

Notes

This call will return the output stream of the process in case the error stream is not set.

See also

Output()

`ErrorReport()`¶

ErrorReport -- Displays a Retry/Cancel requester for an error (V36)

Synopsis

status = ErrorReport(code, type, arg1, device) D0 D1 D2 D3 D4

BOOL ErrorReport(LONG, LONG, ULONG,MsgPort*)

Function

Based on the request type, this routine formats the appropriate requester to be displayed. If the code is not understood, it returns DOS_TRUE immediately. Returns DOS_TRUE if the user selects CANCEL or if the attempt to put up the requester fails, or if the process pr_WindowPtr is -1. Returns FALSE if the user selects Retry. The routine will retry on DISKINSERTED for appropriate error codes. These return values are the opposite of what AutoRequest returns.

This routine is supposed to set IoErr() to code before returning.
See the BUGS section for limitations and workarounds.

Inputs

code - Error code to put a requester up for. Current valid error codes are: ERROR_DISK_NOT_VALIDATED ERROR_DISK_WRITE_PROTECTED ERROR_DISK_FULL ERROR_DEVICE_NOT_MOUNTED ERROR_NOT_A_DOS_DISK ERROR_NO_DISK ABORT_DISK_ERROR / read/write error / ABORT_BUSY / you MUST replace... / type - Request type: REPORT_LOCK - arg1 is a lock (BPTR). REPORT_FH - arg1 is a filehandle (BPTR). REPORT_VOLUME - arg1 is a volumenode (C pointer). REPORT_INSERT - arg1 is the string for the volumename (will be split on a ':'). With ERROR_DEVICE_NOT_MOUNTED puts up the "Please insert..." requester. arg1 - variable parameter (see type) device - (Optional) Address of handler task for which report is to be made. Only required for REPORT_LOCK, and only if arg1==NULL.

Results

status - Cancel/Retry indicator (0 means Retry)

Notes

ErrorReport() cannot be called from a Task because it assumes that is getting called from a Process.

Bugs

ErrorReport() is supposed to set IoErr() to code before returning. In V36-V47.26 it would only set IoErr() to code for the error codes listed in the INPUTS section. For all other codes the IoErr() status prior to calling ErrorReport() would persist.

If you need to be sure that the IoErr() return value matches the
error code you pass to ErrorReport() in case the status returned
is not 0 (0 means Retry), call SetIoErr(code) prior to calling
ErrorReport().

See also

Fault(), IoErr()

`ExAll()`¶

ExAll -- Examine an entire directory (V36)

Synopsis

continue = ExAll(lock, buffer, size, type, control) D0 D1 D2 D3 D4 D5

BOOL ExAll(BPTR,STRPTR,LONG,LONG,ExAllControl*)

Function

Examines an entire directory.

Lock must be on a directory. Size is the size of the buffer supplied. The buffer will be filled with (partial) ExAllData structures, as specified by the type field.

Type is a value from those shown below that determines which information is to be stored in the buffer. Each higher value adds a new thing to the list as described in the table below:-

ED_NAME     FileName
ED_TYPE     Type
ED_SIZE     Size in bytes
ED_PROTECTION   Protection bits
ED_DATE     3 longwords of date
ED_COMMENT  Comment (will be NULL if no comment)
ED_OWNER    owner user-id and group-id (if supported)  (V39)

Thus, ED_NAME gives only filenames, and ED_OWNER gives everything.

NOTE: V37 dos.library, when doing ExAll() emulation, and V37 filesystems will return an error if passed ED_OWNER. If you get ERROR_BAD_NUMBER, retry with ED_COMMENT to get everything but owner info. All filesystems supporting ExAll() must support through ED_COMMENT, and must check Type and return ERROR_BAD_NUMBER if they don't support the type.

The ead_Next entry gives a pointer to the next entry in the buffer. The last entry will have NULL in ead_Next.

The control structure is required so that FFS can keep track if more than one call to ExAll is required. This happens when there are more names in a directory than will fit into the buffer. The format of the control structure is as follows:-

NOTE: the control structure MUST be allocated by AllocDosObject!!!

Entries: This field tells the calling application how many entries are in the buffer after calling ExAll. Note: make sure your code handles the 0 entries case, including 0 entries with continue non-zero.

LastKey: This field ABSOLUTELY MUST be initialised to 0 before calling ExAll for the first time. Any other value will cause nasty things to happen. If ExAll returns non-zero, then this field should not be touched before making the second and subsequent calls to ExAll. Whenever ExAll returns non-zero, there are more calls required before all names have been received.

    As soon as a FALSE return is received then ExAll has completed
    (if IoErr() returns ERROR_NO_MORE_ENTRIES - otherwise it returns
    the error that occured, similar to ExNext.)

MatchString If this field is NULL then all filenames will be returned. If this field is non-null then it is interpreted as a pointer to a string that is used to pattern match all file names before accepting them and putting them into the buffer. The default AmigaDOS caseless pattern match routine is used. This string MUST have been parsed by ParsePatternNoCase()!

MatchFunc: Contains a pointer to a hook for a routine to decide if the entry will be included in the returned list of entries. The entry is filled out first, and then passed to the hook. If no MatchFunc is to be called then this entry should be NULL. The hook is called with the following parameters (as is standard for hooks):

    BOOL = MatchFunc( hookptr, data, typeptr )
            a0  a1  a2
    (a0 = ptr to hook, a1 = ptr to filled in ExAllData, a2 = ptr
     to longword of type).

    MatchFunc should return FALSE if the entry is not to be
    accepted, otherwise return TRUE.

Note that Dos will emulate ExAll() using Examine() and ExNext()
if the handler in question doesn't support the ExAll() packet.

Inputs

lock - Lock on directory to be examined. NOTE: Not all file systems will accept a 0 lock here. buffer - Buffer for data returned (MUST be at least word-aligned, preferably long-word aligned). size - Size in bytes of 'buffer'. type - Type of data to be returned. control - Control data structure (see notes above). MUST have been allocated by AllocDosObject!

Results

continue - Whether or not ExAll is done. If FALSE is returned, either ExAll has completed (IoErr() == ERROR_NO_MORE_ENTRIES), or an error occurred (check IoErr()). If non-zero is returned, you MUST call ExAll again until it returns FALSE.

Example

eac = AllocDosObject(DOS_EXALLCONTROL,NULL); if (!eac) ... ... eac->eac_LastKey = 0; do { more = ExAll(lock, EAData, sizeof(EAData), ED_FOO, eac); if ((!more) && (IoErr() != ERROR_NO_MORE_ENTRIES)) { * ExAll failed abnormally \ break; } if (eac->eac_Entries == 0) { * ExAll failed normally with no entries \ continue; * ("more" is usually zero) \ } ead = (struct ExAllData ) EAData; do { * use ead here \ ... * get next ead \ ead = ead->ed_Next; } while (ead);

} while (more); ... FreeDosObject(DOS_EXALLCONTROL,eac);

Bugs

In V36, there were problems with ExAll (particularily with eac_MatchString, and ed_Next with the ramdisk and the emulation of it in Dos for handlers that do not support the packet. It is advised you only use this under V37 and later. The V39 DirCache variant of the FFS had a bug in ExAll that required to first Examine() the lock before passing it to ExAll. This was fixed in V40, with a patch in SetPatch. The V40 version passed an invalid argument to the dos.library error report handler in case of trouble, potentially causing crashes or other mischiefs. This was fixed in V47, with a patch in SetPatch V45.

See note above regarding extensions to the Type parameter.

`ExAllEnd()`¶

ExAllEnd -- Stop an ExAll() (V39)

Synopsis

ExAllEnd(lock, buffer, size, type, control) D1 D2 D3 D4 D5

ExAllEnd(BPTR,STRPTR,LONG,LONG,ExAllControl*)

Function

Stops an ExAll() on a directory before it hits NO_MORE_ENTRIES. The full set of arguments that had been passed to ExAll() must be passed to ExAllEnd(), so it can handle filesystems that can't abort an ExAll() directly.

Inputs

lock - Lock on directory to be examined. buffer - Buffer for data returned (MUST be at least word-aligned, preferably long-word aligned). size - Size in bytes of 'buffer'. type - Type of data to be returned. control - Control data structure (see notes above). MUST have been allocated by AllocDosObject!

See also

ExAll(), AllocDosObject()

`Examine()`¶

Examine -- Examine a directory or file associated with a lock

Synopsis

success = Examine( lock, FileInfoBlock ) D0 D1 D2

BOOL Examine(BPTR,FileInfoBlock*)

Function

Examine() fills in information in the FileInfoBlock concerning the file or directory associated with the lock. This information includes the name, size, creation date and whether it is a file or directory. FileInfoBlock must be longword aligned. Examine() gives a return code of zero if it fails.

You may make a local copy of the FileInfoBlock, as long as it is
never passed to ExNext().

Inputs

lock - BCPL pointer to a lock infoBlock - pointer to a FileInfoBlock (MUST be longword aligned)

Results

success - boolean

SPECIAL NOTE
FileInfoBlock must be longword-aligned.  AllocDosObject() will
allocate them correctly for you.

`ExamineFH()`¶

ExamineFH -- Gets information on an open file (V36)

Synopsis

success = ExamineFH(fh, fib) D0 D1 D2

BOOL ExamineFH(BPTR,FileInfoBlock*)

Function

Examines a filehandle and returns information about the file in the FileInfoBlock. There are no guarantees as to whether the fib_Size field will reflect any changes made to the file size it was opened, though filesystems should attempt to provide up-to-date information for it.

Inputs

fh - Filehandle you wish to examine fib - FileInfoBlock, must be longword aligned.

Results

success - Success/failure indication

`Execute()`¶

Execute -- Execute a CLI command

Synopsis

success = Execute( commandString, input, output ) D0 D1 D2 D3

BOOL Execute(STRPTR, BPTR, BPTR)

Function

This function attempts to execute the string commandString as a Shell command and arguments. The string can contain any valid input that you could type directly in a Shell, including input and output redirection using < and >. Note that Execute() doesn't return until the command(s) in commandstring have returned.

The input file handle will normally be zero, and in this case
Execute() will perform whatever was requested in the commandString
and then return. If the input file handle is nonzero then after the
(possibly empty) commandString is performed subsequent input is read
from the specified input file handle until end of that file is
reached.

In most cases the output file handle must be provided, and is used
by the Shell commands as their output stream unless output
redirection was specified. If the output file handle is set to zero
then the current window, normally specified as *, is used. Note
that programs running under the Workbench do not normally have a
current window.

Execute() may also be used to create a new interactive Shell process
just like those created with the NewShell command. In order to do
this you would call Execute() with an empty commandString, and pass
a file handle relating to a new window as the input file handle.
The output file handle would be set to zero. The Shell will read
commands from the new window, and will use the same window for
output. This new Shell window can only be terminated by using the
EndCLI command.

Under V37, if an input filehandle is passed, and it's either
interactive or a NIL: filehandle, the pr_ConsoleTask of the new
process will be set to that filehandle's process (the same applies
to SystemTagList()).

For this command to work the program Run must be present in C: in
versions before V36 (except that in 1.3.2 and any later 1.3 versions,
the system first checks the resident list for Run).

Inputs

commandString - pointer to a null-terminated string input - BCPL pointer to a file handle output - BCPL pointer to a file handle

Results

success - BOOLEAN indicating whether Execute was successful in finding and starting the specified program. Note this is NOT the return code of the command(s).

See also

SystemTagList()

`Exit()`¶

Exit -- Exit from a program

Synopsis

Exit( returnCode ) D1

void Exit(LONG)

Function

Exit() is currently for use with programs written as if they were BCPL programs. This function is not normally useful for other purposes.

In general, therefore, please DO NOT CALL THIS FUNCTION!

In order to exit, C programs should use the C language exit()
function (note the lower case letter "e").  Assembly programs should
place a return code in D0, and execute an RTS instruction with
their original stack ptr.

IMPLEMENTATION
The action of Exit() depends on whether the program which called it
is running as a command under a CLI or not. If the program is
running under the CLI the command finishes and control reverts to
the CLI. In this case, returnCode is interpreted as the return code
from the program.

If the program is running as a distinct process, Exit() deletes the
process and release the space associated with the stack, segment
list and process structure.

Inputs

returnCode - integer

See also

CreateProc(), CreateNewProc()

`ExNext()`¶

ExNext -- Examine the next entry in a directory

Synopsis

success = ExNext( lock, FileInfoBlock ) D0 D1 D2

BOOL ExNext(BPTR,FileInfoBlock*)

Function

This routine is passed a directory lock and a FileInfoBlock that have been initialized by a previous call to Examine(), or updated by a previous call to ExNext(). ExNext() gives a return code of zero on failure. The most common cause of failure is reaching the end of the list of files in the owning directory. In this case, IoErr will return ERROR_NO_MORE_ENTRIES and a good exit is appropriate.

So, follow these steps to examine a directory:
1) Pass a Lock and a FileInfoBlock to Examine().  The lock must
   be on the directory you wish to examine.
2) Pass ExNext() the same lock and FileInfoBlock.
3) Do something with the information returned in the FileInfoBlock.
   Note that the fib_DirEntryType field is positive for directories,
   negative for files.
4) Keep calling ExNext() until it returns FALSE.  Check IoErr()
   to ensure that the reason for failure was ERROR_NO_MORE_ENTRIES.

Note: if you wish to recursively scan the file tree and you find
another directory while ExNext()ing you must Lock that directory and
Examine() it using a new FileInfoBlock.  Use of the same
FileInfoBlock to enter a directory would lose important state
information such that it will be impossible to continue scanning
the parent directory.  While it is permissible to UnLock() and Lock()
the parent directory between ExNext() calls, this is NOT recommended.
Important state information is associated with the parent lock, so
if it is freed between ExNext() calls this information has to be
rebuilt on each new ExNext() call, and will significantly slow down
directory scanning.

It is NOT legal to Examine() a file, and then to ExNext() from that
FileInfoBlock.  You may make a local copy of the FileInfoBlock, as
long as it is never passed back to the operating system.

Inputs

lock - BCPL pointer to a lock originally used for the Examine() call This lock shall be non-zero. Unlike Examine(), ExNext() does not support the 0 lock. infoBlock - pointer to a FileInfoBlock used on the previous Examine() or ExNext() call.

Results

success - boolean

SPECIAL NOTE
FileInfoBlock must be longword-aligned.  AllocDosObject() will
allocate them correctly for you.

`Fault()`¶

Fault -- Returns the text associated with a DOS error code (V36)

Synopsis

len = Fault(code, header, buffer, len) D0 D1 D2 D3 D4

LONG Fault(LONG, STRPTR, STRPTR, LONG)

Function

This routine obtains the error message text for the given error code. The header is prepended to the text of the error message, followed by a colon. Puts a null-terminated string for the error message into the buffer. By convention, error messages should be no longer than 80 characters (+1 for termination), and preferably no more than 60. The value returned by IoErr() is set to the code passed in. If there is no message for the error code, the message will be "Error code \n".

The number of characters put into the buffer is returned, which will
be 0 if the code passed in was 0.

Inputs

code - Error code header - header to output before error text buffer - Buffer to receive error message. len - Length of the buffer.

Results

len - number of characters put into buffer (may be 0)

Bugs

In older documentation, the return was shown as BOOL success. This was incorrect, it has always returned the length.

See also

IoErr(), SetIoErr(), PrintFault()

`FGetC()`¶

FGetC -- Read a character from the specified input (buffered) (V36)

Synopsis

char = FGetC(fh) D0 D1

LONG FGetC(BPTR)

Function

Reads the next character from the input stream. A -1 is returned when EOF or an error is encountered. This call is buffered. Use Flush() between buffered and unbuffered I/O on a filehandle.

Inputs

fh - filehandle to use for buffered I/O

Results

char - character read (0-255) or -1

Bugs

In V36, after an EOF was read, EOF would always be returned from FGetC() from then on. Starting in V37, it tries to read from the handler again each time (unless UnGetC(fh,-1) was called).

See also

FPutC(), UnGetC(), Flush()

`FGets()`¶

FGets -- Reads a line from the specified input (buffered) (V36)

Synopsis

buffer = FGets(fh, buf, len) D0 D1 D2 D3

STRPTR FGets(BPTR, STRPTR, ULONG)

Function

This routine reads in a single line from the specified input stopping at a NEWLINE character or EOF. In either event, UP TO the number of len specified bytes minus 1 will be copied into the buffer. Hence if a length of 50 is passed and the input line is longer than 49 bytes, it will return 49 characters. It returns the buffer pointer normally, or NULL if EOF is the first thing read.

If terminated by a newline, the newline WILL be the last character in
the buffer.  This is a buffered read routine.  The string read in IS
null-terminated.

See the BUGS section for the conditions under which the string is
never null-terminated.

Inputs

fh - filehandle to use for buffered I/O buf - Area to read bytes into. len - Number of bytes to read, must be > 0.

Results

buffer - Pointer to buffer passed in, or NULL for immediate EOF or for an error. If NULL is returned for an EOF, IoErr() will return 0.

Notes

The dos FGets() function is patterned after the 'C' standard I/O function fgets() but there is a crucial difference which can produce buffer overflows: FGets() uses an unsigned length parameter whereas fgets() uses a signed integer. If you accidentally pass a negative length to fgets() it will stop immediately. But if you do the same with FGets(), the length will be interpreted as a very large unsigned number. This is what can lead to a string buffer overflow which could corrupt data and lead to undefined behaviour.

Bugs

In V36 and V37, it copies one more byte than it should if it doesn't hit an EOF or newline. In the example above, it would copy 50 bytes and put a null in the 51st. This is fixed in dos V39. Workaround for V36/V37: pass in buffersize-1.

The dos V39 fix for the buffer overflow has a side-effect in that
if you accidentally pass length=0 then FGets() will effectively use a
buffer size of 4294967295 characters. Regardless of its size, your
buffer may be subject to overflow if this occurs. Buffer overflows
can corrupt data and lead to undefined behaviour.
This is fixed in dos 47.27. Passing length=0 will make FGets() return
NULL with IoErr() returning 0, indicating an EOF condition. Nothing
will be written to the buffer. No null-termination will be provided
for a buffer of size 0.

See also

FRead(), FPuts(), FGetC()

`FilePart()`¶

FilePart -- Returns the last component of a path (V36)

Synopsis

fileptr = FilePart( path ) D0 D1

STRPTR FilePart( STRPTR )

Function

This function returns a pointer to the last component of a string path specification, which will normally be the file name. If there is only one component, it returns a pointer to the beginning of the string.

Inputs

path - pointer to an path string. May be relative to the current directory or the current disk.

Results

fileptr - pointer to the last component of the path.

Example

FilePart("xxx:yyy/zzz/qqq") would return a pointer to the first 'q'. FilePart("xxx:yyy") would return a pointer to the first 'y').

See also

PathPart(), AddPart()

`FindArg()`¶

FindArg - find a keyword in a template (V36)

Synopsis

index = FindArg(template, keyword) D0 D1 D2

LONG FindArg(STRPTR, STRPTR)

Function

Returns the argument number of the keyword, or -1 if it is not a keyword for the template. Abbreviations are handled.

Inputs

keyword - keyword to search for in template template - template string to search

Results

index - number of entry in template, or -1 if not found

Bugs

In earlier published versions of the autodoc, keyword and template were backwards.

`FindCliProc()`¶

FindCliProc -- returns a pointer to the requested CLI process (V36)

Synopsis

proc = FindCliProc(num) D0 D1

Process*FindCliProc(ULONG)

Function

This routine returns a pointer to the CLI process associated with the given CLI number. If the process isn't an active CLI process, NULL is returned. NOTE: should normally be called inside a Forbid(), if you must use this function at all.

Inputs

num - Task number of CLI process (range 1-N)

Results

proc - Pointer to given CLI process

See also

Cli(), Forbid(), MaxCli()

`FindDosEntry()`¶

FindDosEntry -- Finds a specific Dos List entry (V36)

Synopsis

newdlist = FindDosEntry(dlist,name,flags) D0 D1 D2 D3

DosList*FindDosEntry(DosList*,STRPTR,ULONG)

Function

Locates an entry on the device list. Starts with the entry dlist. NOTE: must be called with the device list locked, no references may be made to dlist after unlocking.

Inputs

dlist - The device entry to start with. name - Name of device entry (without ':') to locate. flags - Search control flags. Use the flags you passed to LockDosList, or a subset of them. LDF_READ/LDF_WRITE are not required for this call.

Results

newdlist - The device entry or NULL

`FindSegment()`¶

FindSegment - Finds a segment on the resident list (V36)

Synopsis

segment = FindSegment(name, start, system) D0 D1 D2 D3

Segment*FindSegment(STRPTR,Segment*, LONG)

Function

Finds a segment on the Dos resident list by name and type, starting at the segment AFTER 'start', or at the beginning if start is NULL. If system is zero, it will only return nodes with a seg_UC of 0 or more. It does NOT increment the seg_UC, and it does NOT do any locking of the list. You must Forbid() lock the list to use this call.

To use an entry you have found, you must: if the seg_UC is 0 or more,
increment it, and decrement it (under Forbid()!) when you're done
with the seglist.

The other values for seg_UC are:
    -1   - system module, such as a filesystem or shell
    -2   - resident shell command
    -999 - disabled internal command, ignore
Negative values should never be modified.  All other negative
values between 0 and -32767 are reserved to AmigaDos and should not
be used.

Inputs

name - name of segment to find start - segment to start the search after system - true for system segment, false for normal segments

Results

segment - the segment found or NULL

`FindVar()`¶

FindVar -- Finds a local variable (V36)

Synopsis

var = FindVar( name, type ) D0 D1 D2

LocalVar* FindVar(STRPTR, ULONG )

Function

Finds a local variable structure.

Inputs

name - pointer to an variable name. Note variable names follow filesystem syntax and semantics.

type - type of variable to be found (see <dos/var.h>)

Results

var - pointer to a LocalVar structure or NULL

See also

GetVar(), SetVar(), DeleteVar()

`Flush()`¶

Flush -- Flushes buffers for a buffered filehandle (V36)

Synopsis

success = Flush(fh) D0 D1

LONG Flush(BPTR)

Function

Flushes any pending buffered writes to the filehandle. All buffered writes will also be flushed on Close(). If the filehandle was being used for input, it drops the buffer, and tries to Seek() back to the last read position (so subsequent reads or writes will occur at the expected position in the file).

Inputs

fh - Filehandle to flush.

Results

success - Success or failure.

Bugs

Before V37 release, Flush() returned a random value. As of V37, it always returns success (this will be fixed in some future release).

The V36 and V37 releases didn't properly flush filehandles which
have never had a buffered IO done on them.  This commonly occurs
on redirection of input of a command, or when opening a file for
input and then calling CreateNewProc() with NP_Arguments, or when
using a new filehandle with SelectInput() and then calling
RunCommand().  This is fixed in V39.  A workaround would be to
do FGetC(), then UnGetC(), then Flush().

`Format()`¶

Format -- Causes a filesystem to initialize itself (V36)

Synopsis

success = Format(filesystem, volumename, dostype) D0 D1 D2 D3

BOOL Format(STRPTR, STRPTR, ULONG)

Function

Interface for initializing new media on a device. This causes the filesystem to write out an empty disk structure to the media, which should then be ready for use. This assumes the media has been low- level formatted and verified already.

The filesystem should be inhibited before calling Format() to make
sure you don't get an ERROR_OBJECT_IN_USE.

Inputs

filesystem - Name of device to be formatted. ':' must be supplied. volumename - Name for volume (if supported). No ':'. dostype - Type of format, if filesystem supports multiple types.

Results

success - Success/failure indicator.

Bugs

Existed, but was non-functional in V36 dos. (The volumename wasn't converted to a BSTR.) Workaround: require V37, or under V36 convert volumename to a BPTR to a BSTR before calling Format(). Note: a number of printed packet docs for ACTION_FORMAT are wrong as to the arguments.

`FPutC()`¶

FPutC -- Write a character to the specified output (buffered) (V36)

Synopsis

char = FPutC(fh, char) D0 D1 D2

LONG FPutC(BPTR, LONG)

Function

Writes a single character to the output stream. This call is buffered. Use Flush() between buffered and unbuffered I/O on a filehandle. Interactive filehandles are flushed automatically on a newline, return, '\0', or line feed.

Inputs

fh - filehandle to use for buffered I/O char - character to write

Results

char - either the character written, or EOF for an error.

Bugs

Older autodocs indicated that you should pass a UBYTE. The correct usage is to pass a LONG in the range 0-255.

See also

FGetC(), UnGetC(), Flush()

`FPuts()`¶

FPuts -- Writes a string to the specified output (buffered) (V36)

Synopsis

error = FPuts(fh, str) D0 D1 D2

LONG FPuts(BPTR, STRPTR)

Function

This routine writes an unformatted string to the filehandle. No newline is appended to the string. This routine is buffered.

Inputs

fh - filehandle to use for buffered I/O str - Null-terminated string to be written to default output

Results

error - 0 normally, otherwise -1. Note that this is opposite of most other Dos functions, which return success.

`FRead()`¶

FRead -- Reads a number of blocks from an input (buffered) (V36)

Synopsis

count = FRead(fh, buf, blocklen, blocks) D0 D1 D2 D3 D4

LONG FRead(BPTR, STRPTR, ULONG, ULONG)

Function

Attempts to read a number of blocks, each blocklen long, into the specified buffer from the input stream. May return less than the number of blocks requested, either due to EOF or read errors. This call is buffered.

Inputs

fh - filehandle to use for buffered I/O buf - Area to read bytes into. blocklen - number of bytes per block. Must be > 0. blocks - number of blocks to read. Must be > 0.

Results

count - Number of blocks read, or 0 for EOF. On an error, the number of blocks actually read is returned.

Bugs

Doesn't clear IoErr() before starting. If you want to find out about errors, use SetIoErr(0L) before calling. This call was implemented as a series of FGetC() under V45 and below, and hence slow. V47 fixes this.

See also

FGetC(), FWrite(), FGets()

`FreeArgs()`¶

FreeArgs - Free allocated memory after ReadArgs() (V36)

Synopsis

FreeArgs(rdargs) D1

void FreeArgs(RDArgs*)

Function

Frees memory allocated to return arguments in from ReadArgs(). If ReadArgs allocated the RDArgs structure it will be freed. If NULL is passed in this function does nothing.

Inputs

rdargs - structure returned from ReadArgs() or NULL.

See also

ReadArgs(), ReadItem(), FindArg()

`FreeDeviceProc()`¶

FreeDeviceProc -- Releases port returned by GetDeviceProc() (V36)

Synopsis

FreeDeviceProc(devproc) D1

void FreeDeviceProc(DevProc*)

Function

Frees up the structure created by GetDeviceProc(), and any associated temporary locks.

Decrements the counter incremented by GetDeviceProc().  The counter
is in an extension to the 1.3 process structure.  After calling
FreeDeviceProc(), do not use the port or lock again!  It is safe to
call FreeDeviceProc(NULL).

Inputs

devproc - A value returned by GetDeviceProc()

Bugs

Counter not currently active in 2.0.

`FreeDosEntry()`¶

FreeDosEntry -- Frees an entry created by MakeDosEntry (V36)

Synopsis

FreeDosEntry(dlist) D1

void FreeDosEntry(DosList*)

Function

Frees an entry created by MakeDosEntry(). This routine should be eliminated and replaced by a value passed to FreeDosObject()!

Inputs

dlist - DosList to free.

`FreeDosObject()`¶

FreeDosObject -- Frees an object allocated by AllocDosObject() (V36)

Synopsis

FreeDosObject(type, ptr) D1 D2

void FreeDosObject(ULONG, void *)

Function

Frees an object allocated by AllocDosObject(). Do NOT call for objects allocated in any other way.

Inputs

type - type passed to AllocDosObject() ptr - ptr returned by AllocDosObject()

Bugs

Before V39, DOS_CLI objects will only have the struct CommandLineInterface freed, not the strings it points to. This is fixed in V39 dos. Before V39, you can workaround this bug by using FreeVec() on cli_SetName, cli_CommandFile, cli_CommandName, and cli_Prompt, and then setting them all to NULL. In V39 or above, do NOT use the workaround.

See also

AllocDosObject(), FreeVec()

`FWrite()`¶

FWrite -- Writes a number of blocks to an output (buffered) (V36)

Synopsis

count = FWrite(fh, buf, blocklen, blocks) D0 D1 D2 D3 D4

LONG FWrite(BPTR, STRPTR, ULONG, ULONG)

Function

Attempts to write a number of blocks, each blocklen long, from the specified buffer to the output stream. May return less than the number of blocks requested, if there is some error such as a full disk or r/w error. This call is buffered.

Inputs

fh - filehandle to use for buffered I/O buf - Area to write bytes from. blocklen - number of bytes per block. Must be > 0. blocks - number of blocks to write. Must be > 0.

Results

count - Number of blocks written. On an error, the number of blocks actually written is returned.

Bugs

Doesn't clear IoErr() before starting. If you want to find out about errors, use SetIoErr(0L) before calling. This call was implemented as a series of FPutC() under V45 and below and hence slow. V47 fixes this.

See also

FPutC(), FRead(), FPuts()

`GetArgStr()`¶

GetArgStr -- Returns the arguments for the process (V36)

Synopsis

ptr = GetArgStr() D0

STRPTR GetArgStr(void)

Function

Returns a pointer to the (null-terminated) arguments for the program (process). This is the same string passed in a0 on startup from CLI.

Results

ptr - pointer to arguments

See also

SetArgStr(), RunCommand()

`GetConsoleTask()`¶

GetConsoleTask -- Returns the default console for the process (V36)

Synopsis

port = GetConsoleTask() D0

MsgPort*GetConsoleTask(void)

Function

Returns the default console task's port (pr_ConsoleTask) for the current process.

Results

port - The pr_MsgPort of the console handler, or NULL.

See also

SetConsoleTask(), Open()

`GetCurrentDir()`¶

GetCurrentDir -- Return the lock of the current directory (V47)

Synopsis

lock = GetCurrentDir(void) D0

BPTR GetCurrentDir()

Function

This routine returns the lock that represent the current directory of the process.

Results

lock - lock representing the current directory. 0 does not represent an error, but the lock to the root of the root of the boot file system.

See also

CurrentDir()

`GetCurrentDirName()`¶

GetCurrentDirName -- returns the current directory name (V36)

Synopsis

success = GetCurrentDirName(buf, len) D0 D1 D2

BOOL GetCurrentDirName(STRPTR, LONG)

Function

Extracts the current directory name from the CLI structure and puts it into the buffer. If the buffer is too small, the name is truncated appropriately and a failure code returned. If no CLI structure is present, a null string is returned in the buffer, and failure from the call (with IoErr() == ERROR_OBJECT_WRONG_TYPE);

Inputs

buf - Buffer to hold extracted name len - Number of bytes of space in buffer

Results

success - Success/failure indicator

Bugs

In V36, this routine didn't handle 0-length buffers correctly.

See also

SetCurrentDirName()

`GetDeviceProc()`¶

GetDeviceProc -- Finds a handler to send a message to (V36)

Synopsis

devproc = GetDeviceProc(name, devproc) D0 D1 D2

DevProc*GetDeviceProc(STRPTR,DevProc*)

Function

Finds the handler/filesystem to send packets regarding 'name' to. This may involve getting temporary locks. It returns a structure that includes a lock and msgport to send to to attempt your operation. It also includes information on how to handle multiple-directory assigns (by passing the DevProc back to GetDeviceProc() until it returns NULL).

The initial call to GetDeviceProc() should pass NULL for devproc.  If
after using the returned DevProc, you get an ERROR_OBJECT_NOT_FOUND,
and (devproc->dvp_Flags & DVPF_ASSIGN) is true, you should call
GetDeviceProc() again, passing it the devproc structure.  It will
either return a modified devproc structure, or NULL (with
ERROR_NO_MORE_ENTRIES in IoErr()).  Continue until it returns NULL.

This call also increments the counter that locks a handler/fs into
memory.  After calling FreeDeviceProc(), do not use the port or lock
again!

Inputs

name - name of the object you wish to access. This can be a relative path ("foo/bar"), relative to the current volume (":foo/bar"), or relative to a device/volume/assign ("foo:bar"). devproc - A value returned by GetDeviceProc() before, or NULL

Results

devproc - a pointer to a DevProc structure or NULL

Bugs

Counter not currently active in 2.0. In 2.0 and 2.01, you HAD to check DVPF_ASSIGN before calling it again. This was fixed for the 2.02 release of V36.

`GetFileSysTask()`¶

GetFileSysTask -- Returns the default filesystem for the process (V36)

Synopsis

port = GetFileSysTask() D0

MsgPort*GetFileSysTask(void)

Function

Returns the default filesystem task's port (pr_FileSystemTask) for the current process.

Results

port - The pr_MsgPort of the filesystem, or NULL.

See also

SetFileSysTask(), Open()

`GetProgramDir()`¶

GetProgramDir -- Returns a lock on the directory the program was loaded from (V36)

Synopsis

lock = GetProgramDir() D0

BPTR GetProgramDir(void)

Function

Returns a shared lock on the directory the program was loaded from. This can be used for a program to find data files, etc, that are stored with the program, or to find the program file itself. NULL returns are valid, and may occur, for example, when running a program from the resident list. You should NOT unlock the lock.

Results

lock - A lock on the directory the current program was loaded from, or NULL if loaded from resident list, etc.

Bugs

Should return a lock for things loaded via resident. Perhaps should return currentdir if NULL.

See also

SetProgramDir(), Open()

`GetProgramName()`¶

GetProgramName -- Returns the current program name (V36)

Synopsis

success = GetProgramName(buf, len) D0 D1 D2

BOOL GetProgramName(STRPTR, LONG)

Function

Extracts the program name from the CLI structure and puts it into the buffer. If the buffer is too small, the name is truncated. If no CLI structure is present, a null string is returned in the buffer, and failure from the call (with IoErr() == ERROR_OBJECT_WRONG_TYPE);

Inputs

buf - Buffer to hold extracted name len - Number of bytes of space in buffer

Results

success - Success/failure indicator

See also

SetProgramName()

`GetPrompt()`¶

GetPrompt -- Returns the prompt for the current process (V36)

Synopsis

success = GetPrompt(buf, len) D0 D1 D2

BOOL GetPrompt(STRPTR, LONG)

Function

Extracts the prompt string from the CLI structure and puts it into the buffer. If the buffer is too small, the string is truncated appropriately and a failure code returned. If no CLI structure is present, a null string is returned in the buffer, and failure from the call (with IoErr() == ERROR_OBJECT_WRONG_TYPE);

Inputs

buf - Buffer to hold extracted prompt len - Number of bytes of space in buffer

Results

success - Success/failure indicator

See also

SetPrompt()

`GetVar()`¶

GetVar -- Returns the value of a local or global variable (V36)

Synopsis

len = GetVar( name, buffer, size, flags ) D0 D1 D2 D3 D4

LONG GetVar( STRPTR, STRPTR, LONG, ULONG )

Function

Gets the value of a local or environment variable. It is advised to only use ASCII strings inside variables, but not required. This stops putting characters into the destination when a \n is hit, unless GVF_BINARY_VAR is specified. (The \n is not stored in the buffer.)

Inputs

name - pointer to a variable name. buffer - a user allocated area which will be used to store the value associated with the variable. size - length of the buffer region in bytes. flags - combination of type of var to get value of (low 8 bits), and flags to control the behavior of this routine. Currently defined flags include:

        GVF_GLOBAL_ONLY - tries to get a global env variable.
        GVF_LOCAL_ONLY  - tries to get a local variable.
        GVF_BINARY_VAR  - don't stop at \n
        GVF_DONT_NULL_TERM - no null termination (only valid
                  for binary variables). (V37)

     The default is to try to get a local variable first, then
     to try to get a global environment variable.

Results

len - Size of environment variable. -1 indicates that the variable was not defined (if IoErr() returns ERROR_OBJECT_NOT_FOUND - it returns ERROR_BAD_NUMBER if you specify a size of 0). If the value would overflow the user buffer, the buffer is truncated. The buffer returned is null-terminated (even if GVF_BINARY_VAR is used, unless GVF_DONT_NULL_TERM is in effect). If it succeeds, len is the number of characters put in the buffer (not including null termination), and IoErr() will return the the size of the variable (regardless of buffer size).

Bugs

LV_VAR is the only type that can be global. Under V36, we documented (and it returned) the size of the variable, not the number of characters transferred. For V37 this was changed to the number of characters put in the buffer, and the total size of the variable is put in IoErr(). GVF_DONT_NULL_TERM only works for local variables under V37. For V39, it also works for globals.

See also

SetVar(), DeleteVar(), FindVar()

`Info()`¶

Info -- Returns information about the disk

Synopsis

success = Info( lock, parameterBlock ) D0 D1 D2

BOOL Info(BPTR,InfoData*)

Function

Info() can be used to find information about any disk in use. 'lock' refers to the disk, or any file on the disk. The parameter block is returned with information about the size of the disk, number of free blocks and any soft errors.

Inputs

lock - BCPL pointer to a lock parameterBlock - pointer to an InfoData structure (longword aligned)

Results

success - boolean

SPECIAL NOTE:
Note that InfoData structure must be longword aligned.

`Inhibit()`¶

Inhibit -- Inhibits access to a filesystem (V36)

Synopsis

success = Inhibit(filesystem, flag) D0 D1 D2

BOOL Inhibit(STRPTR,LONG)

Function

Sends an ACTION_INHIBIT packet to the indicated handler. This stops all activity by the handler until uninhibited. When uninhibited, anything may have happened to the disk in the drive, or there may no longer be one.

Inputs

filesystem - Name of device to inhibit (with ':') flag - New status. DOSTRUE = inhibited, FALSE = uninhibited

Results

success - Success/failure indicator

`Input()`¶

Input -- Identify the program's initial input file handle

Synopsis

file = Input() D0

BPTR Input(void)

Function

Input() is used to identify the initial input stream allocated when the program was initiated. Never close the filehandle returned by Input!

Results

file - BCPL pointer to a file handle

See also

Output(), SelectInput()

`InternalLoadSeg()`¶

InternalLoadSeg -- Low-level load routine (V36)

Synopsis

seglist = InternalLoadSeg(fh,table,functionarray,stack) D0 D0 A0 A1 A2

BPTR InternalLoadSeg(BPTR,BPTR,LONG *,LONG *)

Function

Loads from fh. Table is used when loading an overlay, otherwise should be NULL. Functionarray is a pointer to an array of functions. Note that the current Seek position after loading may be at any point after the last hunk loaded. The filehandle will not be closed. If a stacksize is encoded in the file, the size will be stuffed in the LONG pointed to by stack. This LONG should be initialized to your default value: InternalLoadSeg() will not change it if no stacksize is found. Clears unused portions of Code and Data hunks (as well as BSS hunks). (This also applies to LoadSeg() and NewLoadSeg()).

If the file being loaded is an overlaid file, this will return
-(seglist).  All other results will be positive.

NOTE to overlay users: InternalLoadSeg() does NOT return seglist in
both D0 and D1, as LoadSeg does.  The current ovs.asm uses LoadSeg(),
and assumes returns are in D1.  We will support this for LoadSeg()
ONLY.

Inputs

fh - Filehandle to load from. table - When loading an overlay, otherwise ignored. functionarray - Array of function to be used for read, alloc, and free. FuncTable[0] -> Actual = ReadFunc(readhandle,buffer,length),DOSBase D0 D1 A0 D0 A6 FuncTable[1] -> Memory = AllocFunc(size,flags), Execbase D0 D0 D1 a6 FuncTable[2] -> FreeFunc(memory,size), Execbase A1 D0 a6 stack - Pointer to storage (ULONG) for stacksize.

Results

seglist - Seglist loaded or NULL. NOT returned in D1!

Bugs

Really should use tags.

`InternalUnLoadSeg()`¶

InternalUnLoadSeg -- Unloads a seglist loaded with InternalLoadSeg() (V36)

Synopsis

success = InternalUnLoadSeg(seglist,FreeFunc) D0 D1 A1

BOOL InternalUnLoadSeg(BPTR,void (*)(STRPTR,ULONG))

Function

Unloads a seglist using freefunc to free segments. Freefunc is called as for InternalLoadSeg. NOTE: will call Close() for overlaid seglists.

Inputs

seglist - Seglist to be unloaded FreeFunc - Function called to free memory

Results

success - returns whether everything went OK (since this may close files). Also returns FALSE if seglist was NULL.

Bugs

Really should use tags

`IoErr()`¶

IoErr -- Return extra information from the system

Synopsis

error = IoErr() D0

LONG IoErr(void)

Function

Most I/O routines return zero to indicate an error. When this happens (or whatever the defined error return for the routine) this routine may be called to determine more information. It is also used in some routines to pass back a secondary result.

Note: there is no guarantee as to the value returned from IoErr()
after a successful operation, unless to specified by the routine.

Results

error - integer

See also

Fault(), PrintFault(), SetIoErr()

`IsFileSystem()`¶

IsFileSystem -- returns whether a Dos handler is a filesystem (V36)

Synopsis

result = IsFileSystem(name) D0 D1

BOOL IsFileSystem(STRPTR)

Function

Returns whether the device is a filesystem or not. A filesystem supports seperate files storing information. It may also support sub-directories, but is not required to. If the filesystem doesn't support this new packet, IsFileSystem() will use Lock(":",...) as an indicator.

Inputs

name - Name of device in question, with trailing ':'.

Results

result - Flag to indicate if device is a file system

See also

Lock()

`IsInteractive()`¶

IsInteractive -- Discover whether a file is "interactive"

Synopsis

status = IsInteractive( file ) D0 D1

BOOL IsInteractive(BPTR)

Function

The return value 'status' indicates whether the file associated with the file handle 'file' is connected to a virtual terminal.

Inputs

file - BCPL pointer to a file handle

Results

status - boolean

`LoadSeg()`¶

LoadSeg -- Scatterload a loadable file into memory

Synopsis

seglist = LoadSeg( name [,table, fh] ) D0 D1 D2 D3

BPTR LoadSeg(STRPTR [,BPTR, BPTR] )

Function

The file 'name' should be a load module produced by the linker. LoadSeg() scatterloads the CODE, DATA and BSS segments into memory, chaining together the segments with BPTR's on their first words. The end of the chain is indicated by a zero. There can be any number of segments in a file. All necessary relocation is handled by LoadSeg().

In the event of an error any blocks loaded will be unloaded and a
NULL result returned.

If the module is correctly loaded then the output will be a pointer
at the beginning of the list of blocks. Loaded code is unloaded via
a call to UnLoadSeg().

Inputs

name - pointer to a null-terminated string, or NULL. table - BPTR to a hunk table, only used for overlayed segments. fh - BPTR to a file handle from which the overlayed segment is loaded.

Results

seglist - BCPL pointer to a seglist In case name is non-NULL and scatter loading aborted due to a HUNK_STOP, i.e. an overlayed binary was found, LoadSeg() checks whether the first hunk has at offset 8 the magic long word constant $ABCD. The binary shall reserve four long words following this magic identifier. The four long words are then filled in as follows: - overlay file handle. This is to be used for loading subsequent overlay segments, and shall be passed in D3 to continue scatter loading. This file handle is closed by UnLoadSeg(). - pointer to the overlay table, the contents of the HUNK_OVERLAY. - global vector of the dos.library, for BCPL code, also required for UnLoadSeg().

Notes

While this function is generally documented to take only a single argument, and the Os prototypes only document the one-argument variant, it actually takes two additional arguments in D2 and D3 if the first argument is NULL. This calling convention of LoadSeg() is used for programs using overlay segments, and then loads an overlay segment according to the hunk table in D2, from the file handle in D3.

`Lock()`¶

Lock -- Lock a directory or file

Synopsis

lock = Lock( name, accessMode ) D0 D1 D2

BPTR Lock(STRPTR, LONG)

Function

A filing system lock on the file or directory 'name' is returned if possible.

If the accessMode is ACCESS_READ, the lock is a shared read lock;
if the accessMode is ACCESS_WRITE then it is an exclusive write
lock.  Do not use random values for mode.

If Lock() fails (that is, if it cannot obtain a filing 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 fl_Link or fl_Access fields.

Inputs

name - pointer to a null-terminated string accessMode - integer

Results

lock - BCPL pointer to a lock

`LockDosList()`¶

LockDosList -- Locks the specified Dos Lists for use (V36)

Synopsis

dlist = LockDosList(flags) D0 D1

DosList*LockDosList(ULONG)

Function

Locks the dos device list in preparation to walk the list. If the list is 'busy' then this routine will not return until it is available. This routine "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 1.3 compatibility, it also does a Forbid() - this will probably be removed at some future time. The 1.3 Forbid() locking of this list had some race conditions. The pointer returned by this 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.

Note for 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.

As an example, here's how you can search for all volumes of a specific
name and do something with them:

2.0 way:

    dl = LockDosList(LDF_VOLUMES|LDF_READ);
    while (dl = FindDosEntry(dl,name,LDF_VOLUMES))
    {
        Add to list of volumes to process or break out of
        the while loop.
        (You could try using it here, but I advise
        against it for compatability reasons if you
        are planning on continuing to examine the list.)
    }

    process list of volumes saved above, or current entry if
    you're only interested in the first one of that name.

    UnLockDosList(LDF_VOLUMES|LDF_READ);
              \* must not use dl after this! *\

1.3/2.0 way:

    if (version >= 36)
        dl = LockDosList(LDF_VOLUMES|LDF_READ);
    else {
        Forbid();
        /* tricky! note dol_Next is at offset 0! */
        dl = &(...->di_DeviceList);
    }

    while (version >= 36 ?
            dl = FindDosEntry(dl,name,LDF_VOLUMES) :
                dl = yourfindentry(dl,name,DLT_VOLUME))
    {
        Add to list of volumes to process, or break out of
        the while loop.
        Do NOT lock foo1/foo2 here if you will continue
        to examine the list - it breaks the forbid
        and the list may change on you.
    }

    process list of volumes saved above, or current entry if
    you're only interested in the first one of that name.

    if (version >= 36)
        UnLockDosList(LDF_VOLUMES|LDF_READ);
    else
        Permit();
    \* must not use dl after this! *\
    ...

    struct DosList *
    yourfindentry (struct DosList *dl, STRPTRname, type)
    {
    \* tricky - depends on dol_Next being at offset 0,
       and the initial ptr being a ptr to di_DeviceList! *\
        while (dl = dl->dol_Next)
        {
            if (dl->dol_Type == type &&
            stricmp(name,BADDR(dl->dol_Name)+1) == 0)
            {
            break;
            }
        }
        return dl;
    }

Inputs

flags - Flags stating which types of nodes you want to lock.

Results

dlist - Pointer to the head of the list. NOT a valid node!

`LockRecord()`¶

LockRecord -- Locks a portion of a file (V36)

Synopsis

success = LockRecord(fh,offset,length,mode,timeout) D0 D1 D2 D3 D4 D5

BOOL LockRecord(BPTR,ULONG,ULONG,ULONG,ULONG)

Function

This locks a portion of a file for exclusive access. Timeout is how long to wait in ticks (1/50 sec) for the record to be available.

Valid modes are:
    REC_EXCLUSIVE
    REC_EXCLUSIVE_IMMED
    REC_SHARED
    REC_SHARED_IMMED
For the IMMED modes, the timeout is ignored.

Record locks are tied to the filehandle used to create them.  The
same filehandle can get any number of exclusive locks on the same
record, for example.  These are cooperative locks, they only
affect other people calling LockRecord().

Inputs

fh - File handle for which to lock the record offset - Record start position length - Length of record in bytes mode - Type of lock requester timeout - Timeout interval in ticks. 0 is legal.

Results

success - Success or failure

Bugs

In 2.0 through 2.02 (V36), LockRecord() only worked in the ramdisk. Attempting to lock records on the disk filesystem causes a crash. This was fixed for V37.

`LockRecords()`¶

LockRecords -- Lock a series of records (V36)

Synopsis

success = LockRecords(record_array,timeout) D0 D1 D2

BOOL LockRecords(RecordLock*,ULONG)

Function

This locks several records within a file for exclusive access. Timeout is how long to wait in ticks for the records to be available. The wait is applied to each attempt to lock each record in the list. It is recommended that you always lock a set of records in the same order to reduce possibilities of deadlock.

The array of RecordLock structures is terminated by an entry with
rec_FH of NULL.

Inputs

record_array - List of records to be locked timeout - Timeout interval. 0 is legal

Results

success - Success or failure

Bugs

See LockRecord()

`MakeDosEntry()`¶

MakeDosEntry -- Creates a DosList structure (V36)

Synopsis

newdlist = MakeDosEntry(name, type) D0 D1 D2

DosList*MakeDosEntry(STRPTR, LONG)

Function

Create a DosList structure, including allocating a name and correctly null-terminating the BSTR. It also sets the dol_Type field, and sets all other fields to 0. This routine should be eliminated and replaced by a value passed to AllocDosObject()!

Inputs

name - name for the device/volume/assign node. type - type of node.

Results

newdlist - The new device entry or NULL.

`MakeLink()`¶

MakeLink -- Creates a filesystem link (V36)

Synopsis

success = MakeLink( name, dest, soft ) D0 D1 D2 D3

BOOL MakeLink( STRPTR, LONG, LONG )

Function

Create a filesystem link from 'name' to dest. For "soft-links", dest is a pointer to a null-terminated path string. For "hard- links", dest is a lock (BPTR). 'soft' is FALSE for hard-links, non-zero otherwise.

Soft-links are resolved at access time by a combination of the
filesystem (by returning ERROR_IS_SOFT_LINK to dos), and by
Dos (using ReadLink() to resolve any links that are hit).

Hard-links are resolved by the filesystem in question.  A series
of hard-links to a file are all equivalent to the file itself.
If one of the links (or the original entry for the file) is
deleted, the data remains until there are no links left.

Inputs

name - Name of the link to create dest - CPTR to path string, or BPTR lock soft - FALSE for hard-links, non-zero for soft-links

Results

Success - boolean

Bugs

In V36, soft-links didn't work in the ROM filesystem. This was fixed for V37.

See also

ReadLink(), Open(), Lock()

`MatchEnd()`¶

MatchEnd -- Free storage allocated for MatchFirst()/MatchNext() (V36)

Synopsis

MatchEnd(AnchorPath) D1

VOID MatchEnd(struct AnchorPath*)

Function

Return all storage associated with a given search.

Inputs

AnchorPath - Anchor used for MatchFirst()/MatchNext() MUST be longword aligned!

`MatchFirst()`¶

MatchFirst -- Finds file that matches pattern (V36)

Synopsis

error = MatchFirst(pat, AnchorPath) D0 D1 D2

LONG MatchFirst(STRPTR,struct AnchorPath*)

Function

Locates the first file or directory that matches a given pattern. MatchFirst() is passed your pattern (you do not pass it through ParsePattern() - MatchFirst() does that for you), and the control structure. MatchFirst() normally initializes your AnchorPath structure for you, and returns the first file that matched your pattern, or an error. Note that MatchFirst()/MatchNext() are unusual for Dos in that they return 0 for success, or the error code (see ), instead of the application getting the error code from IoErr().

When looking at the result of MatchFirst()/MatchNext(), the ap_Info
field of your AnchorPath has the results of an Examine() of the object.
You normally get the name of the object from fib_FileName, and the
directory it's in from ap_Current->an_Lock.  To access this object,
normally you would temporarily CurrentDir() to the lock, do an action
to the file/dir, and then CurrentDir() back to your original directory.
This makes certain you affect the right object even when two volumes
of the same name are in the system.  You can use ap_Buf (with
ap_Strlen) to get a name to report to the user.

To initialize the AnchorPath structure (particularily when reusing
it), set ap_BreakBits to the signal bits (CDEF) that you want to take
a break on, or NULL, if you don't want to convenience the user.
ap_Flags should be set to any flags you need or all 0's otherwise.
ap_FoundBreak should be cleared if you'll be using breaks.

If you want to have the FULL PATH NAME of the files you found,
allocate a buffer at the END of this structure, and put the size of
it into ap_Strlen.  If you don't want the full path name, make sure
you set ap_Strlen to zero.  In this case, the name of the file, and
stats are available in the ap_Info, as per usual.

Then call MatchFirst() and then afterwards, MatchNext() with this
structure.  You should check the return value each time (see below)
and take the appropriate action, ultimately calling MatchEnd() when
there are no more files or you are done.  You can tell when you are
done by checking for the normal AmigaDOS return code
ERROR_NO_MORE_ENTRIES.

Note: patterns with trailing slashes may cause MatchFirst()/MatchNext()
to return with an ap_Current->an_Lock on the object, and a filename
of the empty string ("").

See ParsePattern() for more information on the patterns.

Inputs

pat - Pattern to search for AnchorPath - Place holder for search. MUST be longword aligned!

Results

error - 0 for success or error code. (Opposite of most Dos calls!)

Bugs

In V36, there were a number of bugs with MatchFirst()/MatchNext(). One was that if you entered a directory with a name like "df0:l" using DODIR, it would re-lock the full string "df0:l", which can cause problems if the disk has changed. It also had problems with patterns such as #?/abc/def - the ap_Current->an_Lock would not be on the directory def is found in. ap_Buf would be correct, however. It had similar problems with patterns with trailing slashes. These have been fixed for V37 and later.

A bug that has not been fixed for V37 concerns a pattern of a
single directory name (such as "l").  If you enter such a directory
via DODIR, it re-locks l relative to the current directory.  Thus
you must not change the current directory before calling MatchNext()
with DODIR in that situation.  If you aren't using DODIR to enter
directories you can ignore this.  This may be fixed in some upcoming
release.

In case the pattern does not contain any wildcards, and refers to
a softlink that cannot be resolved, MatchFirst() returns
ERROR_OBJECT_NOT_FOUND. A workaround is to replace the file name
by a pattern that resolves only to this particular file name, e.g.
foo -> foo(|).

`MatchNext()`¶

MatchNext - Finds the next file or directory that matches pattern (V36)

Synopsis

error = MatchNext(AnchorPath) D0 D1

LONG MatchNext(struct AnchorPath*)

Function

Locates the next file or directory that matches a given pattern. See for more information. Various bits in the flags allow the application to control the operation of MatchNext().

See MatchFirst() for other notes.

Inputs

AnchorPath - Place holder for search. MUST be longword aligned!

Results

error - 0 for success or error code. (Opposite of most Dos calls)

Bugs

See MatchFirst().

`MatchPattern()`¶

MatchPattern -- Checks for a pattern match with a string (V36)

Synopsis

match = MatchPattern(pat, str) D0 D1 D2

BOOL MatchPattern(STRPTR, STRPTR)

Function

Checks for a pattern match with a string. The pattern must be a tokenized string output by ParsePattern(). This routine is case-sensitive.

NOTE: this routine is highly recursive.  You must have at least
1500 free bytes of stack to call this (it will cut off it's
recursion before going any deeper than that and return failure).
That's _currently_ enough for about 100 levels deep of #, (, ~, etc.

Inputs

pat - Special pattern string to match as returned by ParsePattern() str - String to match against given pattern

Results

match - success or failure of pattern match. On failure, IoErr() will return 0 or ERROR_TOO_MANY_LEVELS (starting with V37 - before that there was no stack checking).

`MatchPatternNoCase()`¶

MatchPatternNoCase -- Checks for a pattern match with a string (V37)

Synopsis

match = MatchPatternNoCase(pat, str) D0 D1 D2

BOOL MatchPatternNoCase(STRPTR, STRPTR)

Function

Checks for a pattern match with a string. The pattern must be a tokenized string output by ParsePatternNoCase(). This routine is case-insensitive.

NOTE: this routine is highly recursive.  You must have at least
1500 free bytes of stack to call this (it will cut off it's
recursion before going any deeper than that and return failure).
That's _currently_ enough for about 100 levels deep of #, (, ~, etc.

Inputs

pat - Special pattern string to match as returned by ParsePatternNoCase() str - String to match against given pattern

Results

match - success or failure of pattern match. On failure, IoErr() will return 0 or ERROR_TOO_MANY_LEVELS (starting with V37 - before that there was no stack checking).

Bugs

See ParsePatternNoCase().

`MaxCli()`¶

MaxCli -- returns the highest CLI process number possibly in use (V36)

Synopsis

number = MaxCli() D0

LONG MaxCli(void)

Function

Returns the highest CLI number that may be in use. CLI numbers are reused, and are usually as small as possible. To find all CLIs, scan using FindCliProc() from 1 to MaxCLI(). The number returned by MaxCli() may change as processes are created and destroyed.

Results

number - The highest CLI number that may be in use.

See also

FindCliProc(), Cli()

`NameFromFH()`¶

NameFromFH -- Get the name of an open filehandle (V36)

Synopsis

success = NameFromFH(fh, buffer, len) D0 D1 D2 D3

BOOL NameFromFH(BPTR, STRPTR, LONG)

Function

Returns a fully qualified path for the filehandle. This routine is guaranteed not to write more than len characters into the buffer. The name will be null-terminated. See NameFromLock() for more information.

Inputs

fh - Lock of object to be examined. buffer - Buffer to store name. len - Length of buffer.

Results

success - Success/failure indicator.

See also

NameFromLock()

`NameFromLock()`¶

NameFromLock -- Returns the name of a locked object (V36)

Synopsis

success = NameFromLock(lock, buffer, len) D0 D1 D2 D3

BOOL NameFromLock(BPTR, STRPTR, LONG)

Function

Returns a fully qualified path for the lock. This routine is guaranteed not to write more than len characters into the buffer. The name will be null-terminated. NOTE: if the volume is not mounted, the system will request it (unless of course you set pr_WindowPtr to -1). If the volume is not mounted or inserted, it will return an error. If the lock passed in is NULL, "SYS:" will be returned. If the buffer is too short, an error will be returned, and IoErr() will return ERROR_LINE_TOO_LONG.

Inputs

lock - Lock of object to be examined. buffer - Buffer to store name. len - Length of buffer.

Results

success - Success/failure indicator.

Notes

Unless the lock passed in is NULL, this function requires a shared lock to work. If an exclusive lock is used, it will return an error.

Bugs

Should return the name of the boot volume instead of SYS: for a NULL lock.

See also

NameFromFH(), Lock()

`NewLoadSeg()`¶

NewLoadSeg -- Improved version of LoadSeg for stacksizes (V36)

Synopsis

seglist = NewLoadSeg(file, tags) D0 D1 D2

BPTR NewLoadSeg(STRPTR,TagItem*)

seglist = NewLoadSegTagList(file, tags) D0 D1 D2

BPTR NewLoadSegTagList(STRPTR,TagItem*)

seglist = NewLoadSegTags(file, ...)

BPTR NewLoadSegTags(STRPTR, ...)

Function

Does a LoadSeg on a file, and takes additional actions based on the tags supplied.

Clears unused portions of Code and Data hunks (as well as BSS hunks).
(This also applies to InternalLoadSeg() and LoadSeg()).

NOTE to overlay users: NewLoadSeg() does NOT return seglist in
both D0 and D1, as LoadSeg does.  The current ovs.asm uses LoadSeg(),
and assumes returns are in D1.  We will support this for LoadSeg()
ONLY.

Inputs

file - Filename of file to load, shall not be NULL. tags - pointer to tagitem array

Results

seglist - Seglist loaded, or NULL

Bugs

No tags are currently defined. This call runs into the function as LoadSeg(), and thus misinterprets the tags in case the name pointer is NULL.

`NextDosEntry()`¶

NextDosEntry -- Get the next Dos List entry (V36)

Synopsis

newdlist = NextDosEntry(dlist,flags) D0 D1 D2

DosList*NextDosEntry(DosList*,ULONG)

Function

Find the next Dos List entry of the right type. You MUST have locked the types you're looking for. Returns NULL if there are no more of that type in the list.

Inputs

dlist - The current device entry. flags - What type of entries to look for.

Results

newdlist - The next device entry of the right type or NULL.

`Open()`¶

Open -- Open a file for input or output

Synopsis

file = Open( name, accessMode ) D0 D1 D2

BPTR Open(STRPTR, LONG)

Function

The named file is opened and a file handle returned. If the accessMode is MODE_OLDFILE, an existing file is opened for reading or writing. If the value is MODE_NEWFILE, a new file is created for writing. MODE_READWRITE opens a file with an shared lock, but creates it if it didn't exist. Open types are documented in the or include file.

The 'name' can be a filename (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 pr_ConsoleTask. 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 routine IoErr().

Inputs

name - pointer to a null-terminated string accessMode - integer

Results

file - BCPL pointer to a file handle

`OpenFromLock()`¶

OpenFromLock -- Opens a file you have a lock on (V36)

Synopsis

fh = OpenFromLock(lock) D0 D1

BPTR OpenFromLock(BPTR)

Function

Given a lock, this routine performs an open on that lock. If the open succeeds, the lock is (effectively) relinquished, and should not be UnLock()ed or used. If the open fails, the lock is still usable. The lock associated with the file internally is of the same access mode as the lock you gave up - shared is similar to MODE_OLDFILE, exclusive is similar to MODE_NEWFILE.

Inputs

lock - Lock on object to be opened.

Results

fh - Newly opened file handle or NULL for failure

Bugs

In the original V36 autodocs, this was shown (incorrectly) as taking a Mode parameter as well. The prototypes and pragmas were also wrong.

`Output()`¶

Output -- Identify the programs' initial output file handle

Synopsis

file = Output() D0

BPTR Output(void)

Function

Output() is used to identify the initial output stream allocated when the program was initiated. Never close the filehandle returned by Output().

Results

file - BCPL pointer to a file handle

See also

Input(), ErrorOutput()

`ParentDir()`¶

ParentDir -- Obtain the parent of a directory or file

Synopsis

newlock = ParentDir( lock ) D0 D1

BPTR ParentDir(BPTR)

Function

The argument 'lock' is associated with a given file or directory. ParentDir() returns 'newlock' which is associated the parent directory of 'lock'.

Taking the ParentDir() of the root of the current filing system
returns a NULL (0) lock.  Note this 0 lock represents the root of
file system that you booted from (which is, in effect, the parent
of all other file system roots.)

Inputs

lock - BCPL pointer to a lock

Results

newlock - BCPL pointer to a lock

`ParentOfFH()`¶

ParentOfFH -- returns a lock on the parent directory of a file (V36)

Synopsis

lock = ParentOfFH(fh) D0 D1

BPTR ParentOfFH(BPTR)

Function

Returns a shared lock on the parent directory of the filehandle.

Inputs

fh - Filehandle you want the parent of.

Results

lock - Lock on parent directory of the filehandle or NULL for failure.

`ParsePattern()`¶

ParsePattern -- Create a tokenized string for MatchPattern() (V36)

Synopsis

IsWild = ParsePattern(Source, Dest, DestLength) d0 D1 D2 D3

LONG ParsePattern(STRPTR, STRPTR, LONG)

Function

Tokenizes a pattern, for use by MatchPattern(). Also indicates if there are any wildcards in the pattern (i.e. whether it might match more than one item). Note that Dest must be at least 2 times as large as Source plus bytes to be (almost) 100% certain of no buffer overflow. This is because each input character can currently expand to 2 tokens (with one exception that can expand to 3, but only once per string). Note: this implementation may change in the future, so you should handle error returns in all cases, but the size above should still be a reasonable upper bound for a buffer allocation.

The patterns are fairly extensive, and approximate some of the ability
of Unix/grep "regular expression" patterns.  Here are the available
tokens:

?   Matches a single character.
#   Matches the following expression 0 or more times.
(ab|cd) Matches any one of the items seperated by '|'.
~   Negates the following expression.  It matches all strings
    that do not match the expression (aka ~(foo) matches all
    strings that are not exactly "foo").
[abc]   Character class: matches any of the characters in the class.
[~bc]   Character class: matches any of the characters not in the
    class.
a-z Character range (only within character classes).
%   Matches 0 characters always (useful in "(foo|bar|%)").
*   Synonym for "#?", not available by default in 2.0.  Available
    as an option that can be turned on.

"Expression" in the above table means either a single character
(ex: "#?"), or an alternation (ex: "#(ab|cd|ef)"), or a character
class (ex: "#[a-zA-Z]").

Inputs

source - unparsed wildcard string to search for. dest - output string, gets tokenized version of input. DestLength - length available in destination (should be at least as twice as large as source + 2 bytes).

Results

IsWild - 1 means there were wildcards in the pattern, 0 means there were no wildcards in the pattern, -1 means there was a buffer overflow or other error

Bugs

In V37 this call didn't always set IoErr() to something useful on an error. Fixed in V39.

`ParsePatternNoCase()`¶

ParsePatternNoCase -- Create a tokenized string for MatchPatternNoCase() (V37)

Synopsis

IsWild = ParsePatternNoCase(Source, Dest, DestLength) d0 D1 D2 D3

LONG ParsePatternNoCase(STRPTR, STRPTR, LONG)

Function

Tokenizes a pattern, for use by MatchPatternNoCase(). Also indicates if there are any wildcards in the pattern (i.e. whether it might match more than one item). Note that Dest must be at least 2 times as large as Source plus 2 bytes.

For a description of the wildcards, see ParsePattern().

Inputs

Results

IsWild - 1 means there were wildcards in the pattern, 0 means there were no wildcards in the pattern, -1 means there was a buffer overflow or other error

Bugs

In V37 this call didn't always set IoErr() to something useful on an error. Fixed in V39. In V37, it didn't properly convert character-classes ([x-y]) to upper case. Workaround: convert the input pattern to upper case using ToUpper() from utility.library before calling ParsePatternNoCase(). Fixed in V39 dos.

`PathPart()`¶

PathPart -- Returns a pointer to the end of the next-to-last (V36) component of a path.

Synopsis

fileptr = PathPart( path ) D0 D1

STRPTR PathPart( STRPTR )

Function

This function returns a pointer to the character after the next-to-last component of a path specification, which will normally be the directory name. If there is only one component, it returns a pointer to the beginning of the string. The only real difference between this and FilePart() is the handling of '/'.

Inputs

path - pointer to an path string. May be relative to the current directory or the current disk.

Results

fileptr - pointer to the end of the next-to-last component of the path.

Example

PathPart("xxx:yyy/zzz/qqq") would return a pointer to the last '/'. PathPart("xxx:yyy") would return a pointer to the first 'y').

See also

FilePart(), AddPart()

`PrintFault()`¶

PrintFault -- Prints the text associated with a DOS error code (V36)

Synopsis

success = PrintFault(code, header) D0 D1 D2

BOOL PrintFault(LONG, STRPTR)

Function

This routine obtains the error message text for the given error code. This is similar to the Fault() function, except that the output is written to the default error channel (V47), or if that is not present, the output channel with buffered output. The value returned by IoErr() is set to the code passed in.

Inputs

code - Error code header - header to output before error text

Results

success - Success/failure code.

`PutErrStr()`¶

PutErrStr -- Writes a string to the error output (buffered) (V47)

Synopsis

error = PutErrStr(str) D0 D1

LONG PutErrStr(STRPTR)

Function

This routine writes an unformatted string to the error output. No newline is appended to the string and any error is returned. This routine is buffered. In case the error output is not set, the string is printed to the default output.

Inputs

str - Null-terminated string to be written to error output

Results

error - 0 for success, -1 for any error. NOTE: this is opposite most Dos function returns!

`PutStr()`¶

PutStr -- Writes a string to the default output (buffered) (V36)

Synopsis

error = PutStr(str) D0 D1

LONG PutStr(STRPTR)

Function

This routine writes an unformatted string to the default output. No newline is appended to the string and any error is returned. This routine is buffered.

Inputs

str - Null-terminated string to be written to default output

Results

error - 0 for success, -1 for any error. NOTE: this is opposite most Dos function returns!

`Read()`¶

Read -- Read bytes of data from a file

Synopsis

actualLength = Read( file, buffer, length ) D0 D1 D2 D3

LONG Read(BPTR, void *, LONG)

Function

Data can be copied using a combination of Read() and Write(). Read() reads bytes of information from an opened file (represented here by the argument 'file') into the buffer given. The argument 'length' is the length of the buffer given.

The value returned is the length of the information actually read.
So, when 'actualLength' is greater than zero, the value of
'actualLength' is the the number of characters read. Usually Read
will try to fill up your buffer before returning. A value of zero
means that end-of-file has been reached. Errors are indicated by a
value of -1.

Note: this is an unbuffered routine, i.e.the request is passed
directly to the filesystem. Buffered I/O is more efficient for
small reads and writes; see FGetC().

Inputs

file - BCPL pointer to a file handle buffer - pointer to buffer length - integer

Results

actualLength - integer

`ReadArgs()`¶

ReadArgs - Parse the command line input (V36)

Synopsis

result = ReadArgs(template, array, rdargs) D0 D1 D2 D3

RDArgs* ReadArgs(STRPTR, LONG *,RDArgs*)

Function

Parses and argument string according to a template. Normally gets the arguments by reading buffered IO from Input(), but also can be made to parse a string. MUST be matched by a call to FreeArgs().

ReadArgs() parses the commandline according to a template that is
passed to it.  This specifies the different command-line options and
their types.  A template consists of a list of options.  Options are
named in "full" names where possible (for example, "Quick" instead of
"Q").  Abbreviations can also be specified by using "abbrev=option"
(for example, "Q=Quick").

Options in the template are separated by commas.  To get the results
of ReadArgs(), you examine the array of longwords you passed to it
(one entry per option in the template).  This array should be cleared
(or initialized to your default values) before passing to ReadArgs().
Exactly what is put in a given entry by ReadArgs() depends on the type
of option.  The default is a string (a sequence of non-whitespace
characters, or delimited by quotes, which will be stripped by
ReadArgs()), in which case the entry will be a pointer.

Options can be followed by modifiers, which specify things such as
the type of the option.  Modifiers are specified by following the
option with a '/' and a single character modifier.  Multiple modifiers
can be specified by using multiple '/'s.  Valid modifiers are:

/S - Switch.  This is considered a boolean variable, and will be
     set if the option name appears in the command-line.  The entry
     is the boolean (0 for not set, non-zero for set).

/K - Keyword.  This means that the option will not be filled unless
     the keyword appears.  For example if the template is "Name/K",
     then unless "Name=<string>" or "Name <string>" appears in the
     command line, Name will not be filled.

/N - Number.  This parameter is considered a decimal number, and will
     be converted by ReadArgs.  If an invalid number is specified,
     an error will be returned.  The entry will be a pointer to the
     longword number (this is how you know if a number was specified).

/T - Toggle.  This is similar to a switch, but when specified causes
     the boolean value to "toggle".  Similar to /S.

/A - Required.  This keyword must be given a value during command-line
     processing, or an error is returned.

/F - Rest of line.  If this is specified, the entire rest of the line
     is taken as the parameter for the option, even if other option
     keywords appear in it.

/M - Multiple strings.  This means the argument will take any number
     of strings, returning them as an array of strings.  Any arguments
     not considered to be part of another option will be added to this
     option.  Only one /M should be specified in a template.  Example:
     for a template "Dir/M,All/S" the command-line "foo bar all qwe"
     will set the boolean "all", and return an array consisting of
     "foo", "bar", and "qwe".  The entry in the array will be a pointer
     to an array of string pointers, the last of which will be NULL.

     There is an interaction between /M parameters and /A parameters.
     If there are unfilled /A parameters after parsing, it will grab
     strings from the end of a previous /M parameter list to fill the
     /A's.  This is used for things like Copy ("From/A/M,To/A").

ReadArgs() returns a struct RDArgs if it succeeds.  This serves as an
"anchor" to allow FreeArgs() to free the associated memory.  You can
also pass in a struct RDArgs to control the operation of ReadArgs()
(normally you pass NULL for the parameter, and ReadArgs() allocates
one for you).  This allows providing different sources for the
arguments, providing your own string buffer space for temporary
storage, and extended help text.  See <dos/rdargs.h> for more
information on this.  Note: if you pass in a struct RDArgs, you must
still call FreeArgs() to release storage that gets attached to it,
but you are responsible for freeing the RDArgs yourself.

If you pass in a RDArgs structure, you MUST reset (clear or set)
RDA_Buffer for each new call to RDArgs.  The exact behavior if you
don't do this varies from release to release and case to case; don't
count on the behavior!

See BUGS regarding passing in strings.

Inputs

template - formatting string array - array of longwords for results, 1 per template entry rdargs - optional rdargs structure for options. AllocDosObject should be used for allocating them if you pass one in.

Results

result - a struct RDArgs or NULL for failure.

Bugs

In V36, there were a couple of minor bugs with certain argument combinations (/M/N returned strings, /T didn't work, and /K and /F interacted). Also, a template with a /K before any non-switch parameter will require the argument name to be given in order for line to be accepted (i.e. "parm/K,xyzzy/A" would require "xyzzy=xxxxx" in order to work - "xxxxx" would not work). If you need to avoid this for V36, put /K parameters after all non-switch parameters. These problems should be fixed for V37.

Currently (V37 and before) it requires any strings passed in to have
newlines at the end of the string.  This may or may not be fixed in
the future.

`ReadItem()`¶

ReadItem - reads a single argument/name from command line (V36)

Synopsis

value = ReadItem(buffer, maxchars, input) D0 D1 D2 D3

LONG ReadItem(STRPTR, LONG,CSource*)

Function

Reads a "word" from either Input() (buffered), or via CSource, if it is non-NULL (see for more information). Handles quoting and some '' substitutions (e and *n) inside quotes (only). See dos/dos.h for a listing of values returned by ReadItem() (ITEM_XXXX). A "word" is delimited by whitespace, quotes, '=', or an EOF.

ReadItem always unreads the last thing read (UnGetC(fh,-1)) so the
caller can find out what the terminator was.

Inputs

buffer - buffer to store word in. maxchars - size of the buffer input - CSource input or NULL (uses FGetC(Input()))

Results

ITEM_EQUAL the reader detected an '=' sign ITEM_ERROR an error was detected ITEM_NOTHING end of the stream, new line or ';' ITEM_UNQUOTED the item was read successfully and is not quoted ITEM_QUOTED the item was read successfully and is quoted

Bugs

Doesn't actually unread the terminator.

`ReadLink()`¶

ReadLink -- Reads the path for a soft filesystem link (V36)

Synopsis

success = ReadLink( port, lock, path, buffer, size) D0 D1 D2 D3 D4 D5

BOOL ReadLink(MsgPort*, BPTR, STRPTR, STRPTR, ULONG)

Function

ReadLink() takes a lock/name pair (usually from a failed attempt to use them to access an object with packets), and asks the filesystem to find the softlink and fill buffer with the modified path string. You then start the resolution process again by calling GetDeviceProc() with the new string from ReadLink().

Soft-links are resolved at access time by a combination of the
filesystem (by returning ERROR_IS_SOFT_LINK to dos), and by
Dos (using ReadLink() to resolve any links that are hit).

Inputs

port - msgport of the filesystem lock - lock this path is relative to on the filesystem path - path that caused the ERROR_IS_SOFT_LINK buffer - pointer to buffer for new path from handler. size - size of buffer.

Results

Success - boolean

Bugs

In V36, soft-links didn't work in the ROM filesystem. This was fixed for V37.

`Relabel()`¶

Relabel -- Change the volume name of a volume (V36)

Synopsis

success = Relabel(volumename,name) D0 D1 D2

BOOL Relabel(STRPTR,STRPTR)

Function

Changes the volumename of a volume, if supported by the filesystem.

Inputs

volumename - Full name of device to rename (with ':') newname - New name to apply to device (without ':')

Results

success - Success/failure indicator

`RemAssignList()`¶

RemAssignList -- Remove an entry from a multi-dir assign (V36)

Synopsis

success = RemAssignList(name,lock) D0 D1 D2

BOOL RemAssignList(STRPTR,BPTR)

Function

Removes an entry from a multi-directory assign. The entry removed is the first one for which SameLock with 'lock' returns that they are on the same object. The lock for the entry in the list is unlocked (not the entry passed in).

Inputs

name - Name of device to remove lock from (without trailing ':') lock - Lock associated with the object to remove from the list

Results

success - Success/failure indicator.

Bugs

In V36 through V39.23 dos, it would fail to remove the first lock in the assign. Fixed in V39.24 dos (after the V39.106 kickstart).

`RemDosEntry()`¶

RemDosEntry -- Removes a Dos List entry from it's list (V36)

Synopsis

success = RemDosEntry(dlist) D0 D1

BOOL RemDosEntry(DosList*)

Function

This removes an entry from the Dos Device list. The memory associated with the entry is NOT freed. NOTE: you must have locked the Dos List with the appropriate flags before calling this routine. Handler writers should see the AddDosEntry() caveats about locking and use a similar workaround to avoid deadlocks.

Inputs

dlist - Device list entry to be removed.

Results

success - Success/failure indicator

`RemSegment()`¶

RemSegment - Removes a resident segment from the resident list (V36)

Synopsis

success = RemSegment(segment) D0 D1

BOOL RemSegment(Segment*)

Function

Removes a resident segment from the Dos resident segment list, unloads it, and does any other cleanup required. Will only succeed if the seg_UC (usecount) is 0.

Inputs

segment - the segment to be removed

Results

success - success or failure.

See also

FindSegment(), AddSegment()

`Rename()`¶

Rename -- Rename a directory or file

Synopsis

success = Rename( oldName, newName ) D0 D1 D2

BOOL Rename(STRPTR, STRPTR)

Function

Rename() attempts to rename the file or directory specified as 'oldName' with the name 'newName'. If the file or directory 'newName' exists, Rename() fails and returns an error. Both 'oldName' and the 'newName' can contain a directory specification. In this case, the file will be moved from one directory to another.

Note: it is impossible to Rename() a file from one volume to
another.

Inputs

oldName - pointer to a null-terminated string newName - pointer to a null-terminated string

Results

success - boolean

See also

Relabel()

`ReplyPkt()`¶

ReplyPkt -- replies a packet to the person who sent it to you (V36)

Synopsis

ReplyPkt(packet, result1, result2) D1 D2 D3

void ReplyPkt(DosPacket*, LONG, LONG)

Function

This returns a packet to the process which sent it to you. In addition, puts your pr_MsgPort address in dp_Port, so using ReplyPkt() again will send the message to you. (This is used in "ping-ponging" packets between two processes). It uses result 1 & 2 to set the dp_Res1 and dp_Res2 fields of the packet.

Inputs

packet - packet to reply, assumed to set up correctly. result1 - first result result2 - secondary result

`RunCommand()`¶

RunCommand -- Runs a program using the current process (V36)

Synopsis

rc = RunCommand(seglist, stacksize, argptr, argsize) D0 D1 D2 D3 D4

LONG RunCommand(BPTR, ULONG, STRPTR, ULONG)

Function

Runs a command on your process/cli. Seglist may be any language, including BCPL programs. Stacksize is in bytes. argptr is a null- terminated string, argsize is its length. Returns the returncode the program exited with in d0. Returns -1 if the stack couldn't be allocated.

NOTE: the argument string MUST be terminated with a newline to work
properly with ReadArgs() and other argument parsers.

RunCommand also takes care of setting up the current input filehandle
in such a way that ReadArgs() can be used in the program, and restores
the state of the buffering before returning.  It also sets the value
returned by GetArgStr(), and restores it before returning.  NOTE:
the setting of the argument string in the filehandle was added in V37.

It's usually appropriate to set the command name (via
SetProgramName()) before calling RunCommand().  RunCommand() sets
the value returned by GetArgStr() while the command is running.

Inputs

seglist - Seglist of command to run. stacksize - Number of bytes to allocate for stack space argptr - Pointer to argument command string. argsize - Number of bytes in argument command.

Results

rc - Return code from executed command. -1 indicates failure

`SameDevice()`¶

SameDevice -- Are two locks are on partitions of the device? (V37)

Synopsis

same = SameDevice(lock1, lock2) D0 D1 D2

BOOL SameDevice( BPTR, BPTR )

Function

SameDevice() returns whether two locks refer to partitions that are on the same physical device (if it can figure it out). This may be useful in writing copy routines to take advantage of asynchronous multi-device copies.

Entry existed in V36 and always returned 0.

Inputs

lock1,lock2 - locks

Results

same - whether they're on the same device as far as Dos can determine.

`SameLock()`¶

SameLock -- returns whether two locks are on the same object (V36)

Synopsis

value = SameLock(lock1, lock2) D0 D1 D2

LONG SameLock(BPTR, BPTR)

Function

Compares two locks. Returns LOCK_SAME if they are on the same object, LOCK_SAME_VOLUME if on different objects on the same volume, and LOCK_DIFFERENT if they are on different volumes. Always compare for equality or non-equality with the results, in case new return values are added.

Inputs

lock1 - 1st lock for comparison lock2 - 2nd lock for comparison

Results

value - LOCK_SAME, LOCK_SAME_VOLUME, or LOCK_DIFFERENT

Bugs

Should do more extensive checks for NULL against a real lock, checking to see if the real lock is a lock on the root of the boot volume.

In V36, it would return LOCK_SAME_VOLUME for different volumes on the
same handler.  Also, LOCK_SAME_VOLUME was LOCK_SAME_HANDLER (now
an obsolete define, see <dos/dos.h>).

`ScanStackToken()`¶

ScanStackToken -- Find default stack of segment list (V47)

Synopsis

stack = ScanStackToken(segment, defaultstack) D0 D1 D2

LONG ScanStackToken(BPTR segment, LONG defaultstack)

Function

This function scans a segment list for the magic stack token, i.e. "$STACK:" and adjusts the default stack size passed in accordingly. The return value is the maximum of the second argument, and all stack tokens found in the segment list.

Inputs

segment -- a segment list, as returned by LoadSeg() defaultstack -- default stack size in bytes

Results

The stack size recorded in the segment list, computed as the maximum of the passed in size and all stack tokens found in the segment list.

Notes

This function uses a variant of the Knuth-Morris-Pratt fast string search algorithm to keep the complexity time as low as possible.

`Seek()`¶

Seek -- Set the current position for reading and writing

Synopsis

oldPosition = Seek( file, position, mode ) D0 D1 D2 D3

LONG Seek(BPTR, LONG, LONG)

Function

Seek() sets the read/write cursor for the file 'file' to the position 'position'. This position is used by both Read() and Write() as a place to start reading or writing. The result is the current absolute position in the file, or -1 if an error occurs, in which case IoErr() can be used to find more information. '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.

So that to find out where you are, seek zero from current. The end
of the file is a Seek() positioned by zero from end. You cannot
Seek() beyond the end of a file.

Inputs

file - BCPL pointer to a file handle position - integer mode - integer

Results

oldPosition - integer

Bugs

The V36 and V37 ROM filesystem (and V36/V37 l:fastfilesystem) returns the current position instead of -1 on an error. It sets IoErr() to 0 on success, and an error code on an error. This bug was fixed in the V39 filesystem.

See also

Read(), Write(), SetFileSize()

`SelectError()`¶

SelectError -- Select a filehandle as the error output channel (V47)

Synopsis

old_fh = SelectError(fh) D0 D1

BPTR SelectError(BPTR)

Function

Set the current error stream as the default error stream for the process. This changes the value returned by ErrorOutput(). old_fh should be closed or saved as needed.

Inputs

fh - Newly error output handle

Results

old_fh - Previous error output filehandle or 0 if not set.

`SelectInput()`¶

SelectInput -- Select a filehandle as the default input channel (V36)

Synopsis

old_fh = SelectInput(fh) D0 D1

BPTR SelectInput(BPTR)

Function

Set the current input as the default input for the process. This changes the value returned by Input(). old_fh should be closed or saved as needed.

Inputs

fh - Newly default input handle

Results

old_fh - Previous default input filehandle

See also

Input(), SelectOutput(), Output()

`SelectOutput()`¶

SelectOutput -- Select a filehandle as the default output channel (V36)

Synopsis

old_fh = SelectOutput(fh) D0 D1

BPTR SelectOutput(BPTR)

Function

Set the current output as the default output for the process. This changes the value returned by Output(). old_fh should be closed or saved as needed.

Inputs

fh - Newly desired output handle

Results

old_fh - Previous current output

See also

Output(), SelectInput(), Input()

`SendPkt()`¶

SendPkt -- Sends a packet to a handler (V36)

Synopsis

SendPkt(packet, port, replyport) D1 D2 D3

void SendPkt(DosPacket*,MsgPort*,MsgPort*)

Function

Sends a packet to a handler and does not wait. All fields in the packet must be initialized before calling this routine. The packet will be returned to replyport. If you wish to use this with WaitPkt(), use the address of your pr_MsgPort for replyport.

Inputs

packet - packet to send, must be initialized and have a message. port - pr_MsgPort of handler process to send to. replyport - MsgPort for the packet to come back to.

Notes

Callable from a task.

`SetArgStr()`¶

SetArgStr -- Sets the arguments for the current process (V36)

Synopsis

oldptr = SetArgStr(ptr) D0 D1

STRPTR SetArgStr(STRPTR)

Function

Sets the arguments for the current program. The ptr MUST be reset to it's original value before process exit.

Inputs

ptr - pointer to new argument string.

Results

oldptr - the previous argument string

See also

GetArgStr(), RunCommand()

`SetComment()`¶

SetComment -- Change a files' comment string

Synopsis

success = SetComment( name, comment ) D0 D1 D2

BOOL SetComment(STRPTR, STRPTR)

Function

SetComment() sets a comment on a file or directory. The comment is a pointer to a null-terminated string of up to 80 characters in the current ROM filesystem (and RAM:). Note that not all filesystems will support comments (for example, NFS usually will not), or the size of comment supported may vary.

Inputs

name - pointer to a null-terminated string comment - pointer to a null-terminated string

Results

success - boolean

`SetConsoleTask()`¶

SetConsoleTask -- Sets the default console for the process (V36)

Synopsis

oldport = SetConsoleTask(port) D0 D1

MsgPort*SetConsoleTask(MsgPort*)

Function

Sets the default console task's port (pr_ConsoleTask) for the current process.

Inputs

port - The pr_MsgPort of the default console handler for the process

Results

oldport - The previous ConsoleTask value.

See also

GetConsoleTask(), Open()

`SetCurrentDirName()`¶

SetCurrentDirName -- Sets the directory name for the process (V36)

Synopsis

success = SetCurrentDirName(name) D0 D1

BOOL SetCurrentDirName(STRPTR)

Function

Sets the name for the current dir in the cli structure. If the name is too long to fit, a failure is returned, and the old value is left intact. It is advised that you inform the user of this condition. This routine is safe to call even if there is no CLI structure.

Inputs

name - Name of directory to be set.

Results

success - Success/failure indicator

Bugs

This clips to a fixed (1.3 compatible) size.

See also

GetCurrentDirName()

`SetFileDate()`¶

SetFileDate -- Sets the modification date for a file or dir (V36)

Synopsis

success = SetFileDate(name, date) D0 D1 D2

BOOL SetFileDate(STRPTR,DateStamp*)

Function

Sets the file date for a file or directory. Note that for the Old File System and the Fast File System, the date of the root directory cannot be set. Other filesystems may not support setting the date for all files/directories.

Inputs

name - Name of object date - New modification date

Results

success - Success/failure indication

Bugs

It is file system dependent whether SetFileDate() on an object that is exclusively locked proceeds without error. The FFS refuses such an attempt, the RAM-Handler does not.

`SetFileSize()`¶

SetFileSize -- Sets the size of a file (V36)

Synopsis

newsize = SetFileSize(fh, offset, mode) D0 D1 D2 D3

LONG SetFileSize(BPTR, LONG, LONG)

Function

Changes the file size, truncating or extending as needed. Not all handlers may support this; be careful and check the return code. If the file is extended, no values should be assumed for the new bytes. If the new position would be before the filehandle's current position in the file, the filehandle will end with a position at the end-of-file. If there are other filehandles open onto the file, the new size will not leave any filehandle pointing past the end-of-file. You can check for this by looking at the new size (which would be different than what you requested).

The seek position should not be changed unless the file is made
smaller than the current seek position.  However, see BUGS.

Do NOT count on any specific values to be in any extended area.

Inputs

fh - File to be truncated/extended. offset - Offset from position determined by mode. mode - One of OFFSET_BEGINNING, OFFSET_CURRENT, or OFFSET_END.

Results

newsize - position of new end-of-file or -1 for error.

Bugs

The RAM: filesystem releases before V47 and the normal Amiga filesystem act differently where the file position is left after SetFileSize() that extended the size of a file. Older RAM: left you incorrectly at the new end of the file. This has been fixed in the V47 RAM-Handler. The correct behaviour is to leave the current seek position alone, unless the new position is less than the current position, in which case you're left at the new EOF.

The best workaround is to not make any assumptions about the seek
position after SetFileSize().

See also

Seek()

`SetFileSysTask()`¶

SetFileSysTask -- Sets the default filesystem for the process (V36)

Synopsis

oldport = SetFileSysTask(port) D0 D1

MsgPort*SetFileSysTask(MsgPort*)

Function

Sets the default filesystem task's port (pr_FileSystemTask) for the current process.

Inputs

port - The pr_MsgPort of the default filesystem for the process

Results

oldport - The previous FileSysTask value

See also

GetFileSysTask(), Open()

`SetIoErr()`¶

SetIoErr -- Sets the value returned by IoErr() (V36)

Synopsis

oldcode = SetIoErr(code) D0 D1

LONG SetIoErr(LONG);

Function

This routine sets up the secondary result (pr_Result2) return code (returned by the IoErr() function).

Inputs

code - Code to be returned by a call to IoErr.

Results

oldcode - The previous error code.

See also

IoErr(), Fault(), PrintFault()

`SetMode()`¶

SetMode - Set the current behavior of a handler (V36)

Synopsis

success = SetMode(fh, mode) D0 D1 D2

BOOL SetMode(BPTR, LONG)

Function

SetMode() sends an ACTION_SCREEN_MODE packet to the handler in question, normally for changing a CON: handler to raw mode or vice-versa. For CON:, use 1 to go to RAW: mode, 0 for CON: mode, and 2 for the medium mode within which TAB and history functions create immediate CSI sequences, but lines are buffered. This is an extension of the V47 CON: handler.

Inputs

fh - filehandle mode - The new mode you want

Results

success - Boolean

`SetOwner()`¶

SetOwner -- Set owner information for a file or directory (V39)

Synopsis

success = SetOwner( name, owner_info ) D0 D1 D2

BOOL SetOwner (STRPTR, LONG)

Function

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.

This entrypoint did not exist in V36, so you must open at least V37
dos.library to use it.  V37 dos.library will return FALSE to this
call.

Inputs

name - pointer to a null-terminated string owner_info - owner uid (31:16) and group id (15:0)

Results

success - boolean

Notes

This call transmits a packet of type ACTION_SET_OWNER to the file handler that is resolved by the name.

`SetProgramDir()`¶

SetProgramDir -- Sets the directory returned by GetProgramDir (V36)

Synopsis

oldlock = SetProgramDir(lock) D0 D1

BPTR SetProgramDir(BPTR)

Function

Sets a shared lock on the directory the program was loaded from. This can be used for a program to find data files, etc, that are stored with the program, or to find the program file itself. NULL is a valid input. This can be accessed via GetProgramDir() or by using paths relative to PROGDIR:.

Inputs

lock - A lock on the directory the current program was loaded from

Results

oldlock - The previous ProgramDir.

See also

GetProgramDir(), Open()

`SetProgramName()`¶

SetProgramName -- Sets the name of the program being run (V36)

Synopsis

success = SetProgramName(name) D0 D1

BOOL SetProgramName(STRPTR)

Function

Sets the name for the program in the cli structure. If the name is too long to fit, a failure is returned, and the old value is left intact. It is advised that you inform the user if possible of this condition, and/or set the program name to an empty string. This routine is safe to call even if there is no CLI structure.

Inputs

name - Name of program to use.

Results

success - Success/failure indicator.

Bugs

This clips to a fixed (1.3 compatible) size.

See also

GetProgramName()

`SetPrompt()`¶

SetPrompt -- Sets the CLI/shell prompt for the current process (V36)

Synopsis

success = SetPrompt(name) D0 D1

BOOL SetPrompt(STRPTR)

Function

Sets the text for the prompt in the cli structure. If the prompt is too long to fit, a failure is returned, and the old value is left intact. It is advised that you inform the user of this condition. This routine is safe to call even if there is no CLI structure.

Inputs

name - Name of prompt to be set.

Results

success - Success/failure indicator.

Bugs

This clips to a fixed (1.3 compatible) size.

See also

GetPrompt()

`SetProtection()`¶

SetProtection -- Set protection for a file or directory

Synopsis

success = SetProtection( name, mask ) D0 D1 D2

BOOL SetProtection (STRPTR, LONG)

Function

SetProtection() sets the protection attributes on a file or directory. See for a listing of protection bits.

Before V36, the ROM filesystem didn't respect the Read and Write
bits.  In V36 or later and in the FFS, the Read and Write
bits are respected.

The archive bit should be cleared by the filesystem whenever the file
is changed.  Backup utilities will generally set the bit after
backing up each file.

The V36 Shell looks at the execute bit, and will refuse to execute
a file if it is set. It also checks the script ('s') bit and then
calls the Execute command on such scripts.

Other bits are defined in the <dos/dos.h> include files.  Rather
than referring to bits by number you should use the definitions in
<dos/dos.h>.

Inputs

name - pointer to a null-terminated string mask - the protection mask required

Results

success - boolean

Notes

the low order four bits, i.e. 'rwed', are low-active, i.e. a bit stored as zero indicates that the corresponding property of a file is active. All other bits are high-active.

See also

SetComment(), Examine(), ExNext()

`SetVar()`¶

SetVar -- Sets a local or environment variable (V36)

Synopsis

success = SetVar( name, buffer, size, flags ) D0 D1 D2 D3 D4

BOOL SetVar(STRPTR, STRPTR, LONG, ULONG )

Function

Sets a local or environment variable. It is advised to only use ASCII strings inside variables, but not required.

Inputs

name - pointer to an variable name. Note variable names follow filesystem syntax and semantics. buffer - a user allocated area which contains a string that is the value to be associated with this variable. size - length of the buffer region in bytes. -1 means buffer contains a null-terminated string. flags - combination of type of var to set (low 8 bits), and flags to control the behavior of this routine. Currently defined flags include:

    GVF_LOCAL_ONLY - set a local (to your process) variable.
    GVF_GLOBAL_ONLY - set a global environment variable.

    The default is to set a local environment variable.

Results

success - If non-zero, the variable was sucessfully set, FALSE indicates failure.

Bugs

LV_VAR is the only type that can be global. Releases prior V47 did not clear the e protection bit of the file(s) created in ENV: and ENVARC: SetEnv did that manually. If a variable name contained two slashes such as //, releases prior to V47 would have crashed. This has been fixed.

See also

GetVar(), DeleteVar(), FindVar()

`SetVBuf()`¶

SetVBuf -- set buffering modes and size (V39)

Synopsis

error = SetVBuf(fh, buff, type, size) D0 D1 D2 D3 D4

LONG SetVBuf(BPTR, STRPTR, LONG, LONG)

Function

Changes the buffering modes and buffer size for a filehandle. With buff == NULL, the current buffer will be deallocated and a new one of (approximately) size will be allocated. If buffer is non-NULL, it will be used for buffering and must be at least max(size,208) bytes long, and MUST be longword aligned. If size is -1, then only the buffering mode will be changed.

Note that a user-supplied buffer will not be freed if it is later
replaced by another SetVBuf() call, nor will it be freed if the
filehandle is closed.

Has no effect on the buffersize of filehandles that were not created
by AllocDosObject().

Inputs

fh - Filehandle buff - buffer pointer for buffered I/O or NULL. MUST be LONG-aligned! type - buffering mode (see ) size - size of buffer for buffered I/O (sizes less than 208 bytes will be rounded up to 208), or -1.

Results

error - 0 if successful. NOTE: opposite of most dos functions! NOTE: fails if someone has replaced the buffer without using SetVBuf() - RunCommand() does this. Remember to check error before freeing user-supplied buffers!

Bugs

Not implemented until after V39. From V36 up to V39, always returned 0.

Changing the size of the buffer on a file opened on "NIL:" will
lead to memory corruption and/or a crash when that file is
closed in V36-V47.24.

`SplitName()`¶

SplitName -- splits out a component of a pathname into a buffer (V36)

Synopsis

newpos = SplitName(name, separator, buf, oldpos, size) D0 D1 D2 D3 D4 D5

WORD SplitName(STRPTR, UBYTE, STRPTR, WORD, LONG)

Function

This routine splits out the next piece of a name from a given file name. Each piece is copied into the buffer, truncating at size-1 characters. The new position is then returned so that it may be passed in to the next call to splitname. If the separator is not found within 'size' characters, then size-1 characters plus a null will be put into the buffer, and the position of the next separator will be returned.

If a a separator cannot be found, -1 is returned (but the characters
from the old position to the end of the string are copied into the
buffer, up to a maximum of size-1 characters).  Both strings are
null-terminated.

This function is mainly intended to support handlers.

Inputs

name - Filename being parsed. separator - Separator charactor to split by. buf - Buffer to hold separated name. oldpos - Current position in the file. size - Size of buf in bytes (including null termination).

Results

newpos - New position for next call to splitname. -1 for last one.

Bugs

In V36 and V37, path portions greater than or equal to 'size' caused the last character of the portion to be lost when followed by a separator. Fixed for V39 dos. For V36 and V37, the suggested work- around is to call SplitName() with a buffer one larger than normal (for example, 32 bytes), and then set buf[size-2] to '0' (for example, buf[30] = '\0';).

See also

FilePart(), PathPart(), AddPart()

`StartNotify()`¶

StartNotify -- Starts notification on a file or directory (V36)

Synopsis

success = StartNotify(notifystructure) D0 D1

BOOL StartNotify(NotifyRequest*)

Function

Posts a notification request. Do not modify the notify structure while it is active. You will be notified when the file or directory changes. For files, you will be notified after the file is closed. Not all filesystems will support this: applications should NOT require it. In particular, most network filesystems won't support it.

Inputs

notifystructure - A filled-in NotifyRequest structure

Results

success - Success/failure of request

Bugs

The V36 floppy/HD filesystem doesn't actually send notifications. The V36 ram handler (ram:) does. This has been fixed for V37.

See also

EndNotify()

`StrToDate()`¶

StrToDate -- Converts a string to a DateStamp (V36)

Synopsis

success = StrToDate( datetime ) D0 D1

BOOL StrToDate(DateTime* )

Function

Converts a human readable text string into an AmigaDOS DateStamp.

Inputs

DateTime - a pointer to an initialized DateTime structure.

The DateTime structure should be initialized as follows:

dat_Stamp - ignored on input.

dat_Format - a format byte which specifies the format of the
    dat_StrDat.  This can be any of the following (Note:
    If the value used is something other than those below,
    the default of FORMAT_DOS will be used):

    FORMAT_DOS:   AmigaDOS format (dd-mmm-yy).

    FORMAT_INT:   International format (yy-mmm-dd).

    FORMAT_USA:   American format (mm-dd-yy).

    FORMAT_CDN:   Canadian format (dd-mm-yy).

    FORMAT_DEF:   default format for locale.

dat_Flags - a flags byte. The only flag which affects this
      function is:

    DTF_FUTURE:   If set, indicates that strings such
              as (stored in dat_StrDate) "Monday"
              refer to "next" monday. Otherwise,
              if clear, strings like "Monday"
              refer to "last" monday.

    DTF_SUBST:    Ignored by this function

dat_StrDay - ignored by this function.

dat_StrDate - pointer to valid string representing the date.
      This can be a "DTF_SUBST" style string such as
      "Today", "Tomorrow", "Monday", or it may be a string
      as specified by the dat_Format byte. This will be
      converted to the ds_Days portion of the DateStamp.
      If this pointer is NULL, DateStamp->ds_Days will not
      be affected.

dat_StrTime - Pointer to a buffer which contains the time in
      the text format hh:mm:ss. This will be converted
      to the ds_Minutes and ds_Ticks portions of the
      DateStamp. If this pointer is NULL, ds_Minutes and
      ds_Ticks will be unchanged.

Results

success - a zero return indicates that a conversion could not be performed. A non-zero return indicates that the DateTime.dat_Stamp variable contains the converted values.

Notes

The dat_StrDate and dat_StrTime members must either point to a NUL-terminated string or they must be NULL.

The dat_Format FORMAT_DEF option will only be supported if the
locale.library is currently active. Otherwise, FORMAT_DOS will
be used instead which can lead to conversion errors.

See also

DateStamp(), DateToStr()

`StrToLong()`¶

StrToLong -- string to long value (decimal) (V36)

Synopsis

characters = StrToLong(string,value) D0 D1 D2

LONG StrToLong(STRPTR, LONG *)

Function

Converts decimal string into LONG value. Returns number of characters converted. Skips over leading spaces & tabs (included in count). If no decimal digits are found (after skipping leading spaces & tabs), StrToLong returns -1 for characters converted, and puts 0 into value.

Inputs

string - Input string. value - Pointer to long value. Set to 0 if no digits are converted.

Results

result - Number of characters converted or -1.

Bugs

Before V39, if there were no convertible characters it returned the number of leading white-space characters (space and tab in this case).

`SystemTagList()`¶

SystemTagList -- Have a shell execute a command line (V36)

Synopsis

error = SystemTagList(command, tags) D0 D1 D2

LONG SystemTagList(STRPTR,TagItem*)

error = System(command, tags) D0 D1 D2

LONG System(STRPTR,TagItem*)

error = SystemTags(command, Tag1, ...)

LONG SystemTags(STRPTR, ULONG, ...)

Function

Similar to Execute(), creates a new shell in various ways. Spawns a Shell process to execute the command. Depending on its arguments, may or may not wait for the command(s) to be completed. If it does wait, returns the return code of the command, or returns 0 for success in all cases, or -1 if the command(s) could not be run for any reason.

If System() waits for completion, the input and output filehandles
will not be closed by System, you must close them (if needed) after
System returns if you specified them via SYS_Input or SYS_Output.
The command stream SYS_Command/SYS_CmdName will always be closed on
success, regardless of other arguments.

By default the new process will use your current Input() and Output()
filehandles.  Normal Shell command-line parsing will be done
including redirection on 'command'.  The current directory and path
will be inherited from your process.  Your path will be used to find
the command if no path is specified.

Note that you may NOT pass the same filehandle for both SYS_Input
and SYS_Output.  If you want input and output to both be to the same
CON: window, pass a SYS_Input of a filehandle on the CON: window,
and pass a SYS_Output of NULL.  The shell will automatically set
the default Output() stream to the window you passed via SYS_Input,
by opening "*" on that handler, or "NIL:" if "*" could not be
opened.

If used with the SYS_Asynch flag, it WILL close both its input and
output filehandles after running the command (even if these were
your Input() and Output()!).

If command is NULL, System() will read from SYS_CmdStream, or
SYS_Input if the former is not given. It will return immediately
and execute such commands in background, even without SYS_Asynch
set. (V40) This mode is used to implement RUN, see NOTES below.

SYS_Asynch can also be set along with a command or a SYS_CmdStream.
In such a case, the shell will execute the commands from SYS_CmdStream
or command asynchronously, and after its depletion, will contine to
read commands interactively from the input file handle. (V47)
This mode is used to implement the NEWSHELL command, see NOTES.

Normally uses the boot (ROM) shell, but other shells can be specified
via SYS_UserShell and SYS_CustomShell.  Normally, you should send
things written by the user to the UserShell.  The UserShell defaults
to the same shell as the boot shell.

The tags are passed through to CreateNewProc(), tags that conflict
with SystemTagList() will be filtered out. This allows setting
things like priority, etc for the new process.  The tags that are
currently filtered out are:

    NP_Seglist
    NP_FreeSeglist
    NP_Entry
    NP_Input
    NP_Output
    NP_Error
    NP_CloseInput
    NP_CloseOutput
    NP_CloseError
    NP_HomeDir
    NP_Cli

Inputs

command - Program and arguments or NULL. In case command is NULL, a new shell will be started that reads commands from SYS_CmdStream or SYS_CmdIn (if supplied) followed by SYS_Input or SYS_InName, until both sources are exhausted. See below for interaction with SYS_Asynch.

tags    - see <dos/dostags.h>.  Note that both SystemTagList()-
      specific tags and tags from CreateNewProc() may be passed.

SYS_Input:  The input stream the shell will receive. This stream
        will go into cli_StandardInput of the shell and will
        by that also become the input stream of the command
        if one is supplied. If command is NULL and
        SYS_CmdStream/CmdName is not supplied, commands are
        read from SYS_Input/InName instead. Default is the
        input stream of the caller. (BPTR)
SYS_InName: A file name that will be opened to supply an input
        stream. This is mutually exclusive to SYS_Input and
        overrides it if present. The input file will be closed
        when the command or shell returns. (const UBYTE *,V47)
SYS_Output: The output stream of the shell to be created. This
        stream will go into cli_StandardOutput of the shell
        and will by that also become the output stream of
        the command if one is supplied. Default is the output
        stream of the caller. If this is NULL, System()
        will instead use Open("*",MODE_NEWFILE) as output from
        the handler responsible for SYS_Input if this stream
        is interactive. Otherwise, or if "*" could not be
        opened, output will go to "NIL:". (BPTR)
SYS_OutName:    A file name that will be opened to supply an output
        stream. This is mutually exclusive to SYS_Output. The
        file will be closed on exit. (const UBYTE *,V47)
SYS_CmdStream:  Mutually exclusive to the command argument. If command
        is NULL, then the shell will instead read commands from
        this stream until it depletes. If SYS_Asynch is also set,
        then the shell will continue reading from SYS_Input.
        The default is NULL in which case the command to be
        executed comes either from command or SYS_Input or
        SYS_InCmd. The CmdStream is always closed on
        exit, even if it is your stream. (BPTR,V47)
SYS_CmdName:    A file name that will be openend to supply the command
        stream. This is mutually exclusive to SYS_CmdStream.
        The stream will be closed on exit. (BPTR,V47)
SYS_Asynch: Start the new shell in the background and return
        immediately. This is implicit if command is NULL and
        SYS_CmdStream is not supplied. This also implies that
        all streams will be closed by the shell/command once
        it returns, and NP_CurrentDir will be unlocked.
SYS_UserShell:  Starts the user shell, i.e. "Shell" on the resident
        list instead of the system Boot CLI.
SYS_CustomShell:Starts a custom shell from the resident list. The
        argument is a name of a resident module.

Results

error - 0 for success, result from command, or -1. Note that on error, the caller is responsible for any filehandles or other things passed in via tags. -1 will only be returned if dos could not create the new shell. If the command is not found the shell will return an error value, normally RETURN_ERROR. If System() runs a shell or command asynchronously, the result code is either 0 for success, or -1 in case the shell or command(s) could not be launched.

Notes

This call requires (as of V47) about 800 bytes stack space, and needs the caller to be a Process. There is no automatic stack extension.

The RUN command is equivalent to

System(NULL,SYS_Input,instream,SYS_Output,Output(),
       SYS_UserShell,TRUE,TAG_DONE);

where instream is a stream that delivers the command to be run.
For historical reasons, SYS_Async is implicitly set by System(),
even if not given, and the command is passed in through a faked
stream, not as first argument, see also BUGS below.

The NEWSHELL command is equivalent to

System(NULL,SYS_InName,"CON:...",
       SYS_CmdStream,Open("S:Shell-Startup",MODE_OLDFILE),
       SYS_Asynch,TRUE,SYS_UserShell,TRUE,
       NP_Name,"Shell Process",TAG_DONE);

While V47 goes through System(), previous releases of NewShell
used an undocumented legacy shell startup mechanism that has
been deprecated.

The Execute() system call is roughly equivalent to

System(NULL,SYS_CmdStream,cmd,
       SYS_Input,in,SYS_Output,out,SYS_UserShell,FALSE,
       NP_Priority,0,TAG_DONE);

where cmd is a stream that delivers the command otherwise
given as first argument to Execute(), and except that
Execute() returns DOSTRUE in case System() would return 0.

Bugs

V45 and before could release SYS_Input in some error cases. This is fixed in V47 where System() either returns the command return code, or -1, and does not release caller resources in the latter case.

In case the function returned -1 to indicate failure, any lock
passed in as NP_CurrentDir was released by V45 and before, even
though the docs stated and still state that the caller is
responsible for releasing it on error. This also got fixed in V47.
Note that in case of success, NP_CurrenDir is passed over to the
shell/command created, and is released there - this is as documented
and not a bug.

NP_Name was not honoured. Instead, the new shell always received the
name "Background CLI", even with NP_Name set. V47 fixes this.

If command is NULL, System() always detaches the shell it creates
and does not wait for its completion, even if SYS_Async is FALSE.
V47 retains this behaviour for compatibility reasons. The shell
created this way is non-interactive, signal-handling is not
forwarded to the shell, and the console port remains unset, i.e.
the configuration is as required for the Run command which uses
such parameters, see NOTES above. To create an interactive shell,
set SYS_Asynch to TRUE explicitly.

In case command is NULL and an command and input stream coincide,
System() prints the CLI number of the created shell in brackets
over the output stream as these arguments also reflect the Run
command. This should be again better implemented in the Run and not
in the System() call, but also remains as such for compatibility.

V45 and below did not clearly document that System() can (obviously)
not return a command result code in asynchronous operations.

`UnGetC()`¶

UnGetC -- Makes a char available for reading again. (buffered) (V36)

Synopsis

value = UnGetC(fh, character) D0 D1 D2

LONG UnGetC(BPTR, LONG)

Function

Pushes the character specified back into the input buffer. Every time you use a buffered read routine, you can always push back 1 character. You may be able to push back more, though it is not recommended, since there is no guarantee on how many can be pushed back at a given moment.

Passing -1 for the character will cause the last character read to
be pushed back.  If the last character read was an EOF, the next
character read will be an EOF.

Note: UnGetC can be used to make sure that a filehandle is set up
as a read filehandle.  This is only of importance if you are writing
a shell, and must manipulate the filehandle's buffer.

Inputs

fh - filehandle to use for buffered I/O character - character to push back or -1

Results

value - character pushed back, or FALSE if the character cannot be pushed back.

Bugs

In V36, UnGetC(fh,-1) after an EOF would not cause the next character read to be an EOF. This was fixed for V37.

See also

FGetC(), FPutC(), Flush()

`UnLoadSeg()`¶

UnLoadSeg -- Unload a seglist previously loaded by LoadSeg()

Synopsis

success = UnLoadSeg( seglist ) D0 D1

BOOL UnLoadSeg(BPTR)

Function

Unload a seglist loaded by LoadSeg(). 'seglist' may be zero. Overlaid segments will have all needed cleanup done, including closing files.

Inputs

seglist - BCPL pointer to a segment identifier

Results

success - returns 0 if a NULL seglist was passed or if it failed to close an overlay file. NOTE: this function returned a random value before V36!

Notes

In case the segment contains at offset 8 the magic long word $ABCD, and the fourth long word after this identifier coincides with the global vector of the dos.library, the segment is identified as an overlay segment. UnLoadSeg() then releases addition resources such as the file handle for overlay management.

`UnLock()`¶

UnLock -- Unlock a directory or file

Synopsis

UnLock( lock ) D1

void UnLock(BPTR)

Function

The filing system lock (obtained from Lock(), DupLock(), CreateDir(), etc.) is removed and deallocated.

Inputs

lock - BCPL pointer to a lock

Note

Passing zero to UnLock() is harmless.

UnLock() leaves the value returned by IoErr() unchanged. What
IoErr() returns before calling UnLock() will be the same value
IoErr() will return after UnLock() has been called.

`UnLockDosList()`¶

UnLockDosList -- Unlocks the Dos List (V36)

Synopsis

UnLockDosList(flags) D1

void UnLockDosList(ULONG)

Function

Unlocks the access on the Dos Device List. You MUST pass the same flags you used to lock the list.

Inputs

flags - MUST be the same flags passed to (Attempt)LockDosList()

`UnLockRecord()`¶

UnLockRecord -- Unlock a record (V36)

Synopsis

success = UnLockRecord(fh,offset,length) D0 D1 D2 D3

BOOL UnLockRecord(BPTR,ULONG,ULONG)

Function

This releases the specified lock on a file. Note that you must use the same filehandle you used to lock the record, and offset and length must be the same values used to lock it. Every LockRecord() call must be balanced with an UnLockRecord() call.

Inputs

fh - File handle of locked file offset - Record start position length - Length of record in bytes

Results

success - Success or failure.

Bugs

See LockRecord()

`UnLockRecords()`¶

UnLockRecords -- Unlock a list of records (V36)

Synopsis

success = UnLockRecords(record_array) D0 D1

BOOL UnLockRecords(RecordLock*)

Function

This releases an array of record locks obtained using LockRecords. You should NOT modify the record_array while you have the records locked. Every LockRecords() call must be balanced with an UnLockRecords() call.

Inputs

record_array - List of records to be unlocked

Results

success - Success or failure.

Bugs

See LockRecord()

`VFPrintf()`¶

VFPrintf -- format and print a string to a file (buffered) (V36)

Synopsis

count = VFPrintf(fh, fmt, argv) D0 D1 D2 D3

LONG VFPrintf(BPTR, STRPTR, LONG *)

count = FPrintf(fh, fmt, ...)

LONG FPrintf(BPTR, STRPTR, ...)

Function

Writes the formatted string and values to the given file. This routine is assumed to handle all internal buffering so that the formatting string and resultant formatted values can be arbitrarily long. Any secondary error code is returned in IoErr(). This routine is buffered.

Inputs

fh - Filehandle to write to fmt - RawDoFmt() style formatting string argv - Pointer to array of formatting values

Results

count - Number of bytes written or -1 (EOF) for an error

Bugs

The prototype for FPrintf() forced you in V40 to cast the first varargs parameter to LONG due to a deficiency in the program that generates fds, prototypes, and amiga.lib stubs. This was fixed in V44.

`VFWritef()`¶

VFWritef - write a BCPL formatted string to a file (buffered) (V36)

Synopsis

count = VFWritef(fh, fmt, argv) D0 D1 D2 D3

LONG VFWritef(BPTR, STRPTR, LONG *)

count = FWritef(fh, fmt, ...)

LONG FWritef(BPTR, STRPTR, ...)

Function

Writes the formatted string and values to the specified file. This routine is assumed to handle all internal buffering so that the formatting string and resultant formatted values can be arbitrarily long. The formats are in BCPL form. This routine is buffered.

Supported formats are:  (Note x is in base 36!)
    %S  - string (CSTR)
    %Tx - writes a left-justified string in a field at least
          x bytes long.
    %C  - writes a single character
    %Ox - writes a number in octal, maximum x characters wide
    %Xx - writes a number in hex, maximum x characters wide
    %Ix - writes a number in decimal, maximum x characters wide
    %N  - writes a number in decimal, any length
    %Ux - writes an unsigned number, maximum x characters wide
    %$  - ignore parameter

Note: 'x' above is actually the character value - '0'.

Inputs

fh - filehandle to write to fmt - BCPL style formatting string argv - Pointer to array of formatting values

Results

count - Number of bytes written or -1 for error

Bugs

As of V37, VFWritef() does NOT return a valid return value. In order to reduce possible errors, the prototypes supplied for the system as of V37 have it typed as VOID.

See also

VFPrintf(), FPutC()

`VolumeRequestHook()`¶

VolumeRequestHook -- Request insertion of a volume (V47)

Synopsis

res = VolumeRequestHook(volume) D0 D1

LONG VolumeRequestHook(UBYTE *volume)

Function

This function is called by the dos.library itself in case a program attempts to access a volume that is currently not mounted or not inserted. By default, this call returns -1, indicating that the dos.library should show its default requester, i.e. "Please insert volume...". The name of the requested volume is provided as argument. A user supplied application may replace this function and thus provide a more elaborate requester.

Inputs

A NUL terminated C string without terminating colon.

Results

Returns -1 in case the default dos.library volume requester should be shown. Returns 0 in case the insertion shall be aborted, i.e. canceled the request. Returns 1 in case the access shall be retried.

See also

GetDeviceProc()

`VPrintf()`¶

VPrintf -- format and print string (buffered) (V36)

Synopsis

count = VPrintf(fmt, argv) D0 D1 D2

LONG VPrintf(STRPTR, LONG *)

count = Printf(fmt, ...)

LONG Printf(STRPTR, ...)

Function

Writes the formatted string and values to Output(). This routine is assumed to handle all internal buffering so that the formatting string and resultant formatted values can be arbitrarily long. Any secondary error code is returned in IoErr(). This routine is buffered.

Note: RawDoFmt assumes 16 bit ints, so you will usually need 'l's in
your formats (ex: %ld versus %d).

Inputs

fmt - exec.library RawDoFmt() style formatting string argv - Pointer to array of formatting values

Results

count - Number of bytes written or -1 (EOF) for an error

Bugs

The prototype for Printf() forced you in V40 to cast the first varargs parameter to LONG due to a deficiency in the program that generates fds, prototypes, and amiga.lib stubs. This was fixed in V44.

`WaitForChar()`¶

WaitForChar -- Determine if chars arrive within a time limit

Synopsis

status = WaitForChar( file, timeout ) D0 D1 D2

BOOL WaitForChar(BPTR, LONG)

Function

If a character is available to be read from 'file' within the time (in microseconds) indicated by 'timeout', WaitForChar() returns -1 (TRUE). If a character is available, you can use Read() to read it. Note that WaitForChar() is only valid when the I/O stream is connected to a virtual terminal device. If a character is not available within 'timeout', a 0 (FALSE) is returned.

Inputs

file - BCPL pointer to a file handle timeout - integer

Results

status - boolean

Bugs

Due to a bug in the timer.device in V1.2/V1.3, specifying a timeout of zero for WaitForChar() can cause the unreliable timer & floppy disk operation.

See also

Read(), FGetC()

`WaitPkt()`¶

WaitPkt -- Waits for a packet to arrive at your pr_MsgPort (V36)

Synopsis

packet = WaitPkt() D0

DosPacket*WaitPkt(void);

Function

Waits for a packet to arrive at your pr_MsgPort. If anyone has installed a packet wait function in pr_PktWait, it will be called. The message will be automatically GetMsg()ed so that it is no longer on the port. It assumes the message is a dos packet. It is NOT guaranteed to clear the signal for the port.

Results

packet - the packet that arrived at the port (from ln_Name of message).

See also

SendPkt(), DoPkt(), AbortPkt()

`Write()`¶

Write -- Write bytes of data to a file

Synopsis

returnedLength = Write( file, buffer, length ) D0 D1 D2 D3

LONG Write (BPTR, void *, LONG)

Function

Write() writes bytes of data to the opened file 'file'. 'length' indicates the length of data to be transferred; 'buffer' is a pointer to the buffer. The value returned is the length of information actually written. So, when 'length' is greater than zero, the value of 'length' is the number of characters written. Errors are indicated by a value of -1.

Note: this is an unbuffered routine, i.e the request is passed
directly to the filesystem.  Buffered I/O is more efficient for
small reads and writes; see FPutC().

Inputs

file - BCPL pointer to a file handle buffer - pointer to the buffer length - integer

Results

returnedLength - integer

`WriteChars()`¶

WriteChars -- Writes bytes to the default output (buffered) (V36)

Synopsis

count = WriteChars(buf, buflen) D0 D1

LONG WriteChars(STRPTR, LONG)

Function

This routine writes a number of bytes to the default output. The length is returned. This routine is buffered.

Inputs

buf - buffer of characters to write buflen - number of characters to write

Results

count - Number of bytes written. -1 (EOF) indicates an error

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

dos.library Reference¶

Function index¶

AbortPkt()¶

AddBuffers()¶

AddDosEntry()¶

AddPart()¶

AddSegment()¶

AllocDosObject()¶

AssignAdd()¶

AssignLate()¶

AssignLock()¶

AssignPath()¶

AttemptLockDosList()¶

ChangeMode()¶

CheckSignal()¶

Cli()¶

CliInitNewcli()¶

CliInitRun()¶

Close()¶

CompareDates()¶

CreateDir()¶

CreateNewProc()¶

CreateProc()¶

CurrentDir()¶

DateStamp()¶

DateToStr()¶

Delay()¶

DeleteFile()¶

DeleteVar()¶

DeviceProc()¶

DoPkt()¶

DoShellMethod()¶

DupLock()¶

DupLockFromFH()¶

EndNotify()¶

ErrorOutput()¶

ErrorReport()¶

ExAll()¶

ExAllEnd()¶

Examine()¶

ExamineFH()¶

Execute()¶

Exit()¶

ExNext()¶

Fault()¶

FGetC()¶

FGets()¶

FilePart()¶

FindArg()¶

FindCliProc()¶

FindDosEntry()¶

FindSegment()¶

FindVar()¶

Flush()¶

Format()¶

FPutC()¶

FPuts()¶

FRead()¶

FreeArgs()¶

FreeDeviceProc()¶

FreeDosEntry()¶

FreeDosObject()¶

FWrite()¶

GetArgStr()¶

GetConsoleTask()¶

GetCurrentDir()¶

GetCurrentDirName()¶

GetDeviceProc()¶

GetFileSysTask()¶

GetProgramDir()¶

GetProgramName()¶

GetPrompt()¶

GetVar()¶

Info()¶

Inhibit()¶

Input()¶

InternalLoadSeg()¶

InternalUnLoadSeg()¶

IoErr()¶

IsFileSystem()¶

`AbortPkt()`¶

`AddBuffers()`¶

`AddDosEntry()`¶

`AddPart()`¶

`AddSegment()`¶

`AllocDosObject()`¶

`AssignAdd()`¶

`AssignLate()`¶

`AssignLock()`¶

`AssignPath()`¶

`AttemptLockDosList()`¶

`ChangeMode()`¶

`CheckSignal()`¶

`Cli()`¶

`CliInitNewcli()`¶

`CliInitRun()`¶

`Close()`¶

`CompareDates()`¶

`CreateDir()`¶

`CreateNewProc()`¶

`CreateProc()`¶

`CurrentDir()`¶

`DateStamp()`¶

`DateToStr()`¶

`Delay()`¶

`DeleteFile()`¶

`DeleteVar()`¶

`DeviceProc()`¶

`DoPkt()`¶

`DoShellMethod()`¶

`DupLock()`¶

`DupLockFromFH()`¶

`EndNotify()`¶

`ErrorOutput()`¶

`ErrorReport()`¶

`ExAll()`¶

`ExAllEnd()`¶

`Examine()`¶

`ExamineFH()`¶

`Execute()`¶

`Exit()`¶

`ExNext()`¶

`Fault()`¶

`FGetC()`¶

`FGets()`¶

`FilePart()`¶

`FindArg()`¶

`FindCliProc()`¶

`FindDosEntry()`¶

`FindSegment()`¶

`FindVar()`¶

`Flush()`¶

`Format()`¶

`FPutC()`¶

`FPuts()`¶

`FRead()`¶

`FreeArgs()`¶

`FreeDeviceProc()`¶

`FreeDosEntry()`¶

`FreeDosObject()`¶

`FWrite()`¶

`GetArgStr()`¶

`GetConsoleTask()`¶

`GetCurrentDir()`¶

`GetCurrentDirName()`¶

`GetDeviceProc()`¶

`GetFileSysTask()`¶

`GetProgramDir()`¶

`GetProgramName()`¶

`GetPrompt()`¶

`GetVar()`¶

`Info()`¶

`Inhibit()`¶

`Input()`¶

`InternalLoadSeg()`¶

`InternalUnLoadSeg()`¶

`IoErr()`¶

`IsFileSystem()`¶

`IsInteractive()`¶

`LoadSeg()`¶