2 =( Index : TEKlib / Io module reference manual )=
4 -------------------------------------------------------------------------------
6 TEKlib provides a filesystem namespace for any number of mountpoints
7 (''devices'') and logical roots (''assigns''). ''Handlers'' are modules
8 implementing specific roots in the filesystem; they can be mounted
9 explicitely or initialize themselves on demand. On most platforms the
10 filesystem is initially populated with a 'default handler' that occupies the
11 root node, thus abstracting from a host's native filesystem. See the
12 [[#Introduction]] section for details.
14 ===( Open and close )===
16 TOpenFile() || Open file
17 TCloseFile() || Close file
19 ===( Unbuffered I/O )===
21 TRead() || Read from file
22 TWrite() || Write to file
23 TSeek() || Set the position for reading and writing
25 ===( File I/O, buffered )===
27 TFlush() || Flush file buffers
28 TFRead() || Read from file
29 TFWrite() || Write to file
30 TFPutC() || Put character to file
31 TFGetC() || Read character from file
32 TFUngetC() || Put back character to file
33 TFGetS() || Read string from file
34 TFPutS() || Write string to file
35 TFEoF() || Test End-Of-File condition
39 TLockFile() || Lock a file or directory
40 TUnlockFile() || Release a lock
41 TExamine() || Examine lock or file
42 TExNext() || Examine next in a directory
43 TDupLock() || Duplicate a lock
44 TChangeDir() || Change current directory to lock
45 TParentDir() || Get lock on parent of a lock
46 TOpenFromLock() || Turn an open lock into a file
48 ===( Filesystem operations )===
50 TRename() || Rename an object
51 TDeleteFile() || Delete a disk object
52 TMakeDir() || Make a directory
53 TSetFileDate() || Set datestamp of a filesystem object
55 ===( Namespace operations )===
57 TMount() || Mount/unmount a device
58 TMakeName() || Make a path/filename
59 TAssignLock() || Create a logical assign to lock
60 TAssignLate() || Create a logical assign to name
61 TNameOf() || Return name of lock or file
62 TAddPart() || Add a path component to a path
66 TInputFH() || Get the task's standard input handle
67 TOutputFH() || Get the task's standard output handle
68 TErrorFH() || Get the task's standard error handle
69 TGetIOErr() || Get last I/O error code in current context
70 TSetIOErr() || Set I/O error in current context
71 TFault() || Return text representation of an error
73 ===( Asynchronous I/O )===
75 TObtainPacket() || Allocate an I/O message
76 TReleasePacket() || Free an I/O message
86 The colon stands for the root of the "default" filesystem.
88 Typically this is the device from which TEKlib was started, e.g. the
89 filesystem root in the host operating system. If the host operating
90 system has multiple roots then all drives will show up in this list.
91 Under Windows, for example, the contents of {{:}} is a listing of
92 single-letter entries like {{A}}, {{C}}, {{D}}.
94 Names preceding the colon address devices explicitely:
98 This would address a device named {{work}}.
102 This would address a file named {{out}} on a device named {{stdio}}.
104 Named devices can have different origins:
106 * The device is mounted using TMount(), and by that means the
107 name is bound to an instance of an I/O handler.
109 * The name is a logical assign. Logical assigns can be obtained
110 with functions like TAssignLock() or TAssignLate().
112 * The device is mounted automatically on the first attempt to
115 Handlers can place logical assigns in the I/O namespace during
116 initialization. The default handler will supply the following
117 late-binding assigns (more may follow in the future):
121 This is the directory in which the application resides in the host
122 filesystem. E.g. this would point to {{:home/paul/tek}} if Paul
123 started {{~/tek/coolapp}} on his Unix account (regardless of his
128 TEKlib's system directory in the host filesystem. Under BSD, for
129 example, this would point to {{:usr/local/tek}}, on the Amiga
130 platform this would be {{:TEKLIB}} and under a German-localised
131 installation of Windows {{:C/Programme/Gemeinsame Dateien/tek}}.
133 === Path components ===
135 Path components are separated by slashes. A freestanding slash refers to
136 the parent directory. This is different from some other filesystems and
137 can lead to confusion; while {{foo/bar}} and {{foo//bar}} are treated
138 equally in Unix, this is not true for TEKlib, where {{foo//bar}} would
139 have the same effect as {{bar}}.
143 This would access the parent directory, like {{..}} in Windows or Unix.
147 This would access the directory {{foo}} in the parent of the parent
148 directory, like e.g. {{..\..\foo}} in Windows.
152 This would address the parent relative to the directory in which
153 the application resides.
155 The Io module has a support function for the composition of
156 path names, TAddPart(). It takes care of these rules.
158 The current directory can be addressed with an {{""}} (empty
159 string). The empty string is equivalent to {{.}} on many other
162 === Name conversion ===
164 {{.}} and {{..}} are ambiguous for the default handler on many operating
165 systems and should be avoided. When directory contents are
166 scanned, {{.}} and {{..}} will not show up in the application unless
167 they refer to regular files or directories on the given host.
169 Future implementations of TEKlib's default filesystem handler
170 may implement more rigid checking and reject more filenames and
173 === Case sensitivity ===
175 Current implementations of the TEKlib default handler in no way
176 try to abstract from (or enforce) case-sensitivity (or
177 insensitivity) in their underlying host filesystem. Prepare your
178 application to deal with case-sensitive names, and be prepared
179 for (but do not depend on) multiple occurances of the same name
180 with different uppercase/lowercase combinations.
186 TLockFile - Lock a file or directory
189 lock = TIOLockFile(TIOBase, name, mode, tags)
190 TAPTR TAPTR TSTRPTR TINT TTAGITEM*
192 lock = TLockFile(name, mode, tags)
193 TAPTR TSTRPTR TINT TTAGITEM*
196 Locate a named file or directory, lock out other accessors,
197 and return a handle that allows for examination of the object.
199 The mode determines the type of access locking:
202 Attempts a shared lock. Multiple shared
203 locks on a file or directory can succeed.
206 Attempts an exclusive lock. Only one
207 exclusive lock can be held on an object
210 When the object is not found or cannot be locked then the
211 return value is TNULL; a secondary error code can be
212 obtained using TGetIOErr().
215 - {{name}} - Name of the file or directory
216 - {{mode}} - Access mode
217 - {{tags}} - Pointer to an array of tag items
223 - {{lock}} - Lock handle, or TNULL if failed
226 * Exclusive locks to directories are not guaranteed to work
227 universally. Some platform-specific handlers may choose to
228 grant only shared locks on directories.
229 * As of this writing, not all filesystem handlers actually
230 implement all locking modes. The POSIX filesystem handler,
231 for example, does not currently use fcntl or a similar
232 mechanism to lock out other accessors.
235 TUnlockFile(), TExamine(), TOpenFile(), TOpenFromLock(),
241 TUnlockFile - Release a lock
244 TIOUnlockFile(TIOBase, lock)
251 Unlock and free a handle obtained with TLockFile(), TDupLock(),
252 TParentDir() or TMakeDir(). Each lock claimed somewhere
253 must be unlocked once (and only once).
256 - {{lock}} - Lock to release
259 TLockFile(), TDupLock(), TParentDir()
264 TOpenFile - Open file
267 file = TIOOpenFile(TIOBase, name, mode, tags)
268 TAPTR TAPTR TSTRPTR TUINT TTAGITEM*
270 file = TOpenFile(name, mode, tags)
271 TAPTR TSTRPTR TUINT TTAGITEM*
274 The named file is opened and a file handle returned. Name can
275 be a device name such as "foo:", an absolute path such as
276 "foo:bar", or a path relative to the current directory, like
279 The mode argument determines the access and arbitration type
283 An existing file is opened for read access
284 only; no attempts are made to lock out other
288 An existing file is opened for read/write
289 access; no attempts are made to lock out
293 This opens a new file for read/write access.
294 The file will be locked exclusively, i.e.
295 no other accessors are allowed at the same
296 time. If a file of that name existed, it is
297 truncated to a length of zero bytes.
300 Opens a new or existing file for read/write
301 access, locked in shared mode, i.e. other
302 accessors are allowed to read from the file
305 When the file cannot be opened then this function returns TNULL,
306 and a secondary error code is available by calling TGetIOErr().
309 - {{name}} - Name of the file to open
310 - {{mode}} - Access and arbitration mode
311 - {{tags}} - Pointer to an array of tag items
314 None defined currently
317 - {{file}} - File handle, or TNULL if failed
320 * TFMODE_READONLY should be the preferred mode if you need no
321 write access or locking. Note, for example, that it is common
322 behavior under Windows that files copied from a CD-Rom are
325 * As of this writing, not all filesystem handlers actually
326 implement all locking modes. The POSIX filesystem handler,
327 for example, does not currently use fcntl or a similar
328 mechanism to lock out other accessors.
331 TCloseFile(), TLockFile(), TOpenFromLock()
336 TCloseFile - Close a file
339 success = TIOCloseFile(TIOBase, file)
342 success = TCloseFile(file)
346 Close a file that was opened with TOpenFile().
348 The return value indicates whether outstanding write operations,
349 buffers flushes and the like were successful. If the close
350 operation failed, the file handle has been deallocated anyway
351 and may not be used any longer.
353 All file handles that have been opened explicitely must be
354 closed explicitely, once and only once.
357 - {{file}} - Filehandle from TOpenFile() or TOpenFromLock()
360 TOpenFile(), TOpenFromLock()
365 TRead - Read from a file
368 rdlen = TIORead(TIOBase, file, buffer, buflen)
369 TINT TAPTR TAPTR TAPTR TINT
371 rdlen = TRead(file, buffer, buflen)
372 TINT TAPTR TAPTR TINT
375 This function reads a block of data from an open file
376 into the buffer specified. The buflen argument is the size
377 of the buffer, i.e. the maximum number of bytes that can
378 be read in this operation.
380 The return value, if greater than zero, is the number of
381 bytes that have been read successfully. An End-Of-File
382 condition is indicated by a return value of zero. An error
383 is indicated with a return value of -1, in which case
384 additonal error diagnostics can be obtained with the
385 TGetIOErr() function.
388 - {{file}} - File handle
389 - {{buffer}} - Buffer to read into
390 - {{len}} - Maximum number of bytes to read
393 - {{rdlen}} - Number of bytes read, or -1 if an error occured
396 * This function implements no buffering. The I/O request
397 will be directly forwarded to the underlying handler. Small
398 reads are performed very inefficiently with this function.
400 * For switching from buffered I/O calls back to unbuffered
401 functions like this, you must call TFlush().
404 TWrite(), TFWrite(), TOpenFile(), TFGetC()
409 TWrite - Write to a file
412 wrlen = TIOWrite(TIOBase, file, buffer, buflen)
413 TINT TAPTR TAPTR TAPTR TINT
415 wrlen = TWrite(file, buffer, buflen)
416 TINT TAPTR TAPTR TINT
419 This function writes a block of data from the buffer specified
420 to an open file handle. The buflen argument is the size of the
421 buffer, i.e. the maximum number of bytes that will be written
424 The return value, if greater than zero, is the number of
425 bytes that have been written successfully. An error is
426 indicated with a return value of -1, in which case additonal
427 error diagnostics can be obtained with the TGetIOErr() function.
430 - {{file}} - File handle
431 - {{buffer}} - Buffer to write
432 - {{len}} - Number of bytes to write
435 - {{rdlen}} - Number of bytes written, or -1 if an error occured
438 * This function implements no buffering. The I/O request
439 will be directly forwarded to the underlying handler. Small
440 writes are performed very inefficiently with this function.
442 * For switching from buffered I/O calls back to unbuffered
443 functions like this, you must call TFlush().
446 TWrite(), TFWrite(), TOpenFile(), TFGetC()
451 TFlush - Flush file buffers
454 success = TIOFlush(TIOBase, file)
457 success = TFlush(file)
461 Flush buffers from a file handle and readjust the internal
462 read/write cursor. Calling this function is mandatory if you
463 want to switch from buffered I/O functions like TFPutC()
464 back to unbuffered functions like TWrite().
466 The return value will be TFALSE to indicate that an error
467 occured while writing out buffers or while seeking to the
471 - {{file}} - File handle to flush
474 - {{success}} - TTRUE if flushing succeded, TFALSE on error.
476 In the case of an error, more detailed information is
477 available via TGetIOErr().
480 Buffers are automatically flushed when a filehandle is
484 TFPutC(), TFGetC(), TFWrite(), TFWrite(), TRead(), TWrite()
489 TSeek - Set the position for reading and writing
492 filepos = TIOSeek(TIOBase, file, offset, offs_hi, mode)
493 TUINT TAPTR TAPTR TINT TINT* TINT
495 filepos = TSeek(file, offset, offs_hi, mode)
496 TUINT TAPTR TINT TINT* TINT
499 This function moves the read/write cursor in a file to a new
500 position and returns the resulting position measured in bytes
501 from the beginning of the file.
503 The offset specifies the number of bytes for moving the cursor,
504 either relative to the current position or to an absolute
505 position from either the beginning or the end of the file,
506 according to the mode argument:
509 Offset is the number of bytes to move the
510 cursor towards the end of the file, relative
511 to the current position. Seek 0 from current
512 to find out where you are.
515 Offset is the absolute number of bytes from the
516 beginning of the file.
519 Offset is the absolute number of bytes from the
522 When the offs_hi argument is TNULL then this function can operate
523 only on files not larger than 2^32-2 bytes. Errors are indicated
524 with a return value of {{0xffffffff}}. Use TGetIOErr() in this case
525 to get extended error diagnostics.
527 When offs_hi is specified then it is a pointer to a 64 bit offset's
528 high-order 32 bits. If the function fails then the return value is
529 {{0xffffffff}}, and TGetIOErr() returns a secondary error code other
530 than {{TIOERR_SUCCESS}}. The integer being pointed to also receives
531 the high-order 32 bits of the resulting file position.
534 - {{file}} - File handle
535 - {{offset}} - Number of bytes to seek
536 - {{offs_hi}} - Pointer to offset's high-order 32 bits, or TNULL
537 - {{mode}} - Seek mode
540 - {{filepos}} - Lower 32 bits of new absolute position, or {{0xffffffff}}.
542 An error is indicated with a return value of {{0xffffffff}}. If the
543 offs_hi argument was specified then you ''must'' call TGetIOErr() to
544 distinguish an error from a valid file position.
552 TFPutC - Write a character, buffered
555 char = TIOFPutC(TIOBase, file, char)
556 TINT TAPTR TAPTR TINT
558 char = TFPutC(file, char)
562 Write a single character to an open file, buffered.
565 - {{file}} - File to write to
566 - {{char}} - Character to write
569 - {{char}} - the character written, or TEOF if an error occured
572 After using this function, call TFlush() before switching
573 back to unbuffered I/O functions.
576 TFlush(), TFGetC(), TRead(), TOpenFile()
581 TFGetC - Read a character, buffered
584 char = TIOFGetC(TIOBase, file)
591 Read the next character from a file. This call is buffered.
594 - {{file}} - File to read from
597 - {{char}} - next character, or TEOF if the end of the file was reached.
600 After using this function, call TFlush() before switching
601 back to unbuffered I/O functions.
604 TFlush(), TFPutC(), TFUngetC(), TRead(), TOpenFile()
609 TFEoF - Determine End-Of-File condition, buffered
612 status = TIOFEoF(TIOBase, file)
619 Check if a file has reached an End-Of-File condition. This
620 function will basically call TFGetC() in order to test for
621 more characters being available, and push the character back
625 - {{file}} - File handle to check
628 - {{success}} - TTRUE if End-Of-File reached, else TFALSE
631 After using this function, call TFlush() before switching
632 back to unbuffered I/O functions.
640 TFRead - Read from a file, buffered
643 rdlen = TIOFRead(TIOBase, file, buffer, buflen)
644 TINT TAPTR TAPTR TAPTR TINT
646 rdlen = TFRead(file, buffer, buflen)
647 TINT TAPTR TAPTR TINT
650 This function reads a block of data from an open file into
651 the specified buffer. The buflen argument is the size of the
652 buffer, i.e. the maximum number of bytes that may be read
653 during this operation.
655 The return value, if greater than zero, is the number of
656 bytes that have been read successfully. An End-Of-File
657 condition is indicated with a return value of zero. An error
658 is indicated with a return value of -1, in which case
659 additional error information can be obtained with a call
662 Unlike TRead() this function operates on the file in buffered
666 - {{file}} - File handle
667 - {{buffer}} - Buffer to read into
668 - {{buflen}} - Number of bytes to read
671 - {{rdlen}} - Number of bytes read, or -1 if an error occured
674 After using a buffered function, call TFlush() before switching
675 back to unbuffered I/O functions like TRead().
678 TFWrite(), TRead(), TOpenFile(), TFGetC()
683 TFWrite - Write to a file, buffered
686 wrlen = TIOFWrite(TIOBase, file, buffer, buflen)
687 TINT TAPTR TAPTR TAPTR TINT
689 wrlen = TFWrite(file, buffer, buflen)
690 TINT TAPTR TAPTR TINT
693 This function writes a block of data from the specified buffer
694 to an open file handle. The buflen argument is the size of the
695 buffer, i.e. the maximum number of bytes that can be written
696 during this operation.
698 The return value, if greater than zero, is the number of
699 bytes that have been written successfully. An error is
700 indicated with a return value of -1, in which case additonal
701 error informations can be obtained with a call to TGetIOErr().
703 Unlike TWrite() this function operates on the file in buffered mode.
706 - {{file}} - File handle
707 - {{buffer}} - Buffer to write
708 - {{buflen}} - Number of bytes to write
711 - {{rdlen}} - Number of bytes actually written, or -1 if an error occured
714 After using a buffered function, call TFlush() before switching
715 back to unbuffered I/O functions like TRead().
718 TFWrite(), TWrite(), TOpenFile(), TFGetC()
723 TExamine - Examine a lock or filehandle
726 numattr = TIOExamine(TIOBase, object, tags)
727 TINT TAPTR TAPTR TTAGITEM*
729 numattr = TExamine(object, tags)
733 Examine a lock or an open filehandle and query attributes via
734 a list of tagitems. The return value will be the number of
735 attributes that could be retrieved. Note that you may have to
736 check the return value, because not all filesystem handlers
737 must implement all possible attributes. A general error is
738 indicated with a return value of -1, in which case you can
739 use TGetIOErr() for getting more detailed information.
741 Use TExNext() for scanning the contents of a directory you have
745 - {{object}} - Lock or file handle to examine
746 - {{tags}} - Pointer to a list of tag items
749 TFATTR_Name, (TSTRPTR *)
750 Query the object's name. Tag data must be the address of a
751 string variable, which will receive a pointer to the name.
752 Warning: This pointer will become invalid as soon as you
753 call TExNext() the next time or TUnlockFile(). You MUST
754 make a copy of the string if you wish to continue to work
755 with the name after that.
757 TFATTR_Type, (TINT *)
758 Query the object type. Tag data must be the address of an
759 integer, which will receive a type code for the object:
768 Entry is a physical, removable, or a logical drive in
772 Object type is unknown
774 More types may follow in the future, so you are advised to
775 treat file, directory and volume as flags; e.g. every volume
776 is also a directory, and if you are only interested in the
777 directory information, use (type & TFTYPE_Directory). Note:
778 Better leave entries of the type TFTYPE_Unknown alone as they
779 do not currently fit into TEKlib's namespace semantics.
781 TFATTR_Size, (TINT *)
782 Query the object's size in bytes. Tag data must be the address
783 of an integer, which will receive the size of the object
784 in bytes. Note that the size of directory entries will
787 TFATTR_Date, (TDATE *)
788 Query the object's last modification date. Tag data must be
789 the address of a TDATE structure, which will receive a TEKlib
790 datestamp for the object in question.
792 TFATTR_DateBox, (struct TDateBox *)
793 Query the object's last modification date. Tag data must be
794 the address of a TDateBox structure, which will receive a
795 datestamp for the object in question. The TDateBox
796 structure is defined in tek/mod/time.h.
799 - {{numattr}} - Number of attributes queried, or -1 on error
802 TExNext(), TLockFile(), TUnlockFile(), TOpenFile()
807 TExNext - Examine next in a directory
810 numattr = TIOExNext(TIOBase, lock, tags)
811 TINT TAPTR TAPTR TTAGITEM*
813 numattr = TExNext(lock, tags)
817 Examine the next entry in a locked directory, and query
818 attributes via a list of tag items. The return value will
819 be the number of attributes that could be retrieved
820 successfully, or -1 when all entries in the directory have
821 been examined. Use TGetIOErr() to distinguish the end of
822 a directory from a general I/O error.
825 - {{lock}} - Lock handle to examine
826 - {{tags}} - Pointer to a list of tag items
829 See TExamine() for the possible tags.
832 numattr - Number of attributes queried, or -1 on error.
835 TExamine(), TLockFile()
840 TChangeDir - Change current directory to lock
843 oldlock = TIOChangeDir(TIOBase, lock)
846 oldlock = TChangeDir(lock)
850 Change the current task's current directory to the lock
851 specified. If successful, the lock on the previous current
852 directory will be returned to the caller. If the current task
853 has no current directory, or if an error occured, the return
854 will be TNULL. In the latter case, use TGetIOErr() to get more
855 details about the problem.
858 - {{lock}} - Lock handle to change the current directory to
861 oldlock - Lock of the previous current directory, or TNULL
863 The result will be TNULL if the current task had no current
864 directory or when an error occured.
867 * Note that the caller becomes responsible for the lock
868 returned by this function. Just like any other lock, it
869 must be released somewhere.
871 * Each task in TEKlib has a currentdir of its own. Initially, it
872 is inherited from its parent when a new task is created.
875 TLockFile(), TParentDir(), TMakeDir()
880 TParentDir - Get lock on parent of a lock
883 parentlock = TIOParentDir(TIOBase, lock)
886 parentlock = TParentDir(lock)
890 Create a new lock on the parent directory of the lock
894 - {{lock}} - Lock handle to get parent from
897 - {{parentlock}} - Lock to the parent directory of the lock
900 TLockFile(), TUnlockFile(), TChangeDir(), TMakeDir()
905 TNameOf - Get the name of an object
908 len = TIONameOf(TIOBase, object, buf, buflen)
909 TINT TAPTR TAPTR TSTRPTR TINT
911 len = TNameOf(object, buf, buflen)
912 TINT TAPTR TSTRPTR TINT
915 Get the fully qualified path and name of the object specified.
916 Object can be an open file handle or a lock. Buf and buflen
917 determine the destination buffer for the name string to be
918 written to. Note that the length of the destination buffer
919 is assumed to include an extra byte for the strings's trailing
920 zero. If buf and buflen are zero, only the length of the string
921 is calculated. In case of an error, the return value is -1.
924 - {{object}} - A lock or a file handle
925 - {{buf}} - Destination string buffer, or TNULL
926 - {{buflen}} - Length of the destination buffer, or 0
929 - {{len}} - Length of the name string, or -1 in case of an error
932 TLockFile(), TOpenFile(), TAddPart()
937 TDupLock - Duplicate a lock
940 newlock = TIODupLock(TIOBase, lock)
943 newlock = TDupLock(lock)
947 This function creates a duplicate of a shared lock, and
948 returns another lock to the same object.
951 - {{lock}} - Lock handle to duplicate
954 - {{newlock}} - A duplicate of the lock, or TNULL on error.
956 Use TGetIOErr() to get more detailed information in case
960 TLockFile(), TChangeDir(), TUnlockFile()
962 =={ TOpenFromLock }==
965 TOpenFromLock - Turn a lock into an open file
968 file = TIOOpenFromLock(TIOBase, lock)
971 file = TOpenFromLock(lock)
975 This function turns a lock to a file into an open file
976 handle. The lock will be absorbed by the newly created
977 filehandle, and is no longer usable. If this function
978 fails, the lock is still valid. In case of failure, use
979 TGetIOErr() for error diagnostics.
982 - {{lock}} - Lock handle to turn into a file
985 - {{file}} - Newly opened file handle
988 TLockFile(), TOpenFile()
993 TAddPart - Add a path component to a path
996 len = TIOAddPart(TIOBase, path, part, buf, buflen)
997 TINT TAPTR TSTRPTR TSTRPTR TSTRPTR TINT
999 len = TAddPart(path, part, buf, buflen)
1000 TINT TSTRPTR TSTRPTR TSTRPTR TINT
1003 Taking into account all possible path delimiters, add a part
1004 to a path, and render the resulting string to the destination
1005 specified throughout buf and buflen. If buf is TNULL and buflen
1006 zero, only the length will be calculated. Either way, the
1007 actual or expected length of the resulting string will be
1008 returned, or -1 if an error occured. Note that the length of
1009 the destination buffer is expected to include an extra byte
1010 for the string's trailing zero.
1013 - {{path}} - First path component
1014 - {{part}} - Second path component
1015 - {{buf}} - Destination buffer, or TNULL
1016 - {{buflen}} - Length of destination buffer, or zero
1019 - {{len}} - Length of the resulting string, or -1 if an error occured
1027 TRename - Rename a file or directory.
1030 success = TIORename(TIOBase, oldname, newname)
1031 TINT TAPTR TSTRPTR TSTRPTR
1033 success = TRename(oldname, newname)
1034 TINT TSTRPTR TSTRPTR
1037 This function tries to rename the file or directory specified
1038 throughout oldname to newname. If an object of the new name
1039 already exists then an error is returned. Both oldname and
1040 newname can contain path parts, in which case the object will
1041 be moved across directories. Attempts to rename an object across
1042 different filesystems will fail, and the result will be TFALSE.
1045 - {{oldname}} - Old name of an object
1046 - {{newname}} - New name for the object
1049 - {{success}} - boolean
1052 TMakeDir(), TDeleteFile()
1057 TMakeDir - Create a new directory
1060 lock = TIOMakeDir(TIOBase, name, tags)
1061 TAPTR TAPTR TSTRPTR TTAGITEM*
1063 lock = TMakeDir(name, tags)
1064 TAPTR TSTRPTR TTAGITEM*
1067 Attempt to create a new directory of the given name. If
1068 successful, a shared lock to the newly created directory
1069 will be returned. Otherwise, the return value will be
1070 TNULL, and a secondary error code is available by calling
1074 - {{name}} - Name of the directory to create
1075 - {{tags}} - Pointer to an array of tagitems
1078 - {{lock}} - Shared lock to newly created directory, or TNULL
1081 TLockFile(), TUnlockFile(), TRename(), TDeleteFile()
1086 TDeleteFile - Delete an object
1089 success = TIODeleteFile(TIOBase, name)
1092 success = TDeleteFile(name)
1096 This function deletes the object of the specified name.
1097 If the addressed object is a directory, it must be empty
1098 for this function to succeed.
1101 - {{name}} - Name of the object to delete
1104 - {{success}} - Boolean
1107 TRename(), TMakeDir()
1112 TSetIOErr - Set I/O error code
1115 olderror = TIOSetIOErr(TIOBase, newerror)
1118 olderror = TSetIOErr(newerror)
1122 This function sets the I/O error code in the caller's task
1123 context to the value specified as newerror. The previous
1124 error code is returned to the caller.
1127 - {{newerror}} - New error code in the current task
1130 - {{olderror}} - Last error code in the current task
1133 TGetIOErr(), TFault()
1138 TGetIOErr - Get last I/O error code
1141 error = TIOGetIOErr(TIOBase)
1148 Most I/O functions set a secondary error condition in the
1149 caller's task context in case of a problem. Use this function
1150 to query it. Error codes are defined in tek/mod/io.h, and can
1151 be translated to plain English using TFault().
1153 Most functions reset the task's current error condition to
1154 zero on success, but this may not be true for all functions.
1155 To be sure, call TGetIOErr() only when a function's primary
1156 return value indicates a problem, or use TSetIOErr() to
1160 - {{error}} - Secondary error code set by the last I/O function
1163 TSetIOErr(), TFault()
1168 TFault - Return text representation of an error
1171 len = TIOFault(TIOBase, code, buf, buflen, tags)
1172 TINT TAPTR TINT TSTRPTR TINT TTAGITEM*
1174 len = TFault(code, buf, buflen, tags)
1175 TINT TINT TSTRPTR TINT TTAGITEM*
1178 This function writes a text representation of an error code
1179 into a buffer specfified throughout buf and buflen. If the
1180 buffer arguments are TNULL respective zero, only the length
1181 of the string will be calculated and returned to the caller.
1182 Note that buflen is expected to include an extra byte for
1183 the string's trailing zero.
1185 By convention, error messages should be no longer than
1186 79+1 characters (and preferrably much shorter).
1189 - {{code}} - Error code
1190 - {{buf}} - Destination buffer, or TNULL
1191 - {{buflen}} - Length of the buffer, or zero
1192 - {{tags}} - reserved for future extensions
1195 - {{len}} - Length of the error string, or -1 in case of an error
1198 TGetIOErr(), TSetIOErr()
1203 TAssignLate - Add a late-binding assign
1206 success = TIOAssignLate(TIOBase, devname, pathname)
1207 TBOOL TAPTR TSTRPTR TSTRPTR
1209 success = TAssignLate(devname, pathname)
1210 TBOOL TSTRPTR TSTRPTR
1213 This function assigns a logical device name to the specified
1214 path. The device name must be without trailing colon. The
1215 assignment is late-binding, i.e. the assign is stored
1216 symbolically, and resolved upon the first access to its name.
1219 - {{devname}} - Name of the logical device, without colon
1220 - {{pathname}} - A fully qulified TEKlib path
1223 - {{success}} - Boolean
1226 It is currently not possible to remove a late-binding assign
1227 from the namespace. If you want to be able to remove an assign,
1228 use TAssignLock() instead.
1231 TAssignLock(), TGetIOErr()
1236 TAssignLock - Add an assignment to the namespace
1239 success = TIOAssignLock(TIOBase, devname, lock)
1240 TBOOL TAPTR TSTRPTR TAPTR
1242 success = TAssignLock(devname, lock)
1246 This function assigns a logical device name to the specified
1247 lock. The device name must be without trailing colon. Passing
1248 TNULL for the lock cancels outstanding assigns to that name.
1250 Note that if this function succeeds, the lock will be absorbed
1251 by the I/O module's internal device list, and is no longer
1252 valid. If you need to keep a copy of the lock, pass a duplicate
1253 created with TDupLock().
1256 - {{devname}} - Name of the logical device, without colon
1257 - {{lock}} - A lock to be associated
1260 - {{success}} - Boolean
1263 TAssignLate(), TGetIOErr()
1265 =={ TObtainPacket }==
1268 TObtainPacket - Obtain an I/O handler packet
1271 iomsg = TIOObtainPacket(TIOBase, name, namepart)
1272 TIOMSG* TAPTR TSTRPTR TSTRPTR*
1274 iomsg = TObtainPacket(name, namepart)
1275 TIOMSG* TSTRPTR TSTRPTR*
1278 Resolve the specified name and obtain an I/O handler message (or
1279 ''packet'') from the corresponding handler. A pointer to the
1280 handler-independent part of the name will be returned in the
1281 variable being pointed to by namepart.
1283 "foo:bar" would try to obtain the I/O message from the handler
1284 responsible for "foo", and return a pointer to "bar" via the
1285 variable being pointed to by namepart.
1287 "foo/bar" would try to compose the full name from the current
1288 task's current directory. If present, the resulting I/O message
1289 will be obtained from the handler on which the current directory
1290 resides, and the name part would possibly result in something
1291 like "home/paul/foo/bar".
1293 If no lock on a current directory is present in the current task
1294 context then a lock on an application's current directory will be
1295 attempted from the default I/O handler.
1297 The I/O message can be used by implementors of direct handler
1298 communications, such as for asynchronous I/O (overlapping
1299 reads and writes), etc. After filling in fields appropriately,
1300 the packet can be sent to its handler with exec:TPutIO().
1302 See also tek/mod/ioext.h for the I/O message structure and
1306 - {{name}} - Path/file name
1307 - {{namepart}} - Pointer to a string variable
1309 The string variable receives a pointer to the handler-independent
1313 - {{iomsg}} - An I/O message ready for usage, or TNULL
1315 TNULL will be returned if no handler can resolve the requested
1319 TReleasePacket(), exec:TPutIO()
1321 =={ TReleasePacket }==
1324 TReleasePacket - Release an I/O message
1327 TIOReleasePacket(TIOBase, iomsg)
1330 TReleasePacket(iomsg)
1334 Free an I/O message allocated with TObtainPacket(). When the
1335 last outstanding I/O message is returned to its handler, the
1336 handler will usually close down and free its resources. All
1337 messages obtained for direct communication with handlers must
1338 be freed using this function.
1341 - {{iomsg}} - I/O message allocated with TObtainPacket()
1349 TMakeName - Make a path/file name
1352 len = TIOMakeName(TIOBase, name, dest, dlen, mode, tags)
1353 TINT TAPTR TSTRPTR TSTRPTR TINT TINT TTAGITEM*
1355 len = TMakeName(name, dest, dlen, mode, tags)
1356 TINT TSTRPTR TSTRPTR TINT TINT TTAGITEM*
1359 This function tries to convert the specified name to a
1360 fully-qualified, absolute path/file name, and renders the
1361 result to the destination buffer. The length specified with dlen
1362 is assumed to include an extra byte for the string's trailing
1365 If dest is TNULL and dlen zero, only the length of the resulting
1366 string will be calculated and returned to the caller. In case
1367 of failure, the return value is -1.
1369 The mode argument determines the type of conversion.
1373 Tries to convert a path or component in host-style
1374 naming conventions to a fully-qualified path/name
1375 in TEKlib's naming conventions. In this mode, the
1376 name resolution request will be sent to the handler
1377 responsible for the current task's current directory.
1380 Tries to convert a path or component in TEKlib-style
1381 naming conventions to a fully-qualified path/name
1382 in the host's naming conventions. If an absolute path
1383 was specified, the name resolution request will be sent
1384 to the respective handler. If a relative name was given,
1385 the request will be sent to the handler responsible for
1386 the current task's current directory.
1388 An error is returned if the addressed handler does not support
1389 the name resolution action.
1392 - {{name}} - Path/file or component name to be converted
1393 - {{dest}} - Destination buffer, or TNULL
1394 - {{dlen}} - Length of destination buffer, or 0
1395 - {{mode}} - Conversion mode
1396 - {{tags}} - Pointer to an array of tag items
1399 None currently defined.
1402 - {{len}} - Length of the resulting string, or -1 in case of an error
1404 In case of an error, use TGetIOErr() for getting extended error
1408 TNameOf(), TAddPart()
1413 TMount - Mount a named device
1416 success = TIOMount(TIOBase, devname, action, tags)
1417 TBOOL TAPTR TSTRPTR TINT TTAGITEM*
1419 success = TMount(devname, action, tags)
1420 TBOOL TSTRPTR TINT TTAGITEM*
1423 This function attempts to mount or unmount the device name
1424 specified. Actions currently defined:
1427 If successful, an instance of a device or
1428 filesystem handler is loaded, initialized,
1429 and bound to the name. Fails if the name
1433 Tries to unmount the given name. Fails if no
1434 device of the given name is mounted.
1437 - {{devname}} - Name of the device, without trailing {{:}}
1438 - {{action}} - Action code
1439 - {{tags}} - Pointer to an array of tag items
1442 The tags argument usually contains startup arguments and will
1443 be passed to the handler's instance open function. These tags
1444 will be interpreted by TMount():
1446 TIOMount_Handler, (TSTRPTR)
1447 Name of the addressed handler.
1448 Default: The same as devname
1450 TIOMount_HndVersion, (TUINT16)
1451 Minimum version of the handler to be loaded.
1452 Default: 0 (any version will suffice)
1454 All other tags will be forwarded directly to the handler's
1455 instance open function. Tags with a predefined meaning include
1457 TIOMount_Device, (TSTRPTR)
1458 Name of an Exec lowlevel device
1460 TIOMount_InitString, (TSTRPTR)
1461 Startup control arguments
1464 - {{success}} - Boolean
1466 If this function fails, use TGetIOErr() for getting extended
1470 TAssignLock(), TAssignLate(), TGetIOErr()
1475 TFUngetC - Put back one character to a buffered file
1478 pushedchar = TIOFUngetC(TIOBase, file, character)
1479 TINT TAPTR TAPTR TINT
1481 pushedchat = TIOFUngetC(file, character)
1485 Push back one character to a buffered file, where it will be available
1486 for subsequent reads. Only one pushback is guaranteed to succeed.
1487 Passing -1 for the character will cause the last character read to be
1488 pushed back. If the last character read was TEOF, the next character
1491 The return value will be the character that was pushed back, or -1
1492 (TEOF) if an error occured, or when the last character read was TEOF.
1495 - {{file}} - Filehandle
1496 - {{character}} - Chracter to push back, or -1
1499 - {{pushedchar}} - Character pushed back, or -1 if it cannot be pushed back
1502 TFGetC(), TFlush(), TFPutC(), TRead(), TOpenFile()
1507 TFGetS - Read a line from a file, buffered
1510 line = TIOFGetS(TIOBase, file, buffer, len)
1511 TSTRPTR TAPTR TAPTR TSTRPTR TINT
1513 line = TFGetS(file, buffer, len)
1514 TSTRPTR TAPTR TSTRPTR TINT
1517 Read a single line from the specified file, stopping at either TEOF
1518 or a newline character. Up to len minus one characters are written
1519 from the input to the specified buffer. If a newline is read, it is
1520 stored in the buffer. In either case, the resulting string in the
1521 buffer will be terminated with a null byte. The return value will be
1522 set to buffer if successful, or TNULL if an error occured.
1525 - {{file}} - Filehandle
1526 - {{buffer}} - Pointer to a buffer
1527 - {{len}} - Size of the buffer [bytes]
1530 - {{line}} - will be set to buffer, or TNULL in case of an error
1533 TFPutS(), TFGetC(), TFPutC(), TRead(), TOpenFile()
1538 TFPutS - Write a string to a file, buffered
1541 error = TIOFPutS(TIOBase, file, string)
1542 TINT TAPTR TAPTR TSTRPTR
1544 error = TFPutS(file, string)
1548 Write a null-terminated string to a file in a buffered operation;
1549 neither a newline nor a null byte is appended to the data written
1553 - {{file}} - Filehandle
1554 - {{string}} - Pointer to a null-terminated string
1557 - {{error}} - number of bytes written if successful, TEOF on error
1560 TFPutS(), TFGetC(), TFPutC(), TRead(), TOpenFile()
1565 TInputFH - Get a task's standard input file handle
1568 inputfh = TIOInputFH(TIOBase)
1571 inputfh = TInputFH()
1575 Get current task's standard input file handle. If the task
1576 in which the caller is running has no standard input handle,
1577 it is attempted to create one by opening a device named
1580 Note that under no circumstance the caller may close the
1581 resulting filehandle, as it is internally maintained with the
1582 task and getting closed when the task exits.
1585 - {{inputfh}} - current task's input file handle
1588 TOutputFH(), TErrorFH()
1593 TOutputFH - Get a task's standard output file handle
1596 outputfh = TIOOutputFH(TIOBase)
1599 outputfh = TOutputFH()
1603 Get current task's standard output file handle. If the task
1604 in which the caller is running has no standard output handle,
1605 it is attempted to create one by opening a device named
1608 Note that under no circumstance the caller may close the
1609 resulting filehandle, as it is internally maintained with the
1610 task and getting closed when the task exits.
1613 - {{outputfh}} - current task's output file handle
1616 TInputFH(), TErrorFH()
1621 TErrorFH - Get a task's standard error file handle
1624 errorfh = TIOErrorFH(TIOBase)
1627 errorfh = TErrorFH()
1631 Get current task's standard error file handle. If the task
1632 in which the caller is running has no standard error handle,
1633 it is attempted to create one by opening a device named
1636 Note that under no circumstance the caller may close the
1637 resulting filehandle, as it is internally maintained with the
1638 task and getting closed when the task exits.
1641 - {{errorfh}} - current task's error file handle
1644 TInputFH(), TOutputFH()
1646 =={ TSetFileDate }==
1649 TSetFileDate - Set date of a filesystem object
1652 success = TIOSetFileDate(TIOBase, name, date, tags)
1653 TBOOL TAPTR TSTRPTR TDATE* TTAGITEM*
1655 success = TSetFileDate(name, date, tags)
1656 TBOOL TSTRPTR TDATE* TTAGITEM*
1659 This functions sets the date of the specified filesystem
1660 object. The return value will be TTRUE if the operation
1661 succeeded, otherwise TFALSE. Additional error diagnostics
1662 can be obtained with TGetIOErr().
1665 - {{name}} - Name of the object to modify
1668 - {{success}} - Boolean
1671 TExamine(), time:TMakeDate()