AbortPkt
SYNOPSIS
AbortPkt(port, pkt)
void AbortPkt(struct MsgPort *, struct DosPacket *);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
AddBuffers
SYNOPSIS
AddBuffers(, numbuffers)
LONG AddBuffers(CONST, LONG);
DESCRIPTION
Add or remove cache memory from a filesystem
INPUTS
devicename -- NUL terminated dos device name (with ':').
numbuffers -- Number of buffers to add. May be negative
RESULT
!= 0 on success (IoErr() gives the actual number of buffers),
0 else (IoErr() gives the error code
INTERNALS
The error value in case of a filesystem error will be reported in
the io_MORE_CACHE.io_NumBuffers field.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
AddDosEntry
SYNOPSIS
AddDosEntry(dlist)
LONG AddDosEntry(struct DosList *);
DESCRIPTION
Adds a given dos list entry to the dos list. Automatically
locks the list for writing. There may be not more than one device
or assign node of the same name. There are no restrictions on
volume nodes
INPUTS
dlist - pointer to dos list entry
RESULT
!= 0 if all went well, 0 otherwise
NOTES
Since anybody who wants to use a device or volume node in the
dos list has to lock the list, filesystems may be called with
the dos list locked. So if you want to add a dos list entry
out of a filesystem don't just wait on the lock but serve all
incoming requests until the dos list is free instead.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
AddPart
SYNOPSIS
AddPart(dirname, , size)
LONG AddPart(STRPTR, CONST, ULONG);
DESCRIPTION
AddPart() will add a file, directory or other path name to a
directory path. It will take into account any pre-existing
separator characters (':','/').
If filename is a fully qualified path, then it will replace
the current value of dirname
INPUTS
dirname - the path to add the new path to
filename - the path you wish added
size - The size of the dirname buffer, must NOT be 0
RESULT
non-zero if everything succeed, FALSE if the buffer would have
overflowed.
If the buffer would have overflowed, then dirname will not have
been changed
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
EXAMPLE
UBYTE buffer[128];
buffer[0]='\0';
AddPart(buffer, "Work:", 80);
AddPart(buffer, "Programming/Include/exec", 80);
FPuts(Output(), buffer);
--> Work:Programming/Include/exec
AddPart(buffer, "/graphics", 80);
FPuts(Output(), buffer);
--> Work:Programming/Include/graphics
AddPart(buffer, "gfxmacros.h", 80);
FPuts(Output(), buffer);
--> Work:Programming/Include/graphics/gfxmacros.h
SEE ALSO
AddSegment
SYNOPSIS
AddSegment(, seg, type)
LONG AddSegment(CONST, BPTR, LONG);
DESCRIPTION
Adds a program segment to the system resident list. You can later
use these segments to run programs.
The name field should refer to a NULL terminated strings, which
will be copied. The type field determines the type of resident
program. Normal programs should have type >= 0, system segments
should have type == CMD_SYSTEM.
Note that all other values of type are reserved
INPUTS
name - Name of the segment. This is used by FindSegment().
seg - Segment to add.
type - What type of segment (initial use count
RESULT
Segment will have been added to the DOS resident list.
!= 0 success
== 0 failure
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
AddSegmentTagList
SYNOPSIS
AddSegmentTagList(tags)
LONG AddSegmentTagList(struct TagItem *);
DESCRIPTION
Adds a program segment to the system resident list. You can later
use these segments to run programs.
Available tags:
ADDS_Name (CONST_STRPTR, required)
ADDS_Seglist (BPTR)
ADDS_Filename (CONST_STRPTR, required if no seglist is given)
ADDS_Type (LONG, defaults to 0)
The name field should refer to a NULL terminated strings, which
will be copied. The type field determines the type of resident
program. Normal programs should have type >= 0, system segments
should have type == CMD_SYSTEM. The file name is only used if
no seglist is given. It is the name of the file that will be
loaded when someone tries to access this segment.
Note that all other values of type are reserved
RESULT
Segment will have been added to the DOS resident list.
!= 0 success
== 0 failure
BUGS
Uses Forbid() based locking.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
AllocDosObject
SYNOPSIS
AllocDosObject(type, tags)
APTR AllocDosObject(ULONG, struct TagItem *);
DESCRIPTION
Creates a new dos object of a given type. This memory has to be
freed with FreeDosObject
INPUTS
type - Object type.
tags - Pointer to taglist array with additional information. See
<dos/dostags.h> for a list of all supported tags
RESULT
Pointer to new object or NULL, to indicate an error
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
AssignAdd
SYNOPSIS
AssignAdd(, lock)
LONG AssignAdd(CONST, BPTR);
DESCRIPTION
Create a multi-directory assign, or adds to it if it already was one.
Do not use or free the lock after calling this function - it becomes
the assign and will be freed by the system when the assign is removed
INPUTS
name - NULL terminated name of the assign.
lock - Lock on the assigned directory
RESULT
!= 0 success, 0 on failure. IoErr() gives additional information
in that case. The lock is not freed on failure
NOTES
This will only work with an assign created with AssignLock() or
a resolved AssignLate() assign.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
AssignLate
SYNOPSIS
AssignLate(, )
LONG AssignLate(CONST, CONST);
DESCRIPTION
Create an assign for the given name, which will be resolved upon the
first reference to it. If this succeeds (i.e. the path exists and
can be locked) it will be turned into an AssignLock() type assign.
This way you can create assigns to unmounted volumes which will only
be requested when accessed
INPUTS
name -- NULL terminated name of the assign.
path -- NULL terminated path to be resolved on the first reference
RESULT
!= 0 success, 0 on failure. IoErr() gives additional information
in that case
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
AssignLock
SYNOPSIS
AssignLock(, lock)
LONG AssignLock(CONST, BPTR);
DESCRIPTION
Create an assign from a given name to a lock. Replaces any older
assignments from that name, 0 cancels the assign completely. Do not
use or free the lock after calling this function - it becomes
the assign and will be freed by the system if the assign is removed
INPUTS
name - NUL terminated name of the assign.
lock - Lock to assigned directory
RESULT
!=0 success, 0 on failure. IoErr() gives additional information
in that case. The lock is not freed on failure
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
AssignPath
SYNOPSIS
AssignPath(, )
LONG AssignPath(CONST, CONST);
DESCRIPTION
Create an assign for the given name, which will be resolved upon
each reference to it. There will be no permanent lock kept on the
specified path. This way you can create assigns to unmounted volumes
which will only be requested when accessed. Also, using AssignPath()
to assign C: to df0:c would make references go to to df0:c even if
you change the disk
INPUTS
name -- NULL terminated name of the assign.
path -- NULL terminated path to be resolved on each reference
RESULT
!= 0 in case of success, 0 on failure. IoErr() gives additional
information in that case
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
AttemptLockDosList
SYNOPSIS
AttemptLockDosList(flags)
struct DosList * AttemptLockDosList(ULONG);
DESCRIPTION
Tries to get a lock on some of the dos lists. If all went
well a handle is returned that can be used for FindDosEntry().
Don't try to busy wait until the lock can be granted - use
LockDosList() instead
INPUTS
flags -- what lists to lock
RESULT
Handle to the dos list or NULL. This is not a direct pointer
to the first list element but to a pseudo element instead
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ChangeMode
SYNOPSIS
ChangeMode(type, object, newmode)
LONG ChangeMode(ULONG, BPTR, ULONG);
DESCRIPTION
Try to change the mode used by a lock or filehandle
INPUTS
type - CHANGE_FH or CHANGE_LOCK.
object - Filehandle or lock.
newmode - New mode (see <dos/dos.h>
RESULT
!= 0 if all went well, otherwise 0. IoErr() gives additional
information in the latter case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
CheckSignal
SYNOPSIS
CheckSignal(mask)
LONG CheckSignal(LONG);
DESCRIPTION
Checks the current task to see if any of the signals specified in
the mask have been set. The mask of all signals which were set is
returned. The signals specified in the mask will be cleared
INPUTS
mask - The signal mask to check
RESULT
The mask of all signals which were set
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Cli
DESCRIPTION
Returns a pointer to the CLI structure of the current process
RESULT
Pointer to CLI structure
NOTES
Do not use this function to test if the process was started from
the shell. Check pr_CLI instead.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
CliInitNewcli
SYNOPSIS
CliInitNewcli(dp)
IPTR CliInitNewcli(struct DosPacket *);
DESCRIPTION
Set up a process to be a shell using a startup packet
INPUTS
packet -- startup arguments passed as a packet
SEE ALSO
CliInitRun
SYNOPSIS
CliInitRun(dp)
IPTR CliInitRun(struct DosPacket *);
DESCRIPTION
Set up a process to be a shell
INPUTS
dp -- startup arguments specified as a packet
SEE ALSO
Close
SYNOPSIS
Close(file)
LONG Close(BPTR);
DESCRIPTION
Close a filehandle opened with Open(). If the file was used
with buffered I/O the final write may fail and thus Close()
return an error. The file is closed in any case
INPUTS
file -- filehandle
RESULT
0 if there was an error. != 0 on success
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
CompareDates
SYNOPSIS
CompareDates(date, date)
LONG CompareDates(const struct DateStamp *, const struct DateStamp *);
DESCRIPTION
Compares two dates
INPUTS
date1, date2 - The two dates to compare
RESULT
< 0 if date1 is later than date2, == 0 if they are equal or > 0
if date2 is later than date1
NOTES
This is NOT the same ordering as strcmp() !
CreateDir
SYNOPSIS
CreateDir()
BPTR CreateDir(CONST);
DESCRIPTION
Creates a new directory under the given name. If all went an
exclusive lock on the new diretory is returned
INPUTS
name -- NUL terminated name
RESULT
Exclusive lock to the new directory or 0 if couldn't be created.
IoErr() gives additional information in that case
NOTES
You must UnLock() the returned lock to make the directory usable.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
CreateNewProc
SYNOPSIS
CreateNewProc(tags)
struct Process * CreateNewProc(struct TagItem *);
DESCRIPTION
Create a new process using the tagitem array
INPUTS
tags - information on the new process
RESULT
Pointer to the new process or NULL on error
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
CreateProc
SYNOPSIS
CreateProc(, pri, segList, stackSize)
struct MsgPort * CreateProc(CONST, LONG, BPTR, LONG);
DESCRIPTION
CreateProc() will create a new process (a process is a superset
of an exec Task), with the name 'name' and the priority 'pri'.
You should pass a segList as returned by LoadSeg() (or similar)
in the 'segList' parameter, and specify the stack size in
'stackSize'. Note that the 'stackSize' is only significant for
m68k applications.
You should really use CreateNewProc() rather than this function
as it is much more flexible
INPUTS
name - Name of the new process.
pri - Starting priority.
segList - BCPL pointer to a seglist.
stackSize - The size of the initial process m68k stack
RESULT
Pointer to the pr_MsgPort in the Process structure. Will
return NULL on failure
NOTES
This will not free the seglist when the process finishes.
This does not return a pointer to the Process structure, but
rather the MsgPort structure contained within it. You can
get the real Process structure by:
struct Process *pr;
struct MsgPort *mp;
mp = CreateProc(...);
pr = (struct Process *)((struct Task *)mp - 1);
// Shouldn't use mp after this point
INTERNALS
Basically passes this call to CreateNewProc().
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
CurrentDir
SYNOPSIS
CurrentDir(lock)
BPTR CurrentDir(BPTR);
DESCRIPTION
Sets a new directory as the current directory. Returns the old one.
0 is valid in both cases and represents the boot filesystem
INPUTS
lock - Lock for the new current directory
RESULT
Old current directory
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
DateStamp
SYNOPSIS
DateStamp(date)
struct DateStamp * DateStamp(struct DateStamp *);
DESCRIPTION
Fills the structure with the current time. Time is measured from
Jan 1, 1978
INPUTS
date - The structure to fill
RESULT
date->ds_Days is filled with the days from Jan 1, 1978.
date->ds_Minute is filled with the number of minutes elapsed in the
day. date->ds_Tick is the number of ticks elapsed in the current
minute. A tick happens 50 times a second. DateStamp() ensures that
the day and minute are consistent. All three elements are zero if
the date is unset
NOTES
The original function could only return even multiples of 50 ticks.
SEE ALSO
DateStampToPosixDateStamp
DESCRIPTION
Convert local time to UTC POSIX datestamp. The epoch of the POSIX
datestamps is 1970-01-01 00:00:00 UTC. The conversion uses the
currently set system time zone
INPUTS
ds - struct DateStamp in local time to convert from.
pds - struct PosixDateStamp to fill
RESULT
!= 0 if all went well, 0 else. The function will fail if input is
invalid
NOTES
The conversion from local time is performed using the current
system-wide timezone setting.
The datestamp conversion assumes that the date converted was
created using the same timezone as the currently configured
system-wide timezone. If this is not the case, the returned UTC
timestamp will be incorrect.
Since struct DateStamp ds_Ticks is in 1/50th second units, the
resulting pds_NSec precision is limited to this as well.
BUGS
Due to nature of daylight saving time, in timezones where DST is
observed, there is generally is a 1 hour period each year where
the local datestamp is ambigious. Thus this 1 hour perioid each
year cannot be presented precisely in local time.
INTERNALS
This function was added in dos.library V51.66.
EXAMPLE
const struct DateStamp ds = {17412, 1395, 1929};
struct PosixDateStamp pds;
if (DateStampToPosixDateStamp(&ds, &pds
SEE ALSO
DateToStr
SYNOPSIS
DateToStr(datetime)
LONG DateToStr(struct DateTime *);
DESCRIPTION
DateToStr converts an AmigaDOS DateStamp to a human
readable ASCII 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:
\begin{description}
\item{dat_Stamp} The datestamp to convert to ascii
\item{dat_Format} How to convert the datestamp into
dat_StrDate. Can be any of the following:
\begin{description}
\item{FORMAT_DOS} AmigaDOS format (dd-mmm-yy). This
is the default if you specify something other
than any entry in this list.
\item{FORMAT_INT} International format (yy-mmm-dd).
\item{FORMAT_USA} American format (mm-dd-yy).
\item{FORMAT_CDN} Canadian format (dd-mm-yy).
\item{FORMAT_DEF} default format for locale.
\end{description}
\item{dat_Flags} Modifies dat_Format. The only flag
used by this function is DTF_SUBST. If set, then
a string like "Today" or "Monday" is generated
instead of the normal format if possible.
\item{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.
\item{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.
\item{dat_StrTime} Pointer to a buffer to receive the time
of day string. If NULL, this will not be generated.
\end{description
RESULT
A zero return indicates that the DateStamp was invalid, and could
not be converted. Non-zero indicates that the call succeeded
EXAMPLE
See below
SEE ALSO
Delay
SYNOPSIS
Delay(timeout)
void Delay(ULONG);
DESCRIPTION
Waits for at least the time specified as timeout
INPUTS
timeout - the minimum time to wait in ticks (1/50 seconds
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
DeleteFile
SYNOPSIS
DeleteFile()
LONG DeleteFile(CONST);
DESCRIPTION
Tries to delete a file or directory by a given name.
May fail if the file is in use or protected from deletion
INPUTS
name - NUL terminated name
RESULT
!= 0 if the file is gone, 0 if is still there.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
DeleteVar
SYNOPSIS
DeleteVar(, flags)
LONG DeleteVar(CONST, ULONG);
DESCRIPTION
Deletes a local or environment variable.
The default is to delete a local variable if one was found,
or to delete a global environmental variable otherwise.
A global environmental variable will only be deleted for the
type LV_VAR
INPUTS
name - the name of the variable to delete. Note that variable
names follow the same syntax and semantics as filesystem
names.
flags - A combination of the type of variable (low 8 bits), and
flags to control the behaviour of this routine.
Currently defined flags:
GVF_LOCAL_ONLY - delete a local variable.
GVF_GLOBAL_ONLY - delete a global environmental variable
RESULT
If non-zero, the variable was deleted successfully,
DOSFALSE otherwise
NOTES
When the GVF_SAVE_VAR flag is set, and only one of the global
variable pair could be deleted (either the in memory or on disk
variable), DOSFALSE will be returned.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
DeviceProc
SYNOPSIS
DeviceProc()
struct MsgPort * DeviceProc(CONST);
DESCRIPTION
DeviceProc() is an obsolete function that returns the Process
responsible for a DOS device
INPUTS
name - Name of the object you wish to access. See GetDeviceProc()
for details
RESULT
Either a pointer to the message port or NULL
NOTES
You should really use GetDeviceProc() as this function caters
for all possible device types. This call exist to support old,
Kickstart 1.x era software, and should not be used in new code.
BUGS
Does not support late- and non-bound assigns, or multiple
path assigns very well. This call does not lock the filesystem in
any way, and thus the port can disappear at any point if the
volume is unmounted. Use GetDeviceProc() function instead.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
DoPkt
SYNOPSIS
DoPkt(port, action, arg, arg, arg, arg, arg)
LONG DoPkt(struct MsgPort *, LONG, LONG, LONG, LONG, LONG, LONG);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
DupLock
SYNOPSIS
DupLock(lock)
BPTR DupLock(BPTR);
DESCRIPTION
Clone a lock on a file or directory. This will only work on shared
locks
INPUTS
lock - Old lock
RESULT
The new lock or NULL in case of an error. IoErr() will give additional
information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
DupLockFromFH
SYNOPSIS
DupLockFromFH(fh)
BPTR DupLockFromFH(BPTR);
DESCRIPTION
Try to get a lock on the object selected by the filehandle
INPUTS
fh - filehandle
RESULT
The new lock or 0 in case of an error. IoErr() will give additional
information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
EndNotify
SYNOPSIS
EndNotify(notify)
void EndNotify(struct NotifyRequest *);
DESCRIPTION
End a notification (quit notifying for a request previously sent with
StartNotify
INPUTS
notify -- NotifyRequest used with StartNotify
NOTES
Message port used for the notification *must* be freed after
EndNotify().
SEE ALSO
ErrorReport
SYNOPSIS
ErrorReport(code, type, arg, device)
LONG ErrorReport(LONG, LONG, ULONG, struct MsgPort *);
INPUTS
code -- The error to put up the requester for
type -- Type of request
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
arg1 -- Argument according to type (see above)
device -- Optional handler task address (obsolete
HISTORY
23.10.99 -- SDuvan implemented
ExAll
SYNOPSIS
ExAll(lock, buffer, size, type, control)
LONG ExAll(BPTR, struct ExAllData *, LONG, LONG, struct ExAllControl *);
DESCRIPTION
Examine an entire directory
INPUTS
lock -- lock on the directory to be examined
buffer -- buffer for the data that is returned (must be aligned)
which is filled with (partial) ExAllData structures
(see NOTES)
size -- size of 'buffer' in bytes
type -- type of the data to be returned
control -- a control structure allocated by AllocDosObject
RESULT
An indicator of if ExAll() is done. If FALSE is returned, either ExAll()
has completed in which case IoErr() is ERROR_NO_MORE_ENTRIES or an
error occurred. If a non-zero value is returned ExAll() must be called
again until it returns FALSE
NOTES
The input parameter 'type' can have the following values:
ED_NAME -- filename
ED_TYPE -- type (ST_ values like in fib_EntryType)
ED_SIZE -- size in bytes
ED_PROTECTION -- protection bits
ED_DATE -- date information (3 longwords)
ED_COMMENT -- file comment (NULL if no comment exists)
ED_OWNER -- owner user and group id
ED_SIZE64 -- ed_Size64, 64-bit file size in bytes (V51.30)
ED_POSIXDATE -- ed_PosixDate. date relative to 1-jan-1970 UTC (V51.70)
This is an incremental list meaning that if you specify ED_POSIXDATE you
will get ALL attributes!
MorphOS support for specific 'type' depends on the dos.library version.
MorphOS dos.library will generate the necessary values even if the
filesystem doesn't support them natively. If MorphOS dos.library is odler
(and doesn't support a particular type), ERROR_BAD_NUMBER is returned. In
such case, you should fall back to a lower type if you wish your app to
function correctly with older MorphOS versions.
The following information is essential information on the ExAllData
structure:
ed_Next : pointer to the next entry in the buffer. The last entry
has a NULL value for ed_Next.
The control structure have the following fields.
eac_Entries : the number of entries in the buffer after a call to ExAll().
Make sure that your code handles the case when eac_Entries
is 0 and ExAll() returns TRUE.
eac_LastKey : must be initialized to 0 before calling ExAll() for the
first time.
eac_MatchString : if NULL then information on all files will be returned.
If non-NULL it's interpreted as a pointer to a string
used for pattern matching which files to return
information on. This string must have been parsed by
ParsePatternNoCase()!
eac_MatchFunc : pointer to a hook that will be called to decide if an
entry should be included in the buffer. If NULL, no
matching function will be called. The hook is called as
follows
BOOL = MatchFunc(hook, data, typeptr)
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
ExAllEnd
SYNOPSIS
ExAllEnd(lock, buffer, size, data, control)
void ExAllEnd(BPTR, struct ExAllData *, LONG, LONG, struct ExAllControl *);
DESCRIPTION
Stop an ExAll() operation before returning ERROR_NO_MORE_ENTRIES
INPUTS
The inputs should correspond to the inputs for the ExAll() function.
lock -- lock on the directory that is being examined
buffer -- buffer for data returned
size -- size of 'buffer' in bytes
type -- type of data to be returned
control -- control data structure
NOTES
The control data structure must have been allocated with AllocDosObject().
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
ExNext
SYNOPSIS
ExNext(lock, fib)
LONG ExNext(BPTR, struct FileInfoBlock *);
DESCRIPTION
Examine the next entry in a directory
INPUTS
lock -- lock on the direcory the contents of which to examine
fib -- a FileInfoBlock previously initialized by Examine()
(or used before with ExNext
RESULT
success -- a boolean telling whether the operation was successful
or not. A failure occurs also if there is no "next" entry in
the directory. Then IoErr() equals ERROR_NO_MORE_ENTRIES
NOTES
If scanning a filesystem tree recursively, you'll need to allocated a
new FilInfoBlock for each directory level.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
EXAMPLE
To examine a directory, do the following:
1. Pass a lock on the directory and a FileInfoBlock (allocated by
AllocDosObject()) to Examine().
2. Pass the same parameters to ExNext().
3. Do something with the FileInfoBlock returned.
4. Call ExNext() repeatedly until it returns FALSE and use the
information you are provided. When ExNext returns FALSE, check IoErr()
to make sure that there was no real failure (ERROR_NO_MORE_ENTRIES
SEE ALSO
ExNext64
DESCRIPTION
Examine the next entry in a directory
INPUTS
lock -- lock on the direcory the contents of which to examine
fib -- a FileInfoBlock previously initialized by Examine()
(or used before with ExNext64()), fib_Size64 contains
the size of the file. fib_NumBlocks64 contains the number
of blocks for the file.
tags -- see dos/dostags.h for EX64TAG_
RESULT
success -- a boolean telling whether the operation was successful
or not. A failure occurs also if there is no "next" entry in
the directory. Then IoErr() equals ERROR_NO_MORE_ENTRIES
NOTES
If scanning a filesystem tree recursively, you'll need to allocated a
new FileInfoBlock for each directory level.
Examine64/ExNext64()/ExamineFH64 support getting UTC timestamp of the
object by passing EX64TAG_PosixDate, TRUE tag to the function. If you
use the tag you must set fib_ActExtFlags to zero before the call. Once
success is returned, fib_PosixDate will contain the object POSIX
datestamp *if* FIBEXTF_POSIXDATE flag is set in fib_ActExtFlags. If
the flag is not set, fib_Date contains the traditional DateStamp of
the object.
Do note that fib_Date and fib_PosixDate share the same storage in the
FileInfoBlock structure and thus you *MUST* check for the flag to
process the information correctly.
See PosixDateStampToDateStamp() and DateStampToPosixDateStamp()
functions to convert between different date stamp formats.
INTERNALS
This function was added in dos.library V50.65.
EXAMPLE
To examine a directory, do the following:
1. Pass a lock on the directory and a FileInfoBlock (allocated by
AllocDosObject()) to Examine64().
2. Pass the same parameters to ExNext64().
3. Do something with the FileInfoBlock returned.
4. Call ExNext64() repeatedly until it returns FALSE and use the
information you are provided. When ExNext64 returns FALSE, check IoErr()
make sure that there was no real failure (ERROR_NO_MORE_ENTRIES
SEE ALSO
Examine
SYNOPSIS
Examine(lock, fib)
LONG Examine(BPTR, struct FileInfoBlock *);
DESCRIPTION
Fill in a FileInfoBlock structure concerning a file or directory
associated with a particular lock
INPUTS
lock -- lock to examine
fib -- FileInfoBlock where the result of the examination is stored
RESULT
A boolean telling whether the operation was successful or not
NOTES
FileInfoBlocks should be allocated with AllocDosObject(). You may make
a copy of the FileInfoBlock but, however, this copy may NOT be passed
to ExNext()!
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
Examine64
DESCRIPTION
Fill in a FileInfoBlock structure concerning a file or directory
associated with a particular lock
INPUTS
lock -- lock to examine
fib -- FileInfoBlock where the result of the examination is stored,
fib_Size64 containing the size of the file. fib_NumBlocks64
contains the number of blocks for the file.
tags -- see dos/dostags.h for EX64TAG_
RESULT
A boolean telling whether the operation was successful or not
NOTES
Examine64/ExNext64()/ExamineFH64 support getting UTC timestamp of the
object by passing EX64TAG_PosixDate, TRUE tag to the function. If you
use the tag you must set fib_ActExtFlags to zero before the call. Once
success is returned, fib_PosixDate will contain the object POSIX
datestamp *if* FIBEXTF_POSIXDATE flag is set in fib_ActExtFlags. If
the flag is not set, fib_Date contains the traditional DateStamp of
the object.
Do note that fib_Date and fib_PosixDate share the same storage in the
FileInfoBlock structure and thus you *MUST* check for the flag to
process the information correctly.
See PosixDateStampToDateStamp() and DateStampToPosixDateStamp()
functions to convert between different date stamp formats.
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
ExamineFH
SYNOPSIS
ExamineFH(fh, fib)
LONG ExamineFH(BPTR, struct FileInfoBlock *);
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ExamineFH64
DESCRIPTION
Fill in a FileInfoBlock structure concerning a file associated with
a particular filehandle
INPUTS
fh -- filehandle to examine
fib -- FileInfoBlock where the result of the examination is stored,
fib_Size64 containing the size of the file. fib_NumBlocks64
contains the number of blocks for the file.
tags -- see dos/dostags.h for EX64TAG_
RESULT
A boolean telling whether the operation was successful or not
NOTES
Examine64/ExNext64()/ExamineFH64 support getting UTC timestamp of the
object by passing EX64TAG_PosixDate, TRUE tag to the function. If you
use the tag you must set fib_ActExtFlags to zero before the call. Once
success is returned, fib_PosixDate will contain the object POSIX
datestamp *if* FIBEXTF_POSIXDATE flag is set in fib_ActExtFlags. If
the flag is not set, fib_Date contains the traditional DateStamp of
the object.
Do note that fib_Date and fib_PosixDate share the same storage in the
FileInfoBlock structure and thus you *MUST* check for the flag to
process the information correctly.
See PosixDateStampToDateStamp() and DateStampToPosixDateStamp()
functions to convert between different date stamp formats.
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
Execute
SYNOPSIS
Execute(string, input, output)
LONG Execute(STRPTR, BPTR, BPTR);
DESCRIPTION
Execute a CLI command specified in 'string'. This string may contain
features you may use on the shell commandline like redirection using >,
< or >>. Execute() doesn't return until the command(s) that should be
executed are finished.
If 'input' is not NULL, more commands will be read from this stream
until end of file is reached. 'output' will be used as the output stream
of the commands (if output is not redirected). If 'output' is NULL the
current window is used for output -- note that programs run from the
Workbench doesn't normally have a current window
INPUTS
string -- pointer to a NULL-terminated string with commands
(may be NULL)
input -- stream to use as input (may be NULL)
output -- stream to use as output (may be NULL
RESULT
Boolean tellning whether Execute() could find and start the specified
command(s). (This is NOT the return code of the command(s
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
2x-12-99 SDuvan implemented
SEE ALSO
FGetC
SYNOPSIS
FGetC(file)
LONG FGetC(BPTR);
DESCRIPTION
Get a character from a buffered file. Buffered I/O is more efficient
for small amounts of data but less for big chunks. You have to
use Flush() between buffered and non-buffered I/O or you'll
clutter your I/O stream
INPUTS
file - filehandle
RESULT
The character read or EOF if the file ended or an error happened.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FGets
SYNOPSIS
FGets(fh, buf, buflen)
STRPTR FGets(BPTR, STRPTR, ULONG);
DESCRIPTION
Read until NEWLINE (\n), EOF is encountered or buflen-1
characters have been read. If a NEWLINE is read, it will
be the last character in the buffer. The buffer will always
be \0-terminated
INPUTS
fh - Read buffered from this filehandle
buf - Put read chars in this buffer
buflen - The size of the buffer
RESULT
buf or NULL if the first thing read is EOF
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
FPutC
SYNOPSIS
FPutC(file, character)
LONG FPutC(BPTR, LONG);
INPUTS
file - Filehandle to write to.
character - Character to write
RESULT
The character written or EOF in case of an error.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FPuts
SYNOPSIS
FPuts(file, string)
LONG FPuts(BPTR, STRPTR);
INPUTS
file - Filehandle to write to.
string - String to write
RESULT
0 if all went well or EOF in case of an error.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FRead
SYNOPSIS
FRead(fh, block, blocklen, number)
LONG FRead(BPTR, APTR, ULONG, ULONG);
DESCRIPTION
Read a number of blocks from a file
INPUTS
fh - Read from this file
block - The data is put here
blocklen - This is the size of a single block
number - The number of blocks
RESULT
The number of blocks read from the file or 0 on EOF.
This function may return less than the requested number of blocks
IoErr() gives additional information in case of an error
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FRead
SYNOPSIS
FRead(file, block, blocklen, number)
LONG FRead(BPTR, APTR, ULONG, ULONG);
DESCRIPTION
Read a number of blocks from a file
INPUTS
file - Read from this file
block - The data is put here
blocklen - This is the size of a single block
number - The number of blocks
RESULT
The number of blocks read from the file or 0 on EOF.
This function may return less than the requested number of blocks
IoErr() gives additional information in case of an error
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FWrite
SYNOPSIS
FWrite(fh, block, blocklen, number)
LONG FWrite(BPTR, APTR, ULONG, ULONG);
DESCRIPTION
Write a number of blocks to a file
INPUTS
fh - Write to this file
block - The data begins here
blocklen - This is the size of a single block
number - The number of blocks
RESULT
The number of blocks written to the file or EOF on error. IoErr()
gives additional information in case of an error
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FWrite
SYNOPSIS
FWrite(file, block, blocklen, number)
LONG FWrite(BPTR, APTR, ULONG, ULONG);
DESCRIPTION
Write a number of blocks to a file
INPUTS
file - Write to this file
block - The data begins here
blocklen - This is the size of a single block
number - The number of blocks
RESULT
The number of blocks written to the file or EOF on error. IoErr()
gives additional information in case of an error
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
Fault
SYNOPSIS
Fault(code, header, buffer, len)
LONG Fault(LONG, STRPTR, STRPTR, LONG);
DESCRIPTION
Fault will obtain the error message string for the given error
code. First the header string is copied to the buffer, followed
by a ":" (colon), then the NULL terminated string for the error
message into the buffer.
By convention, error messages are ALWAYS less than 80 (plus 1 for
NULL termination), and ideally less than 60 characters.
If the error code is not know, then the string "Unknown error"
followed by the error number will be added to the string
INPUTS
code - The error code.
header - The string to prepend to the buffer before the error
text. This may be NULL in which case nothing is prepended.
buffer - The destination buffer.
len - Length of the buffer
RESULT
Number of characters placed in the buffer, may be 0
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Fault
SYNOPSIS
Fault(code, header, buffer, len)
LONG Fault(LONG, STRPTR, STRPTR, LONG);
DESCRIPTION
Fault will obtain the error message string for the given error
code. First the header string is copied to the buffer, followed
by a ":" (colon), then the NULL terminated string for the error
message into the buffer.
By convention, error messages are ALWAYS less than 80 (plus 1 for
NULL termination), and ideally less than 60 characters.
If the error code is not know, then the string "Unknown error"
followed by the error number will be added to the string
INPUTS
code - The error code.
header - The string to prepend to the buffer before the error
text. This may be NULL in which case nothing is prepended.
buffer - The destination buffer.
len - Length of the buffer
RESULT
Number of characters placed in the buffer, may be 0
FilePart
SYNOPSIS
FilePart(path)
STRPTR FilePart(STRPTR);
DESCRIPTION
Get a pointer to the last component of a path, which is normally the
filename
INPUTS
path - pointer AmigaDOS path string
May be relative to the current directory or the current disk
RESULT
A pointer to the first char of the filename
BUGS
None known.
INTERNALS
Goes from the last char of the pathname back until it finds a ':',
a '/' or until the first char reached.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
04-08-96 steigerwald hopefully filled up with something useful
;-), however untested!
07-08-96 steigerwald reworked code, implented digulla's
suggestions, thanks Aaron ;-)
added some documentation ;-)
converted all comments in function to
c++ style to avoid nested comments
again untested, cause too much AROS stuff
that is not easy to #ifdef out missing
20-08-96 steigerwald finally added all those #ifndef NO_AROS
to get this thing working stand-alone
test routine added
some bugs fixed
problem: see while and ifs below ;-(((
routine seems to work so far, but doesnt
check for path consistency so
FilePart("dh0:test/exec:now") will give a
pointer to "now" ;-)
EXAMPLE
FilePart("xxx:yyy/zzz/qqq") returns a pointer to the first 'q'.
FilePart("xxx:yyy") returns a pointer to the first 'y'.
FilePart("yyy") returns a pointer to the first 'y
SEE ALSO
FindArg
SYNOPSIS
FindArg(template, keyword)
LONG FindArg(STRPTR, STRPTR);
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
FindCliProc
SYNOPSIS
FindCliProc(num)
struct Process * FindCliProc(ULONG);
DESCRIPTION
Find a CLI process by its task number. The number must be greater
than 0
INPUTS
num - The task number of the CLI to find
RESULT
Pointer to the process if found, NULL otherwise
NOTES
The application calling this function must take care if they intend to
use the returned pointer. Calling Forbid() before the call and only
calling Permit() once you're done with it is a good strategy.
HISTORY
02.12.2000 SDuvan -- rewrote to use rootnode rn_TaskArray instead of
hacking the process lists
SEE ALSO
FindDosEntry
SYNOPSIS
FindDosEntry(dlist, , flags)
struct DosList * FindDosEntry(struct DosList *, CONST, ULONG);
DESCRIPTION
Looks for the next dos list entry with the right name. The list
must be locked for this. There may be not more than one device
or assign node of the same name. There are no restrictions on
volume nodes
INPUTS
dlist - the value given by LockDosList() or the last call to
FindDosEntry().
name - logical device name without colon. Case insensitive.
flags - the same flags as given to LockDosList() or a subset
of them
RESULT
Pointer to dos list entry found or NULL if the are no more entries
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
FindSegment
SYNOPSIS
FindSegment(name, seg, system)
struct Segment * FindSegment(STRPTR, struct Segment *, LONG);
DESCRIPTION
Search for a resident segment by name and type. FindSegment() will
return the first segment that exactly matches the name and type.
You can continue searching by specifying the last returned segment
as the seg argument
INPUTS
name - Name of the segment to search for.
seg - Start search from this point.
system - Search for a system segment
RESULT
Will return the segment structure if a match is found, otherwise
will return NULL
NOTES
FindSegment() does no locking of the segment list. You should
lock yourself. FindSegment() also does not increment the value
of the seg_UC field. If the value of seg_UC > 0, you MUST
perform user counting in order to prevent the segment from being
unloaded.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FindSegmentTagList
SYNOPSIS
FindSegmentTagList(tags)
struct Segment * FindSegmentTagList(struct TagItem *);
DESCRIPTION
Search for a resident segment by name and type. FindSegment() will
return the first segment that exactly matches the name and type.
You can continue searching by specifying the last returned segment
as the seg argument
RESULT
Will return the segment structure if a match is found, otherwise
will return NULL
NOTES
FindSegmentTags() does no locking of the segment list. You should
lock yourself. FindSegmentTags() also does not increment the value
of the seg_UC field. If the value of seg_UC > 0, you MUST
perform user counting in order to prevent the segment from being
unloaded.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FindVar
SYNOPSIS
FindVar(, type)
struct LocalVar * FindVar(CONST, ULONG);
DESCRIPTION
Finds a local variable structure
INPUTS
name - the name of the variable you wish to find. Note that
variable names follow the same syntax and semantics
as filesystem names.
type - The type of variable to be found (see <dos/var.h>).
Actually, only the lower 8 bits of "type" are used
by FindVar
RESULT
A pointer to the LocalVar structure for that variable if it was
found. If the variable wasn't found, or was of the wrong type,
NULL will be returned
INTERNALS
For every local variable, a structure of type LocalVar exists:
struct LocalVar {
struct Node lv_Node;
UWORD lv_Flags;
UBYTE *lv_Value;
ULONG lv_Len;
};
lv_Node.ln_Type
holds the variable type, either LV_VAR for regular local environment
variables or LV_ALIAS for shell aliases. dos/var.h also defines
LVF_IGNORE (for private usage by the shell)
lv_Node.ln_Name
holds the variable name (NUL terminated string)
lv_Flags
stores GVF_BINARY_VAR and GVF_DONT_NULL_TERM if given as flags to
SetVar(). It is only used by GetVar().
lv_Value
holds the variable's value
lv_Len
is the length of lv_Value
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
Flush
SYNOPSIS
Flush(file)
LONG Flush(BPTR);
DESCRIPTION
Flushes any pending writes on the file. If the file was used
for input and there is still some data to read it tries to
seek back to the expected position
INPUTS
file - filehandle
RESULT
!= 0 on success, 0 on error. IoErr() gives additional information
in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Format
SYNOPSIS
Format(devicename, volumename, dostype)
LONG Format(STRPTR, STRPTR, ULONG);
DESCRIPTION
Initialise a filesystem for use by the system. This instructs
a filesystem to write out the data that it uses to describe the
device.
The device should already have been formatted
INPUTS
devicename - Name of the device to format (with ':').
volumename - The name you wish the volume to be called.
dostype - The DOS type you wish on the disk
RESULT
!= 0 if the format was successful, 0 otherwise
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
FreeArgs
SYNOPSIS
FreeArgs(args)
void FreeArgs(struct RDArgs *);
DESCRIPTION
FreeArgs() will clean up after a call to ReadArgs(). If the
RDArgs structure was allocated by the system in a call to
ReadArgs(), then it will be freed. If however, you allocated
the RDArgs structure with AllocDosObject(), then you will
have to free it yourself with FreeDosObject
INPUTS
args - The data used by ReadArgs(). May be NULL,
in which case, FreeArgs() does nothing
RESULT
Some memory will have been returned to the system
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FreeCLIData
DESCRIPTION
Release resources associated with the struct CLIData
INPUTS
data - Pointer to struct CLIData returned by QueryCLIDataTagList
RESULT
All resources associated to the CLIData structure returned by
QueryCLIDataTagList are returned to the system
INTERNALS
This function was added in dos.library V51.51.
SEE ALSO
FreeDeviceProc
SYNOPSIS
FreeDeviceProc(dp)
void FreeDeviceProc(struct DevProc *);
DESCRIPTION
FreeDeviceProc() will clean up after a call to GetDeviceProc
INPUTS
dp - DevProc structure as returned by GetDeviceProc
RESULT
Some memory and other resources returned to the system
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
FreeDosEntry
SYNOPSIS
FreeDosEntry(dlist)
void FreeDosEntry(struct DosList *);
DESCRIPTION
Frees a dos list entry created with MakeDosEntry
INPUTS
dlist - pointer to dos list entry. May be NULL
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
FreeDosObject
SYNOPSIS
FreeDosObject(type, ptr)
ULONG FreeDosObject(ULONG, APTR);
DESCRIPTION
Frees an object allocated with AllocDosObject
INPUTS
type - object type. The same parameter as given to AllocDosObject().
ptr - Pointer to object
RESULT
0 if all went well, !=0 otherwise. (Only for DOS_FSCONTEXT
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
GetArgStr
DESCRIPTION
Returns a pointer to the argument string passed to the current
process at startup
RESULT
Pointer to argument string
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
GetConsoleTask
DESCRIPTION
Return the console handler for the current Process
INPUTS
None
RESULT
The address of the console handler, or NULL if none is set
NOTES
You will only get NULL from this call if you call it on a Task,
or when the Process is not attached to a console.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
GetCurrentDirName
SYNOPSIS
GetCurrentDirName(buf, len)
LONG GetCurrentDirName(STRPTR, LONG);
DESCRIPTION
Copies the name of the current directory from the CLI structure
into the buffer. If the buffer is too small the name is truncated,
and a failure is returned. If the current process doesn't have
a CLI structure, a 0 length string is put into the buffer and a
failure is returned
INPUTS
buf - Buffer for the name.
len - Size of the buffer in bytes
RESULT
!=0 on success, 0 on failure. IoErr() gives additional information
in that case
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
29-09-97 turrican implemented
SEE ALSO
GetDeviceProc
SYNOPSIS
GetDeviceProc(name, dp)
struct DevProc * GetDeviceProc(STRPTR, struct DevProc *);
DESCRIPTION
GetDeviceProc() will search for the filesystem handler which
you should send a command to for a specific path.
The first call to GetDeviceProc() should have the |dp| parameter
as NULL.
If the name refers to a multi-assign, dvp_Flags will have DVPF_ASSIGN
flag set. If the disk operation returns ERROR_OBJECT_NOT_FOUND (and
dvp_Flags has DVPF_ASSIGN set!) you may call GetDeviceProc again, and
thus iterate the other elements of the multi-assign. Once all elements
in the multi-assign have been iterated, the function will return NULL
and IoErr() of ERROR_NO_MORE_ENTRIES.
Once you're done sending packets to the filesystem, you should call
FreeDeviceProc() to release the lock to the filesystem. Do not use
the DevProc structure or the message port obtained from it after this
point
INPUTS
name - Name of the object to find filesystem handler
for. The path can be relative or absolute. For
example:
- relative to current dir: "Devs/Monitors"
- relative to current volume: ":Devs/Monitors"
- absolute: "Work:", "S:startup-squence"
dp - Previous result of GetDeviceProc() or NULL
RESULT
A pointer to a DevProc structure containing the information
required to send a command to a filesystem
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
GetDosObjectAttr
DESCRIPTION
Queries DOS object in a way specified in the taglist
INPUTS
type - type of the object, one of DOS_* in dos/dos.h.
object - pointer to the object to modify.
tags - taglist to specify how the dosobject should be
queried. See ADO_* in dos/dostags.h
RESULT
A boolean telling whether the operation was successful or not.
If multiple tags are passed, any single operation failing will
fail the whole call
NOTES
BSTR type variable size strings are queried through struct
DosAttrBuffer. This structure can be used to first query the
size of the data and then fetch it.
INTERNALS
This function was added in dos.library V51.21.
EXAMPLE
/* Example 1: Get DOS_DEVICENODE priority & stacksize */
LONG priority;
ULONG stacksize;
if (GetDosObjectAttrTags(DOS_DEVICENODE, devnode,
ADO_DN_Priority, (IPTR) &priority,
ADO_DN_StackSize, (IPTR) &stacksize,
TAG_DONE))
{
Printf("priority %ld stacksize %lu\n", priority, stacksize);
}
/* Example 2: Get DOS_FSCONTEXT name (BSTR) */
/* First get the required buffer size, including terminating 0. */
struct DosAttrBuffer name = {NULL, 0};
if (GetDosObjectAttrTags(DOS_FSCONTEXT, fscontext,
ADO_DN_Name, (IPTR) &name,
TAG_DONE))
{
/* Allocate buffer for to hold the data. */
UBYTE *buffer = AllocVec(name.dab_Len, MEMF_ANY);
if (buffer)
{
/* Ask to place the data to the buffer. */
name.dab_Ptr = buffer;
if (GetDosObjectAttrTags(DOS_FSCONTEXT, fscontext,
ADO_DN_Name, (IPTR) &name,
TAG_DONE))
{
/* 'buffer' now holds the name of the dosnode */
Printf("name: %s\n", buffer);
}
FreeVec(buffer
SEE ALSO
GetFileSysAttr
DESCRIPTION
Query filesystem for attributes, such as maximum filename length,
or maximum file size
INPUTS
devicename -- name of the filesystem to get attributes from
attr -- attribute to get information about. see FQA_* in
dos/dosextens.h for possible values
storage -- storage to hold the result
storage_size -- size of the storage
RESULT
Success/failure indication. In case of a failure, IoErr() gives
more information about the failure:
ERROR_ACTION_NOT_KNOWN -- the packet is not supported
ERROR_BAD_NUMBER -- the attribute is not known
ERROR_LINE_TOO_LONG -- the result doesn't fit the provided
storage_size
SEE ALSO
GetFileSysTask
DESCRIPTION
Return the default filesystem handler for this process
INPUTS
None
RESULT
The default filesystem handler for this process
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
GetProgramDir
DESCRIPTION
This function will return the shared lock on the directory that
the current process was loaded from. You can use this to help
you find data files which were supplied with your program.
A NULL return is possible, which means that you may be running
from the Resident list.
You should NOT under any circumstance UnLock() this lock
RESULT
A shared lock on the directory the program was started from
HISTORY
27-11-1996 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
17-02-1997 iaint Implemented. Required for locale.
GetProgramName
SYNOPSIS
GetProgramName(buf, len)
LONG GetProgramName(STRPTR, LONG);
DESCRIPTION
Copies the name of the current program from the CLI structure
into the buffer. If the buffer is too small the name is truncated,
and a failure is returned. If the current process doesn't have
a CLI structure, a 0 length string is put into the buffer and a
failure is returned
INPUTS
buf - Buffer for the name.
len - Size of the buffer in bytes
RESULT
!=0 on success, 0 on failure. IoErr() gives additional information
in that case
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
GetPrompt
SYNOPSIS
GetPrompt(buf, len)
LONG GetPrompt(STRPTR, LONG);
DESCRIPTION
Copies the prompt from the CLI structure into the buffer. If the
buffer is too small the name is truncated, and a failure is returned.
If the current process doesn't have a CLI structure, a 0 length string
is put into the buffer and a failure is returned
INPUTS
buf - Buffer for the prompt.
len - Size of the buffer in bytes
RESULT
!=0 on success, 0 on failure. IoErr() gives additional information
in that case
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
GetSegListAttr
DESCRIPTION
Query seglist for attributes, such as the ObjData ptr
INPUTS
seglist -- SegList BPTR
attr -- attribute to get information about
storage -- storage to hold the result
storage_size -- size of the storage
RESULT
Success/failure indication. In case of a failure, IoErr() gives
more information about the failure:
ERROR_ACTION_NOT_KNOWN -- the packet is not supported
ERROR_BAD_NUMBER -- the attribute is not known
ERROR_LINE_TOO_LONG -- the result doesn't fit the provided
storage_size
NOTES
This function is older API endpoint that didn't have the taglist
argument, and thus cannot be used to get segment specific attributes.
New code should use GetSegListAttrTagList().
INTERNALS
This function was added in dos.library V50.75.
SEE ALSO
GetSegListAttrTagList
DESCRIPTION
Query seglist for attributes, such as the ObjData ptr
INPUTS
seglist -- SegList BPTR
attr -- attribute to get information about, see dos/dostags.h
SEGLISTTAG_*
storage -- storage to hold the result
storage_size -- size of the storage
tags -- taglist pointer, when querying segment specific
attribute, a taglist is used be specify the segment
index with:
SEGLISTTAG_DOS_SEGINDEX - specify segment index as in LoadSeg
SEGLISTTAG_ELF_SEGINDEX - specify segment index as in elf
RESULT
Success/failure indication. In case of a failure, IoErr() gives
more information about the failure:
ERROR_ACTION_NOT_KNOWN -- the packet is not supported
ERROR_BAD_NUMBER -- the attribute is not known
ERROR_LINE_TOO_LONG -- the result doesn't fit the provided
storage_size
INTERNALS
This function was added in dos.library V51.52.
SEE ALSO
<dos/dosextens.h><dos/dostags.h>
GetVar
SYNOPSIS
GetVar(name, buffer, size, flags)
LONG GetVar(STRPTR, STRPTR, LONG, LONG);
DESCRIPTION
Gets the value of a local or environment variable, or an alias. It
is advised to only use ASCII strings inside variables/aliases, but
this is not required.
Variable/alias names are case insensitive.
This function stops putting characters into the destination buffer
when a newline character (\n) is met, unless if GVF_BINARY_VAR flag
is specified. The newline character itself is not stored in the
buffer.
This function can be used to access aliases aswell, by specifying
type of LV_ALIAS. GVF_GLOBAL_ONLY must not be specified in this
case, as aliases are always shell local
INPUTS
name - pointer to name of the variable/alias.
buffer - user allocated buffer to store the variable/alias
contents to.
size - length of the user buffer in bytes.
flags - A combination of the type of variable to get (lower
8 bits: LV_VAR or LV_ALIAS) and flags that control the
operation of this function. Currently defined flags are:
GVF_GLOBAL_ONLY - only tries to get a global variable.
GVF_LOCAL_ONLY - only tries to get a local variable.
GVF_BINARY_VAR - do not stop at a newline character.
GVF_DONT_NULL_TERM - no null (\0) termination. Only valid
for GVF_BINARY_VAR
RESULT
The return value is the number of characters put in the buffer, or -1
if the variable/alias is not defined. The newline ('\n') character if
it exists will not be placed in the buffer.
If the variable/alias content would overflow the provided user buffer,
then the number of bytes copied into the buffer will be returned and
the buffer is truncated. The buffer will be null (\0) terminated
unless if GVF_DONT_NULL_TERM is set.
IoErr() will be:
a) ERROR_BAD_NUMBER
if the size of the user buffer is 0.
b) ERROR_OBJECT_NOT_FOUND
if the variable/alias is not defined.
c) the total length of the variable (may be larger than the return
value if the result was truncated
SEE ALSO
Info
SYNOPSIS
Info(lock, parameterBlock)
LONG Info(BPTR, struct InfoData *);
DESCRIPTION
Get information about a volume in the system
INPUTS
lock -- a lock on any file on the volume for which information
should be supplied
parameterBlock -- pointer to an InfoData structure
RESULT
Boolean indicating success or failure. If TRUE (success) the
'parameterBlock' is filled with information on the volume
SEE ALSO
Inhibit
SYNOPSIS
Inhibit(name, onoff)
LONG Inhibit(STRPTR, LONG);
DESCRIPTION
Stop a filesystem from being used
INPUTS
name -- Name of the device to inhibit (including a ':')
onoff -- Specify whether to inhinit (DOSTRUE) or uninhibit (DOSFALSE)
the device
RESULT
A boolean telling whether the action was carried out
NOTES
After uninhibiting a device anything might have happened like the disk
in the drive was removed.
HISTORY
26.03.2000 -- SDuvan implemented
Input
DESCRIPTION
Returns the current input stream or 0 if there is no current
input stream
RESULT
Input stream handle
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
InternalLoadSeg
SYNOPSIS
InternalLoadSeg(fh, table, , stack)
BPTR InternalLoadSeg(BPTR, BPTR, LONG, LONG *);
DESCRIPTION
Loads from fh.
Functionarray is a pointer to an array of functions. See below.
This function really only tries to load the different file
formats aos, elf and aout
INPUTS
fh : Filehandle to load from
table : ignored
functionarray : Array of function to be used fro read, alloc and free
FuncTable[0] -> bytes = 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.
(currently ignored
RESULT
seglist - pointer to loaded Seglist or NULL in case of failure
BUGS
Use of table and stack are not implemented, yet!
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
InternalLoadSeg
SYNOPSIS
InternalLoadSeg(fh, table, , stack)
BPTR InternalLoadSeg(BPTR, BPTR, LONG, LONG *);
DESCRIPTION
Loads executable segment from fh.
Functionarray is a pointer to an array of functions. See below
INPUTS
fh : Filehandle to load from
table : When loading an overlay, otherwise ignored.
functionarray : Array of function to be used fro read, alloc and free
FuncTable[0] -> bytes = 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.
(currently ignored
RESULT
seglist - pointer to loaded Seglist or NULL in case of failure
BUGS
Use of stack are not implemented, yet!
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
InternalUnLoadSeg
SYNOPSIS
InternalUnLoadSeg(seglist, )
LONG InternalUnLoadSeg(BPTR, VOID);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
InternalUnLoadSeg
SYNOPSIS
InternalUnLoadSeg(seglist, )
LONG InternalUnLoadSeg(BPTR, VOID);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
IoErr
DESCRIPTION
Get the dos error code for the current process
RESULT
Error code
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
IsFileSystem
SYNOPSIS
IsFileSystem(devicename)
LONG IsFileSystem(STRPTR);
DESCRIPTION
Query the device whether it is a filesystem
INPUTS
devicename - Name of the device to query
RESULT
TRUE if the device is a filesystem, FALSE otherwise
NOTES
DF0:, HD0:, ... are filesystems.
CON:, PIPE:, AUX:, ... are not
In AmigaOS if devicename contains no ":" then result
is always TRUE. Also volume and assign names return
TRUE.
IsInteractive
SYNOPSIS
IsInteractive(file)
LONG IsInteractive(BPTR);
DESCRIPTION
Check if file is bound to an interactive device such as a console
or shell window
INPUTS
file - filehandle
RESULT
!= 0 if the file is interactive, 0 if it is not
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
LoadSeg
SYNOPSIS
LoadSeg(name, table, fh)
BPTR LoadSeg(STRPTR, BPTR, BPTR);
DESCRIPTION
Loads an executable file into memory. Each hunk of the loadfile
is loaded into his own memory section and a handle on all of them
is returned. The segments can be freed with UnLoadSeg().
When loading MorphOS native PowerPC applications a seglist is also
returned. The first segment holds a shim that when executed as m68k
code transfers execution to the PowerPC native code in the 2nd
segment
INPUTS
name - NUL terminated name of the file
RESULT
Handle to the loaded executable or 0 if the load failed.
IoErr() gives additional information in that case
NOTES
This function is built on top of InternalLoadSeg()
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
LoadSegNoreq
SYNOPSIS
LoadSegNoreq(name)
BPTR LoadSegNoreq(STRPTR);
DESCRIPTION
Like LoadSeg, except that it inhibits requesters.
This is dosPrivate2
INPUTS
name - NUL terminated name of the file
RESULT
Handle to the loaded executable or 0 if the load failed.
IoErr() gives additional information in that case
SEE ALSO
Lock
SYNOPSIS
Lock(name, accessMode)
BPTR Lock(STRPTR, LONG);
DESCRIPTION
Gets a lock on a file or directory. There may be more than one
shared lock on a file but only one if it is an exclusive one.
Locked files or directories may not be deleted
INPUTS
name - NUL terminated name of the file or directory.
accessMode - One of SHARED_LOCK
EXCLUSIVE_LOCK
RESULT
Handle to the file or directory or 0 if the object couldn't be locked.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
LockDosList
SYNOPSIS
LockDosList(flags)
struct DosList * LockDosList(ULONG);
DESCRIPTION
Waits until the desired dos lists are free then gets a lock on them.
A handle is returned that can be used for FindDosEntry().
Calls to this function nest, i.e. you must call UnLockDosList()
as often as you called LockDosList(). Always lock all lists
at once - do not try to get a lock on one of them then on another
INPUTS
flags - what lists to lock
RESULT
Handle to the dos list. This is not a direct pointer
to the first list element but to a pseudo element instead
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
LockRecord
SYNOPSIS
LockRecord(fh, offset, length, mode, timeout)
LONG LockRecord(BPTR, ULONG, ULONG, ULONG, ULONG);
DESCRIPTION
Lock a portion of a file for exclusive access. A timeout may be specified
which is the maximum amount of time to wait for the record to be available
INPUTS
fh -- file handle for the file to lock a record of
offset -- starting position of the lock
length -- length of the record in bytes
mode -- lock type
timeout -- timeout interval measured in ticks (may be 0
RESULT
Success/failure indicator
NOTES
Record locks are cooperative, meaning that they only affect other calls
to LockRecord().
SEE ALSO
LockRecord64
DESCRIPTION
Lock a portion of a file for exclusive access. A timeout may be specified
which is the maximum amount of time to wait for the record to be available
INPUTS
fh -- file handle for the file to lock a record of
offset -- starting position of the lock
length -- length of the record in bytes
mode -- lock type
timeout -- timeout interval measured in ticks (may be 0
RESULT
Success/failure indicator
NOTES
Record locks are cooperative, meaning that they only affect other calls
to LockRecord64().
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
LockRecords
SYNOPSIS
LockRecords(recArray, timeout)
LONG LockRecords(struct RecordLock *, ULONG);
DESCRIPTION
Lock several records at the same time. The timeout specified is applied
to each lock to attempt. The array of RecordLock:s is terminated with
an entry where rec_FH is equal to NULL
INPUTS
recArray -- array of records to lock
timeout -- maximum number of ticks to wait for a lock to be ready
RESULT
Success/failure indication. In case of a success, all the record locks
are locked. In case of failure, no record locks are locked
NOTES
A set of records should always be locked in the same order so as to
reduce possiblities of deadlock.
SEE ALSO
LockRecords64
DESCRIPTION
Lock several records at the same time. The timeout specified is applied
to each lock to attempt. The array of RecordLock:s is terminated with
an entry where rec_FH is equal to NULL
INPUTS
recArray -- array of records to lock
timeout -- maximum number of ticks to wait for a lock to be ready
RESULT
Success/failure indication. In case of a success, all the record locks
are locked. In case of failure, no record locks are locked
NOTES
A set of records should always be locked in the same order so as to
reduce possiblities of deadlock.
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
MakeDosEntry
SYNOPSIS
MakeDosEntry(, type)
struct DosList * MakeDosEntry(CONST, LONG);
DESCRIPTION
Create an entry for the dos list. Depending on the type this may
be a device a volume or an assign node
INPUTS
name - pointer to name
type - type of list entry to create
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
MakeLink
SYNOPSIS
MakeLink(name, dest, soft)
LONG MakeLink(STRPTR, APTR, LONG);
DESCRIPTION
MakeLink() will create a link between two files or directories.
A link is a filesystem object that refers to another file.
A soft link refers to another file by name, and is resolved by
the filesystem and the caller. Soft links are not restricted to
the same volume. The |dest| argument is a NUL terminated pathname
to the pre-existing object. Soft links can be used on directories.
A hard link refers to another file by the location on a disk, and
is resolved by the filesystem. Hard links are restricted to files
on the same volume. The |dest| argument is a lock on another file
INPUTS
name - The name of the link to create
dest - If 'soft' is TRUE this must be a filename, if it is FALSE a BPTR
pointing to the file to be hard-linked must be provided
soft - TRUE, if a soft-link is to be created, FALSE for an hard-link
RESULT
boolean - DOSTRUE or DOSFALSE. On error, IoErr() will contain more
information
BUGS
Soft links were not working in the ROM filesystem before version
37.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
MatchEnd
SYNOPSIS
MatchEnd(AP)
void MatchEnd(struct AnchorPath *);
DESCRIPTION
Free the memory that was allocated by calls to MatchFirst() and
MatchNext
INPUTS
AP - pointer to Anchor Path structure which had been passed to
MatchFirst() before
RESULT
Allocated memory is returned and filelocks are freed
HISTORY
29-04-97 bergers, initial revision
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
MatchFirst
SYNOPSIS
MatchFirst(pat, AP)
LONG MatchFirst(STRPTR, struct AnchorPath *);
DESCRIPTION
Searches for the first file or directory that matches a given pattern.
MatchFirst() initializes the AnchorPath structure for you but you
must initialize the following fields: ap_Flags, ap_Strlen, ap_BreakBits
and ap_FoundBreak. The first call to MatchFirst() also passes you
the first matching file which you can examine in ap_Info and the directory
the files is in in ap_Current->an_Lock. After the first call to
MatchFirst() call MatchNext().
The search begins whereever the current directory is set to. See
CurrentDir(); For more info on patterns see ParsePattern
INPUTS
pat - pattern to search for
AP - pointer to (initilized) AnchorPath structure
RESULT
0 = success
other = DOS error code
HISTORY
09-11-2000 stegerg, rewritten from scratch.
29-04-97 bergers, initial revision
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
MatchNext
SYNOPSIS
MatchNext(AP)
LONG MatchNext(struct AnchorPath *);
DESCRIPTION
Find next file or directory that matches a given pattern.
See <dos/dosasl.h> for more docs and how to control MatchNext
INPUTS
AP - pointer to Anchor Path structure which had been passed to
MatchFirst() before
HISTORY
09-11-2000 stegerg, rewritten from scratch.
29-04-97 bergers, initial revision
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
MatchPattern
SYNOPSIS
MatchPattern(pat, str)
LONG MatchPattern(STRPTR, STRPTR);
DESCRIPTION
Check if a string matches a pattern. The pattern must be a pattern as
output by ParsePattern(). Note that this routine is case sensitive
INPUTS
pat -- Pattern string (as returned by ParsePattern())
str -- The string to match against the pattern 'pat
RESULT
Boolean telling whether the string matched the pattern
SEE ALSO
MatchPatternNoCase
SYNOPSIS
MatchPatternNoCase(pat, str)
LONG MatchPatternNoCase(STRPTR, STRPTR);
DESCRIPTION
Similar to MatchPattern(), only case insensitive (see there for
more information). For use with ParsePatternNoCase
INPUTS
pat -- Pattern as returned by ParsePatternNoCase()
str -- String to match against the pattern 'pat
RESULT
Boolean telling whether the match was successful or not
SEE ALSO
MaxCli
DESCRIPTION
Returns the highest Cli number currently in use. Since processes
may be added and removed at any time the returned value may already
be wrong
RESULT
Maximum Cli number (_not_ the number of Clis
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
NameFromFH
SYNOPSIS
NameFromFH(fh, buffer, len)
LONG NameFromFH(BPTR, STRPTR, LONG);
DESCRIPTION
Get the full path name associated with file-handle into a
user supplied buffer
INPUTS
fh - File-handle to file or directory.
buffer - Buffer to fill. Contains a NUL terminated string if
all went well.
length - Size of the buffer in bytes
RESULT
!=0 if all went well, 0 in case of an error. IoErr() will
give additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
NameFromLock
SYNOPSIS
NameFromLock(lock, buffer, length)
LONG NameFromLock(BPTR, STRPTR, LONG);
DESCRIPTION
Get the full path name associated with a lock to a file or
directory into a user supplied buffer
INPUTS
lock - Lock to file or directory.
buffer - Buffer to fill. Contains a NUL terminated string if
all went well.
length - Size of the buffer in bytes
RESULT
!=0 if all went well, 0 in case of an error. IoErr() will
give additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
NewLoadSeg
SYNOPSIS
NewLoadSeg(file, tags)
BPTR NewLoadSeg(STRPTR, struct TagItem *);
DESCRIPTION
Loads an executable file into memory via LoadSeg() and takes
additional actions based upon the supplied tags
INPUTS
file - NULL terminated name of the file
tags - pointer to the tagitems
RESULT
Handle to the loaded executable or 0 if the load failed.
IoErr() gives additional information in that case
BUGS
As there are no tags currently defined all this function does is
call LoadSeg()
SEE ALSO
NewReadLink
DESCRIPTION
Read the filename referred to by the soft-linked object contained
in |path| (relative to the lock |lock|) into the buffer |buffer|.
The variable |path| should contain the name of the object that
caused the original OBJECT_IS_SOFT_LINK error. Unlike original
ReadLink, NewReadLink works on hardlinks aswell as softlinks
INPUTS
port - The handler to send the request to.
lock - Object that |path| is relative to.
path - Name of the object that caused the error.
buffer - Buffer to fill with resolved filename.
buffer_size - Length of the buffer
RESULT
> 0 success, actual length of the returned string.
0 failure, probably ERROR_NOT_IMPLEMENTED.
-1 failure, see IoErr() for more information.
-2 failure, not enough space in the buffer
BUGS
Before dos.library 51.41 the filesystems not implementing this
functionality would result in IoErr() not being set. This was
fixed in dos 51.41 which now consistently sets IoErr() to
ERROR_NOT_IMPLEMENTED in this case.
SEE ALSO
NextDosEntry
SYNOPSIS
NextDosEntry(dlist, flags)
struct DosList * NextDosEntry(struct DosList *, ULONG);
DESCRIPTION
Looks for the next dos list entry with the right type. The list
must be locked for this
INPUTS
dlist - the value given by LockDosList() or the last call to
FindDosEntry().
flags - the same flags as given to LockDosList() or a subset
of them
RESULT
Pointer to dos list entry found or NULL if the are no more entries
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Open
SYNOPSIS
Open(, accessMode)
BPTR Open(CONST, LONG);
DESCRIPTION
Opens a file for read and/or write depending on the accessmode given
INPUTS
name - zero terminated name of the file.
accessMode - One of MODE_OLDFILE - open existing file, shared lock
MODE_NEWFILE - delete old, create new file,
exclusive lock
MODE_READWRITE - open new file if it doesn't exist,
shared lock
RESULT
Handle to the file or 0 if the file couldn't be opened.
IoErr() gives additional information in that case
NOTES
The open accessMode does not map directly to the POSIX open() flags.
Here's how to implement similar functionality in regards of O_CREAT,
O_EXCL, O_EXLOCK and O_TRUNC:
1. If both O_CREAT and O_EXCL are set first attempt to Lock() the name
to see if the file already exists. If the file exists, fail the
operation.
2. If both O_CREAT and O_EXLOCK are set use MODE_NEWFILE to create a new
file with exclusive access. Otherwise if O_CREAT is set use
MODE_READWRITE, else MODE_OLDFILE.
3. If O_TRUNC is set, after successful open call SetFileSize(handke, 0,
OFFSET_BEGINNING) to truncate the file to 0 bytes.
Note that Open() will always follow softlinks, no matter what.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
OpenFromLock
SYNOPSIS
OpenFromLock(lock)
BPTR OpenFromLock(BPTR);
DESCRIPTION
Convert a lock into a filehandle. If all went well the lock
will be gone. In case of an error it must still be freed
INPUTS
lock - Lock to convert
RESULT
New filehandle or 0 in case of an error. IoErr() will give
additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Output
DESCRIPTION
Returns the current output stream or 0 if there is no current
output stream
RESULT
Output stream handle
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ParentDir
SYNOPSIS
ParentDir(lock)
BPTR ParentDir(BPTR);
DESCRIPTION
Returns a lock to the parent directory of the supplied lock
INPUTS
lock - Lock to get parent directory of
RESULT
Returns a lock to the parent directory or NULL, in which case the
supplied lock has no parent directory (because it is the root
directory) or an error occured. IoErr() returns 0 in the former case
and a different value on error
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ParentOfFH
SYNOPSIS
ParentOfFH(fh)
BPTR ParentOfFH(BPTR);
DESCRIPTION
Lock the directory a file is located in
INPUTS
fh - Filehandle of which you want to obtain the parent
RESULT
lock - Lock on the parent directory of the filehandle or
NULL for failure
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
ParsePattern
SYNOPSIS
ParsePattern(Source, Dest, DestLength)
LONG ParsePattern(STRPTR, STRPTR, LONG);
DESCRIPTION
Takes a pattern containing wildcards and transforms it into some
intermediate representation for use with the MatchPattern() function.
The intermediate representation is longer but generally a buffer
size of 2*(strlen(Source)+1) is enough. Nevertheless you should check
the returncode to be sure that everything went fine
INPUTS
Source - Pattern describing the kind of strings that match.
Possible tokens are:
#x - The following character or item is repeaded 0 or
more times.
? - Item matching a single non-NUL character.
a|b|c - Matches one of multiple strings.
~x - This item matches if the item x doesn't match.
(a) - Parens
[a-z] - Matches a single character out of the set.
[~a-z] - Matches a single non-NUL character not in the set.
'c - Escapes the following character.
% - Matches 0 characters always (useful in "(foo|bar|%)").
* - Same as #?, but optional.
Dest - Buffer for the destination.
DestLength - Size of the buffer
RESULT
1 - There are wildcards in the pattern (it might match more than
one string).
0 - No wildcards in it, all went fine.
-1 - An error happened. IoErr() gives additional information in
that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ParsePatternNoCase
SYNOPSIS
ParsePatternNoCase(Source, Dest, DestLength)
LONG ParsePatternNoCase(STRPTR, STRPTR, LONG);
DESCRIPTION
Similar to ParsePattern(), only case insensitive (see there
for more information). For use with MatchPatternNoCase
SEE ALSO
PathPart
SYNOPSIS
PathPart(path)
STRPTR PathPart(STRPTR);
DESCRIPTION
Returns a pointer to the character after the last
directory in path (see examples
INPUTS
path - Search this path
RESULT
A pointer to a character in 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
PosixDateStamp
DESCRIPTION
Return current system time in UTC POSIX datestamp. The epoch of the
POSIX datestamps is 1970-01-01 00:00:00 UTC
INPUTS
pds - struct PosixDateStamp to fill
RESULT
Pointer to pds. This function cannot fail
BUGS
Currently the system cannot return dates past 2114-02-07. This
likely won't be problem we need to solve as we've all deceased
long before that.
INTERNALS
This function was added in dos.library V51.66.
Currently the resolution of the returned time is in microseconds
(multiple of 1000 nanoseconds). This may improve later.
EXAMPLE
struct PosixDateStamp pds;
PosixDateStamp(&pds
SEE ALSO
PosixDateStampToDateStamp
DESCRIPTION
Convert UTC POSIX datestamp to local time. The epoch of the POSIX
datestamps is 1970-01-01 00:00:00 UTC. The conversion uses the
currently set system time zone
INPUTS
pds - struct PosixDateStamp to convert from.
ds - struct DateStamp to fill with local time
RESULT
!= 0 if all went well, 0 else. The function will fail if input is
invalid, or if the output format cannot be used to represent the
time
NOTES
The conversion to local time is performed using the current
system-wide timezone setting.
Since the epoch of struct DateStamp dates is 1978-01-01 and that
dates before this cannot be presented, it means that dates earlier
than about 1978-01-01 (varying a bit depending on your local
timezone) can't be converted. The function will return FALSE if the
result would be invalid. It is up to the caller to decide how to
handle such situation.
Since struct DateStamp ds_Ticks is in 1/50th second units, the
input timestamp nanoseconds will be rounded down to nearest
1/50th second.
INTERNALS
This function was added in dos.library V51.66.
EXAMPLE
const struct PosixDateStamp pds = {1756930434LL, 911231112};
struct DateStamp ds;
if (PosixDateStampToDateStamp(&pds, &ds
SEE ALSO
PrintFault
SYNOPSIS
PrintFault(code, header)
LONG PrintFault(LONG, STRPTR);
DESCRIPTION
Prints the header and the text associated with the error code to
the console (buffered), then sets the value returned by IoErr() to
the error code given
INPUTS
code - Error code.
header - Text to print before the error message. This may be NULL
in which case only the error message is printed
RESULT
!=0 if all went well. 0 on failure
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
PutStr
SYNOPSIS
PutStr(string)
LONG PutStr(STRPTR);
DESCRIPTION
Writes an unformatted string to the default output. No newline character
is appendded to the output
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
QueryCLIDataTagList
DESCRIPTION
Returns information about specified CLIs in use
INPUTS
tags - Taglist to alter the operation. Current tags:
CLIDATATAG_CLINumber - Only return data matching the specified
CLI number. Returns either 0 or 1 entries.
CLIDATATAG_CommandName - Only return data matching the specified
command. This matches cli_CommandName, and
can return 0 or multiple entries.
CLIDATATAG_Sorted - If ti_Data is specified as non-zero, the
resulting array is sorted by CLI number
RESULT
Pointer to struct CLIData or NULL if error occurred.
If non-NULL pointer is released cd_NumCLIs indicates the number of
entries in the cd_CLI array, which can be 0.
Each entry in the cd_CLI array is a pointer to struct CLIDataItem,
containing information about the CLI, including the command being
executed currently (if any). The data is effectively a snapshot at the
time the function was called. It will become outdated shortly
afterwards.
Once you're done with the data it must be released with call to
FreeCLIData
INTERNALS
This function was added in dos.library V51.51.
EXAMPLE
struct CLIData *cd;
cd = QueryCLIDataTags(CLIDATATAG_Sorted, TRUE, TAG_DONE);
if (cd)
{
ULONG i;
for (i = 0; < cd->cd_NumCLIs; i++)
{
Printf("#%ld: %s\n",
cd->cd_CLI[i]->cdi_CLINum,
cd->cd_CLI[i]->cdi_Command);
}
FreeCLIData(cd
SEE ALSO
Read
SYNOPSIS
Read(file, buffer, length)
LONG Read(BPTR, APTR, LONG);
DESCRIPTION
Read some data from a given file. The request is directly
given to the filesystem - no buffering is involved. For
small amounts of data it's probably better to use the
buffered I/O routines
INPUTS
file - filehandle
buffer - pointer to buffer for the data
length - number of bytes to read. The filesystem is
advised to try to fulfill the request as good
as possible
RESULT
The number of bytes actually read, 0 if the end of the
file was reached, -1 if an error happened. IoErr() will
give additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ReadArgs
SYNOPSIS
ReadArgs(template, array, rdargs)
struct RDArgs * ReadArgs(STRPTR, IPTR *, struct RDArgs *);
DESCRIPTION
Parses the commandline, a given string or Input() and fills
an argument array according to the options template given.
The array must be initialized to the wanted defaults before
each call to ReadArgs(). If the rdargs argument is NULL
ReadArgs() tries to parse the commandline and continues
on the input channel if it just consists of a single '?',
prompting the user for input
INPUTS
template - Template string. The template string is given as
a number of options separated by ',' and modified
by '/' modifiers, e.g. 'NAME,WIDTH/N,HEIGHT/N'
means get a name string and two numbers (width and
height). The possible modifiers are:
/S Option is a switch. It may be either set or
left out.
/T Option is a boolean value. Requires an argument
which may be "ON", "YES" (setting the respective
argument to 1), "OFF" or "NO" (setting the
respective argument to 0).
/N Option is a number. Strings are not allowed.
If the option is optional, a pointer to the
actual number is returned. This is how you know
if it was really given.
/A Argument is required. If it is left out ReadArgs()
fails.
/K The keyword must be given when filling the option.
Normally it's skipped.
/M Multiple strings. The result is returned as a string
pointer array terminated with NULL. /M eats all strings
that don't fit into any other option. If there are
unfilled /A arguments after parsing they steal strings
from /M. This makes it possible to e.g. write a COPY
template like 'FROM/A/M,TO/A'. There may be only one
/M option in a template.
/F Eats the rest of the line even if there are option
keywords in it.
array - Array to be filled with the result values. The array must
be intialized to the default values before calling
ReadArgs().
rdargs - An optional RDArgs structure determinating the type of
input to process
RESULT
A handle for the memory allocated by ReadArgs(). Must be freed
with FreeArgs() later
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
EXAMPLE
See below
SEE ALSO
ReadItem
SYNOPSIS
ReadItem(buffer, maxchars, input)
LONG ReadItem(STRPTR, LONG, struct CSource *);
DESCRIPTION
Reads a "word" from CSource. The word can be unquoted or
"double quoted" (with **, *", *E and *N special handling). The
words are delimited by either whitespace or a '=' or an EOF.
If CSource is NULL then standard input is used to fetch the
input
INPUTS
buffer - buffer to store the word in.
maxchars - size of the buffer.
input - CSource input or NULL (use standard input
RESULT
One of ITEM_UNQUOTED - normal unquotes word
ITEM_QUOTED - doublequoted string
ITEM_NOTHING - EOF reached, nothing returned.
ITEM_EQUAL - '=' was met, nothing returned.
ITEM_ERROR - an error occured
BUGS
There are numerous undocumented side-effects resulting from the
use of this function. While ReadItem() was originally documented
to always always unread the last thing read (UnGetC(fh,-1)), in
reality this might not always be the case.
SEE ALSO
ReadLink
SYNOPSIS
ReadLink(port, lock, path, buffer, size)
LONG ReadLink(struct MsgPort *, BPTR, STRPTR, STRPTR, ULONG);
DESCRIPTION
Read the filename referred to by the soft-linked object contained
in |path| (relative to the lock |lock|) into the buffer |buffer|.
The variable |path| should contain the name of the object that
caused the original OBJECT_IS_SOFT_LINK error
INPUTS
port - The handler to send the request to.
lock - Object that |path| is relative to.
path - Name of the object that caused the error.
buffer - Buffer to fill with resolved filename.
size - Length of the buffer
RESULT
>= 0 success, actual length of the returned string.
-1 failure, see IoErr() for more information.
-2 failure, not enough space in the buffer
BUGS
Old autodocs and GuruBook were wrong about the return value.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
Relabel
SYNOPSIS
Relabel(drive, newname)
LONG Relabel(STRPTR, STRPTR);
DESCRIPTION
Change names of a volume
INPUTS
drive -- The name of the device to rename (including the ':').
newname -- The new name for the device (without the
RESULT
A boolean telling whether the name change was successful or not
HISTORY
28.04.2000 SDuvan implemented
ReleaseCLINumber
DESCRIPTION
Releases the given CLI number of be reused
INPUTS
clinum - CLI number to release
RESULT
The CLI slot is released to the pool of available CLI numbers
NOTES
There is generally no reason for user code to call this function.
INTERNALS
This function was added in dos.library V51.51.
RemAssignList
SYNOPSIS
RemAssignList(name, lock)
LONG RemAssignList(STRPTR, BPTR);
DESCRIPTION
Remove an entry from a multi-dir assign. The entry removed will be
the first one that the SameLock() function called on the 'lock'
parameter returns that they belong to the same object.
The entry for this lock will be remove from the lock, and the
lock for the entry in the list will be unlocked
INPUTS
name - Name of the device to remove lock from. This should
not contain the trailing ':'.
lock - Lock on the object to remove from the list
RESULT
success - Have we actually succeeded
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
RemDosEntry
SYNOPSIS
RemDosEntry(dlist)
LONG RemDosEntry(struct DosList *);
DESCRIPTION
Removes a given dos list entry from the dos list. Automatically
locks the list for writing
INPUTS
dlist - pointer to dos list entry
RESULT
!=0 if all went well, 0 otherwise
NOTES
Since anybody who wants to use a device or volume node in the
dos list has to lock the list, filesystems may be called with
the dos list locked. So if you want to add a dos list entry
out of a filesystem don't just wait on the lock but serve all
incoming requests until the dos list is free instead.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
RemSegment
SYNOPSIS
RemSegment(seg)
LONG RemSegment(struct Segment *);
DESCRIPTION
Remove the segment seg from the DOS resident command list.
The segment to be removed should be in the list, and should
have a usercount of 0. System or internal segment cannot be
removed (although they can be replaced).
New: the same seglist can now appear several times in the
list with different names. If this occurs, the Segment is
freed but the seglist is not unloaded
INPUTS
seg - Segment to remove
RESULT
!= 0 Segment was removed
== 0 Segment was not removed (not in list, or not free
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
Rename
SYNOPSIS
Rename(oldName, newName)
LONG Rename(STRPTR, STRPTR);
DESCRIPTION
Renames a given file. The old name and the new name must point to the
same volume
INPUTS
oldName - Name of the file to rename
newName - New name of the file to rename
RESULT
boolean - DOSTRUE or DOSFALSE. IoErr() provides additional information
on DOSFALSE
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
ReplyPkt
SYNOPSIS
ReplyPkt(dp, res, res)
void ReplyPkt(struct DosPacket *, LONG, LONG);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
RunCommand
SYNOPSIS
RunCommand(segList, stacksize, argptr, argsize)
LONG RunCommand(BPTR, ULONG, STRPTR, ULONG);
DESCRIPTION
RunCommand() will run the command loaded in the |segList| with the
arguments specified with a new m68k stack of |stacksize| bytes. The
stack size has no effect on stack size of PowerPC native executables.
The return code of the command run will be returned.
This call will not return until the command has completed
INPUTS
segList - segment of program to run.
stacksize - size of the m68k stack to use.
argptr - pointer to NULL-terminated arguments.
argsize - size of the arguments string
RESULT
The return code from the program. See also IoErr
NOTES
Programs expect the arugment string to end with a newline ('\n')
character (ReadArgs() requires it to work properly).
BUGS
stacksize only affects m68k stack size. PowerPC native applications
are expected to manage their own stack size and not require caller
to have knowledge of it.
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SameDevice
SYNOPSIS
SameDevice(lock, lock)
LONG SameDevice(BPTR, BPTR);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SameLock
SYNOPSIS
SameLock(lock, lock)
LONG SameLock(BPTR, BPTR);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Seek
SYNOPSIS
Seek(file, position, mode)
LONG Seek(BPTR, LONG, LONG);
DESCRIPTION
Changes the current read/write position in a file and/or
reads the current position, e.g to get the current position
do a Seek(file,0,OFFSET_CURRENT).
This function may fail (obviously) on certain devices such
as pipes or console handlers
INPUTS
file - filehandle
position - relative offset in bytes (positive, negative or 0).
mode - Where to count from. Either OFFSET_BEGINNING,
OFFSET_CURRENT or OFFSET_END
RESULT
Absolute position in bytes before the Seek(), -1 if an error
happened. IoErr() will give additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
Seek64
DESCRIPTION
Changes the current read/write position in a file and/or
reads the current position, e.g to get the current position
do a Seek64(file,0,OFFSET_CURRENT).
This function may fail (obviously) on certain devices such
as pipes or console handlers
INPUTS
file - filehandle
position - relative offset in bytes (positive, negative or 0).
mode - Where to count from. Either OFFSET_BEGINNING,
OFFSET_CURRENT or OFFSET_END
RESULT
Absolute position in bytes before the Seek64(), -1 if an error
happened. IoErr() will give additional information in that case
NOTES
This function also works on older volumes that do not support
large files.
The return value of this function differs from POSIX lseek() in
that it returns the *previous* position not the resulting one.
INTERNALS
This function was added in dos.library V50.65.
SelectInput
SYNOPSIS
SelectInput(fh)
BPTR SelectInput(BPTR);
DESCRIPTION
Sets the current input stream returned by Input() to a new
value. Returns the old input stream
INPUTS
fh - New input stream
RESULT
Old input stream handle
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SelectOutput
SYNOPSIS
SelectOutput(fh)
BPTR SelectOutput(BPTR);
DESCRIPTION
Sets the current output stream returned by Output() to a new
value. Returns the old output stream
INPUTS
fh - New output stream
RESULT
Old output stream handle
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SendPkt
SYNOPSIS
SendPkt(dp, port, replyport)
void SendPkt(struct DosPacket *, struct MsgPort *, struct MsgPort *);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetArgStr
SYNOPSIS
SetArgStr(string)
STRPTR SetArgStr(STRPTR);
DESCRIPTION
Sets the arguments to the current process. The arguments must be
reset to the original value before process exit
INPUTS
string - The new argument string. (A C string
RESULT
The address of the previous argument string. May be NULL
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SetComment
SYNOPSIS
SetComment(name, comment)
LONG SetComment(STRPTR, STRPTR);
DESCRIPTION
Change the comment on a file or directory.
The comment may be any NUL terminated string. The supported
size varies from filesystem to filesystem
INPUTS
name - name of the file
comment - new comment for the file or NULL
RESULT
!=0 if all went well, 0 else. IoErr() gives additional
information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetConsoleTask
SYNOPSIS
SetConsoleTask(handler)
struct MsgPort * SetConsoleTask(struct MsgPort *);
DESCRIPTION
Set the console handler for the current process, and return the
old handler
INPUTS
handler - The new console handler for the process
RESULT
The address of the old handler
NOTES
The use of Task in the name is because historically filesystem
handlers were tasks (instead of Devices).
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SetCurrentDirName
SYNOPSIS
SetCurrentDirName(name)
LONG SetCurrentDirName(STRPTR);
DESCRIPTION
Sets the name of the current directory in the CLI structure.
If the name doesn't fit the old name is kept and a failure
returned. If the current process doesn't have a CLI structure
this function does nothing
INPUTS
name - Name for the current directory
RESULT
!=0 on success, 0 on failure
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SetDosObjectAttr
DESCRIPTION
Modifies DOS object in a way specified in the taglist
INPUTS
type - type of the object, one of DOS_* in dos/dos.h.
object - pointer to the object to modify.
tags - taglist to specify how the dosobject should be
modified. See ADO_* in dos/dostags.h
RESULT
A boolean telling whether the operation was successful or not
NOTES
BSTR type arguments are copied and need to be present after a
successful call.
INTERNALS
This function was added in dos.library V51.21.
EXAMPLE
/* Set devicenode startup BSTR and priority */
UBYTE startup[] = "\x08" "bstrtest";
if (GetDosObjectAttrTags(DOS_DEVICENODE, devnode,
ADO_DN_Startup, (IPTR) startup,
ADO_DN_Priority, 5,
TAG_DONE))
{
/* Success
SEE ALSO
SetFileDate
SYNOPSIS
SetFileDate(name, date)
LONG SetFileDate(STRPTR, struct DateStamp *);
DESCRIPTION
Change the modification time of a file or directory
INPUTS
name - name of the file
date - new file time
RESULT
!= 0 if all went well, 0 else. IoErr() gives additional
information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetFilePosixDateTagList
DESCRIPTION
Change the modification time of a file or directory
INPUTS
name - name of the object.
date - new modification time, relative to 1970-01-01 00:00:00 UTC.
tags - taglist, no tags are defined currently
RESULT
!= 0 if all went well, 0 else. IoErr() gives additional
information in that case
NOTES
Unlike with SetFileDate() The date is in UTC rather then local time.
This allows specifying exact date and time regardless of system
timezone or daylight saving status.
Not all volumes store dates in UTC internally. In this case the
date set is transparently converted to the format expected by the
volume. Note with such volumes changes in system timezone will
result in discrepency on the file modification times.
Not all volumes store the object time with nanosecond precision,
and the speciified pds_NSec will then get rounded down accordingly.
INTERNALS
This function was added in dos.library V51.66.
EXAMPLE
const struct PosixDateStamp pds = {1756930434LL, 911231112};
if (SetFilePosixDateTagList("RAM:T", &pdf, NULL
SEE ALSO
SetFileSize
SYNOPSIS
SetFileSize(file, offset, mode)
LONG SetFileSize(BPTR, LONG, LONG);
DESCRIPTION
Change the size of a file
INPUTS
file - filehandle
offset - relative size
mode - OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END
RESULT
New size of the file or -1 in case of an error.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetFileSize64
DESCRIPTION
Change the size of a file
INPUTS
file - filehandle
offset - relative size
mode - OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END
RESULT
New size of the file or -1 in case of an error.
IoErr() gives additional information in that case
NOTES
This function also works on older volumes that do not support large
files. However, with such older volumes out of range size values
result in error return with IoErr() of ERROR_NOT_IMPLEMENTED.
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
SetFileSysTask
SYNOPSIS
SetFileSysTask(task)
struct MsgPort * SetFileSysTask(struct MsgPort *);
DESCRIPTION
Set the default filesystem handler for the current process,
the old filesystem handler will be returned
INPUTS
task - The new filesystem handler
RESULT
The old filesystem handler
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SetIoErr
SYNOPSIS
SetIoErr(result)
LONG SetIoErr(LONG);
DESCRIPTION
Sets to dos error code for the current process
INPUTS
result -- new error code
RESULT
Old error code
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetMode
SYNOPSIS
SetMode(fh, mode)
LONG SetMode(BPTR, LONG);
DESCRIPTION
SetMode() can be used to change a console handler between
RAW: mode and CON: mode
INPUTS
fh - The filehandle describing the console.
mode - The new mode of the console:
1 - RAW: mode
0 - CON: mode
RESULT
This function will return whether it succeeded:
== DOSTRUE console mode changed
!= DOSTRUE console mode change failed
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetOwner
SYNOPSIS
SetOwner(name, owner)
LONG SetOwner(STRPTR, ULONG);
INPUTS
name -- name of the file
owner_info -- (UID << 16) + GID
RESULT
!= 0 if all went well, 0 else. IoErr() gives additional
information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetProgramDir
SYNOPSIS
SetProgramDir(lock)
BPTR SetProgramDir(BPTR);
DESCRIPTION
This function will set a shared lock on the directory that the
current program was loaded from. This can be accessed through
the path PROGDIR:. The use of this path is to allow the program
to easily access files which are supplied with the program
INPUTS
lock - The lock to set as the new program directory. NULL
is a valid value
RESULT
This function will return the old program directory lock
NOTES
This function will not duplicate the lock, so you should not
free the lock.
HISTORY
27-11-1996 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
17-02-1997 iaint Implemented. Need it for locale.
SEE ALSO
SetProgramName
SYNOPSIS
SetProgramName(name)
LONG SetProgramName(STRPTR);
DESCRIPTION
Sets the name for the current program in the CLI structure. If the
name doesn't fit the old name is kept and a failure is returned.
If the current process doesn't have a CLI structure this function
does nothing
INPUTS
name -- Name for the current program
RESULT
!= 0 on success, 0 on failure
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SetPrompt
SYNOPSIS
SetPrompt(name)
LONG SetPrompt(STRPTR);
DESCRIPTION
Sets the prompt in the current CLI structure. If the name doesn't
fit the old name is kept and a failure is returned. If the current
process doesn't have a CLI structure this function does nothing
INPUTS
name - The prompt to be set
RESULT
!=0 on success, 0 on failure
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
SetProtection
SYNOPSIS
SetProtection(name, protect)
LONG SetProtection(STRPTR, ULONG);
INPUTS
name - name of the file
protect - new protection bits
RESULT
!= 0 if all went well, 0 else. IoErr() gives additional
information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetVBuf
SYNOPSIS
SetVBuf(fh, buff, type, size)
LONG SetVBuf(BPTR, STRPTR, LONG, LONG);
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SetVar
SYNOPSIS
SetVar(, , size, flags)
LONG SetVar(CONST, CONST, LONG, LONG);
DESCRIPTION
This function sets a local or global environmental variable, or an
shell alias. It is advised to only use ASCII strings inside
variables/aliases, but this is not required.
Variable/alias names are case insensitive.
SetVar() for an already existing variable/alias changes its value
to buffer content. The 'buffer' pointer can be NULL, in which case
the variable/alias is deleted.
size of -1 means that the buffer is null (\0) terminater string, and
the actual size is calculated by SetVar().
If neither GVF_LOCAL_ONLY or GVF_GLOBAL_ONLY are set the default
is to set a local variable
INPUTS
name - the name of the variable/alias to set/delete.
buffer - pointer to the data to set.
size - the size of the data in the buffer.
flags - A combination of the type of variable to get (lower
8 bits: LV_VAR or LV_ALIAS) and flags that control the
operation of this function. Currently defined flags are:
GVF_LOCAL_ONLY - set a local variable only.
GVF_GLOBAL_ONLY - set a global environmental
variable only.
GVF_SAVE_VAR - if GVF_LOCAL_ONLY is not set, and type
is LV_VAR then also store the variable
to ENVARC: as well as ENV
RESULT
success - If non-zero, the variable was sucessfully set, FALSE
indicates failure
SEE ALSO
SplitName
SYNOPSIS
SplitName(name, separator, buf, oldpos, size)
LONG SplitName(STRPTR, UBYTE, STRPTR, WORD, WORD);
DESCRIPTION
Split a path into parts at the position of seperator
INPUTS
name - Split this path
seperator - Split it at this seperator
buf - Copy the current part into this buffer
oldpos - Begin at this place with the search for seperator.
If you call this function for the first time, set it
to 0.
size - The size of the buffer. If the current part of the
path is bigger than size-1, only size-1 bytes will
be copied
RESULT
The next position to continue for the next part or -1 if
there is no seperator after name+oldpos
StartNotify
SYNOPSIS
StartNotify(notify)
LONG StartNotify(struct NotifyRequest *);
DESCRIPTION
Send a notification request to a filesystem. You will then be notified
whenever the file (or directory) changes
INPUTS
notify -- a notification request for the file or directory to monitor
RESULT
Success/failure indicator
NOTES
The file or directory connected to a notification request does not have
to exist at the time of calling StartNotify().
The NotifyRequest used with this function should not be altered while
active.
SEE ALSO
StartSystem
SYNOPSIS
StartSystem(data)
ULONG StartSystem(APTR);
StrToDate
SYNOPSIS
StrToDate(datetime)
LONG StrToDate(struct DateTime *);
DESCRIPTION
Converts a human readable ASCII string into an AmigaDOS
DateStamp
INPUTS
DateTime - a pointer to an initialized DateTime structure.
The structure should be initialized as follows:
\begin{description}
\item{dat_Stamp} The converted date will be written here
\item{dat_Format} How to convert the datestamp into
dat_StrDate. Can be any of the following:
\begin{description}
\item{FORMAT_DOS} AmigaDOS format (dd-mmm-yy). This
is the default if you specify something other
than any entry in this list.
\item{FORMAT_INT} International format (yy-mmm-dd).
\item{FORMAT_USA} American format (mm-dd-yy).
\item{FORMAT_CDN} Canadian format (dd-mm-yy).
\item{FORMAT_DEF} default format for locale.
\end{description}
\item{dat_Flags} Modifies dat_Format. The only flag
used by this function is DTF_FUTURE. If set, then
a string like "Monday" refers to the next monday.
Otherwise it refers to the last monday.
\item{dat_StrDay} Ignored.
\item{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.
\item{dat_StrTime} Pointer to a buffer which contains the
time in the ASCII 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.
\end{description
RESULT
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
SEE ALSO
StrToLong
SYNOPSIS
StrToLong(string, value)
LONG StrToLong(STRPTR, LONG *);
DESCRIPTION
Convert a string to a long number
INPUTS
string - The value to convert
value - The result is returned here
RESULT
How many characters in the string were considered when it was
converted or -1 if no valid number could be found
NOTES
The routine doesn't check if the number if too large.
HISTORY
04-07-02 Added ability to read hex-strings.
EXAMPLE
// Valid number are: 5, -1, +3, +0007, $feed, -0xBEEF, etc
SystemTagList
SYNOPSIS
SystemTagList(command, tags)
LONG SystemTagList(STRPTR, struct TagItem *);
DESCRIPTION
Execute a command via a shell. As defaults, the process will use the
current Input() and Output(), and the current directory as well as the
path will be inherited from your process. If no path is specified, this
path will be used to find the command.
Normally, the boot shell is used but other shells may be specified
via tags. The tags are passed through to CreateNewProc() except those
who conflict with SystemTagList(). Currently, these are
NP_Seglist
NP_FreeSeglist
NP_Entry
NP_Input
NP_Output
NP_CloseInput
NP_CloseOutput
NP_HomeDir
NP_Cli
INPUTS
command -- program and arguments as a string
tags -- see <dos/dostags.h>. Note that both SystemTagList() tags and
tags for CreateNewProc() may be passed
RESULT
The return code of the command executed or -1 or if the command could
not run because the shell couldn't be created. If the command is not
found, the shell will return an error code, usually RETURN_ERROR
NOTES
You must close the input and output filehandles yourself (if needed)
after System() returns if they were specified via SYS_Input or
SYS_Output (also, see below).
You may NOT use the same filehandle for both SYS_Input and SYS_Output.
If you want them to be the same CON: window, set SYS_Input to a filehandle
on the CON: window and set SYS_Output to NULL. Then the shell will
automatically set the output by opening CONSOLE: on that handler.
If you specified SYS_Asynch, both the input and the output filehandles
will be closed when the command is finished (even if this was your Input()
and Output().
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
9.1.2000 SDuvan implemented
SEE ALSO
UnGetC
SYNOPSIS
UnGetC(file, character)
LONG UnGetC(BPTR, LONG);
DESCRIPTION
Push a character back into a read filehandle. If you've read
a character from that file you may always push at least 1 character
back. UnGetC(file,-1) ungets the last character read. This also
works for EOF
INPUTS
file - Filehandle you've read from.
character - Character to push back or EOF
RESULT
!=0 if all went well, 0 if the character couldn't be pushed back.
IoErr() gives additional information in that case
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
UnLoadSeg
SYNOPSIS
UnLoadSeg(seglist)
LONG UnLoadSeg(BPTR);
DESCRIPTION
Free a segment list allocated with LoadSeg
INPUTS
seglist - The segment list
RESULT
success - returns whether everything went ok. Returns FALSE if
seglist was NULL
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO
UnLock
SYNOPSIS
UnLock(lock)
void UnLock(BPTR);
DESCRIPTION
Free a lock created with Lock
INPUTS
lock -- The lock to free
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
UnLockDosList
SYNOPSIS
UnLockDosList(flags)
void UnLockDosList(ULONG);
DESCRIPTION
Frees a lock on the dos lists given by LockDosList
INPUTS
flags - the same value as given to LockDosList
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
UnLockRecord
SYNOPSIS
UnLockRecord(fh, offset, length)
LONG UnLockRecord(BPTR, ULONG, ULONG);
DESCRIPTION
Release a lock made with LockRecord
INPUTS
fh -- filehandle the lock was made on
offset -- starting position of the lock
length -- length of the record in bytes
NOTES
The length and offset must match the corresponding LockRecord()
call.
SEE ALSO
UnLockRecord64
DESCRIPTION
Release a lock made with LockRecord64
INPUTS
fh -- filehandle the lock was made on
offset -- starting position of the lock
length -- length of the record in bytes
NOTES
The length and offset must match the corresponding LockRecord64()
call.
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
UnLockRecords
SYNOPSIS
UnLockRecords(recArray)
LONG UnLockRecords(struct RecordLock *);
DESCRIPTION
Release an array of record locks obtained with LockRecords
INPUTS
recArray -- array of record locks (previously locked with LockRecords
NOTES
A array of records may not be modified when records are locked.
SEE ALSO
UnLockRecords64
DESCRIPTION
Release an array of record locks obtained with LockRecords64
INPUTS
recArray -- array of record locks (previously locked with
LockRecords64
NOTES
A array of records may not be modified when records are locked.
INTERNALS
This function was added in dos.library V50.65.
SEE ALSO
VFPrintf
SYNOPSIS
VFPrintf(file, , argarray)
LONG VFPrintf(BPTR, CONST, IPTR *);
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
VFPrintf
SYNOPSIS
VFPrintf(file, , argarray)
LONG VFPrintf(BPTR, CONST, IPTR *);
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
VFWritef
SYNOPSIS
VFWritef(fh, fmt, argarray)
LONG VFWritef(BPTR, STRPTR, IPTR *);
DESCRIPTION
Write a formatted string (with supplied values) to a specified file.
The string may be of any length and the routine is buffered.
The following format commands may be used (preceded by a '%') a la printf.
S -- string (C style)
Tx -- writes a left justified string padding it to be (at least)
x bytes long
C -- character
Ox -- octal number; maximum width x characters
Xx -- hexadecimal number; maximum width x characters
Ix -- decimal number; maximum width x chararcters
N -- decimal number; any length
Ux -- unsigned decimal number; maximum width x characters
$ -- ignore parameter
Note: 'x' above is the character value - '0
INPUTS
fh -- file to write the output to
fmt -- format string
argarray -- pointer to an array of formatting values
RESULT
The number of bytes written or -1 if there was an error
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
22.12.99 SDuvan implemented
SEE ALSO
VPrintf
SYNOPSIS
VPrintf(format, argarray)
LONG VPrintf(STRPTR, IPTR *);
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
VPrintf
SYNOPSIS
VPrintf(format, argarray)
LONG VPrintf(STRPTR, IPTR *);
HISTORY
29-10-95 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
WaitForChar
SYNOPSIS
WaitForChar(file, timeout)
LONG WaitForChar(BPTR, LONG);
DESCRIPTION
Wait for a character to arrive at a filehandle. The filehandle
can be either a console handle, or a regular file. For a regular
file most filesystems will return a character immediately, but
sometimes (for example a network handler) the character may not
have arrived
INPUTS
file - File to wait for a character on.
timeout - Number of microseconds to wait for the character
to arrive. A value of 0 says to wait indefinately
RESULT
!= 0 if a character arrived before the timeout expired
== 0 if no character arrived
NOTES
Many filesystems do not implement this function.
HISTORY
27-11-96 digulla automatically created from
dos_lib.fd and clib/dos_protos.h
WaitPkt
SYNOPSIS
WaitPkt(port)
struct DosPacket * WaitPkt(struct MsgPort *);
DESCRIPTION
Wait for a packet to arrive at your process' pr_MsgPort. It will call
pr_PktWait if such a function is installed
RESULT
The packet we received
NOTES
The packet will be released from the port.
This function should NOT be used. It's there only for AmigaOS
compatibility.
Write
SYNOPSIS
Write(file, , length)
LONG Write(BPTR, CONST, LONG);
DESCRIPTION
Write some data to a given file. The request is directly
given to the filesystem - no buffering is involved. For
small amounts of data it's probably better to use the
buffered I/O routines
INPUTS
file - filehandle
buffer - pointer to data buffer
length - number of bytes to write. The filesystem is
advised to try to fulfill the request as good
as possible
RESULT
The number of bytes actually written, -1 if an error happened.
IoErr() will give additional information in that case
WriteChars
SYNOPSIS
WriteChars(buf, buflen)
LONG WriteChars(STRPTR, ULONG);
DESCRIPTION
Writes the contents of the buffer to the current output stream.
The number of bytes written is returned
INPUTS
buf - Buffer to be written.
buflen - Size of the buffer in bytes
RESULT
The number of bytes written or EOF on failure. IoErr() gives
additional information in that case
HISTORY
5-12-96 turrican automatically created from
dos_lib.fd and clib/dos_protos.h
SEE ALSO