RAD Studio
ContentsIndex
PreviousUpNext
io.h

The following functions, macros, and classes are provided in io.h:

Name 
Description 
Header File
io.h
Category
Directory Control Routines
Prototype
int _findclose(long handle);
Description
Closes the specified search handle and releases associated resources associated with previous calls to findfirst/findnext. The handle parameter is the search handle returned by the previous call to _findfirst.
This function is provided for Microsoft compatibility.
Return Value
On success, returns 0.
Otherwise, returns –1 and sets errno to:
ENOENTFile specification that could not be matched
Portability  
Header File
io.h, wchar.h
Category
Directory Control Routines
Prototype
long _findfirst(char *filter, struct _finddata_t *fileinfo);
long __wfindfirst(wchar_t *filter, struct _wfinddata_t *fileinfo);
Description
Begins a search of a disk directory to find information about the first instance of a filename that matches a specified filter. The filter parameter is a string that specifies which files to return. Wildcards may be used in the filter. The fileinfo parameter is the file information buffer. If a matching file is found, the fileinfo structure is filled with the file-directory information.
These functions are provided for Microsoft compatibility.
Return Value
On success, returns a unique... more 
Header File
io.h, wchar.h
Category
Directory Control Routines
Prototype
long _findfirsti64(char *filter, struct _finddatai64_t *fileinfo);
long _wfindfirsti64(wchar_t *filter, struct _wfinddatai64_t *fileinfo);
Description
Begins a search of a disk directory to find information about the first instance of a filename that matches a specified filter. The filter parameter is a string that specifies which files to return. Wildcards may be used in the filter. The fileinfo parameter is the file information buffer. If a matching file is found, the fileinfo structure is filled with the file-directory information.
These i64 versions are for 64 bit filesize use and are provided for Microsoft... more 
Header File
io.h, wchar.h
Category
Directory Control Routines
Prototype
long _findnext(long handle, struct _finddata_t *fileinfo);
long __wfindnext(long handle, struct _wfinddata_t *fileinfo);
Description
Finds subsequent files, if any, that match the filter argument in a previous call to _findfirst/__wfindfirst. Then, _findnext/__wfindnext updates the fileinfo structure with the necessary information for continuing the search. One file name for each call to _tfindnext is returned until no more files are found in the directory matching the pathname (filter).
The handle parameter is the search handle returned by a previous call to _findfirst. The fileinfo parameter is the file information buffer.
These functions are... more 
Header File
io.h, wchar.h
Category
Directory Control Routines
Prototype
long _findnexti64(long handle, struct _finddatai64_t *fileinfo);
__int64 _wfindnexti64(long handle, struct _wfinddata_t *fileinfo);
Description
Finds subsequent files, if any, that match the filter argument in a previous call to _findfirsti64/_wfindfirsti64. Then, _findnexti64/_wfindnexti64 updates the fileinfo structure with the necessary information for continuing the search. One file name for each call to _tfindnext is returned until no more files are found in the directory matching the pathname (filter).
The handle parameter is the search handle returned by a previous call to _findfirst. The fileinfo parameter is the file information buffer.
These i64 versions... more 
Header File
io.h
Category
Input/output Routines
Prototype
long _get_osfhandle(int filehandle);
Description
Associates file handles.
The _get_osfhandle function associates an operating system file handle with an existing runtime file handle. The variable filehandle is the file handle of your program.
Return value
On success, _get_osfhandle returns an operating system file handle corresponding to the variable filehandle.
On error, the function returns -1 and sets the global variable errno to  
Header File
io.h
Category
Input/output Routines
Prototype
int _open_osfhandle(long osfhandle, int flags);
Description
Associates file handles.
The _open_osfhandle function allocates a runtime file handle and sets it to point to the operating system file handle specified by osfhandle.
The value flags is a bitwise OR combination of one or more of the following manifest constants (defined in fcntl.h):  
Header File
stdio.h
Category
Input/output Routines, Process Control Routines
Prototype
int _pclose(FILE * stream);
Description
Waits for piped command to complete.
_pclose closes a pipe stream created by a previous call to _popen, and then waits for the associated child command to complete.
Return Value
On success, _pclose returns the termination status of the child command. This is the same value as the termination status returned by cwait, except that the high and low order bytes of the low word are swapped.
On error, it returns -1.
Portability  
Header File
io.h
Category
Input/output Routines
Prototype
int _rtl_chmod(const char *path, int func [, int attrib]);
int _wrtl_chmod(const wchar_t *path, int func, ... );
Description
Gets or sets file attributes.
Note: The _rtl_chmod function replaces _chmod
which is obsolete_rtl_chmod can either fetch or set file attributes. If func is 0, _rtl_chmod returns the current attributes for the file. If func is 1, the attribute is set to attrib.
attrib can be one of the following symbolic constants (defined in dos.h):  
Header File
io.h
Category
Input/output Routines
Prototype
int _rtl_close(int handle);
Description
Closes a file.
Note: This function replaces _close which is obsolete
The _rtl_close function closes the file associated with handle, a file handle obtained from a call to creat, creatnew, creattemp, dup, dup2, open, _rtl_creat, or _rtl_open.
It does not write a Ctrl-Z character at the end of the file. If you want to terminate the file with a Ctrl-Z, you must explicitly output one.
Return Value
On success, _rtl_close returns 0.
On error (if it fails because handle is not the handle of a valid, open file), _rtl_close... more 
Header File
io.h
Category
Input/output Routines
Prototype
int _rtl_creat(const char *path, int attrib);
int _wrtl_creat(const wchar_t *path, int attrib);
Description
Creates a new file or overwrites an existing one.
Note: The _rtl_creat function replaces _creat,
which is obsolete_rtl_creat opens the file specified by path. The file is always opened in binary mode. Upon successful file creation, the file pointer is set to the beginning of the file. The file is opened for both reading and writing.
If the file already exists its size is reset to 0. (This is essentially the same as deleting the file and creating a new... more 
Header File
io.h
Category
Input/output Routines
Prototype
int _rtl_open(const char *filename, int oflags);
int _wrtl_open(const wchar_t *path, int oflags);
Description
Opens a file for reading or writing.
Note: The _rtl_open function replaces _open which is obsolete.
_rtl_open opens the file specified by filename, then prepares it for reading or writing, as determined by the value of oflags. The file is always opened in binary mode.
oflags uses the flags from the following two lists. Only one flag from List 1 can be used (and one must be used) and the flags in List 2 can be used in any logical... more 
Header File
io.h
Category
Input/output Routines
Prototype
int _rtl_read(int handle, void *buf, unsigned len);
Description
Reads from file.
Note: This function replaces _read which is obsolete.
This function reads len bytes from the file associated with handle into the buffer pointed to by buf. When a file is opened in text mode, _rtl_read does not remove carriage returns.
The argument handle is a file handle obtained from a creat, open, dup, or dup2 call.
On disk files, _rtl_read begins reading at the current file pointer. When the reading is complete, it increments the file pointer by the number of bytes... more 
Header File
io.h
Category
Input/output Routines
Prototype
int _rtl_write(int handle, void *buf, unsigned len);
Description
Writes to a file.
Note: This function replaces _write which is obsolete.
_rtl_write attempts to write len bytes from the buffer pointed to by buf to the file associated with handle.
The maximum number of bytes that _rtl_write can write is UINT_MAX -1 (because UINT_MAX is the same as -1), which is the error return indicator for _rtl_write. UINT_MAX is defined in limits.h. _rtl_write does not translate a linefeed character (LF) to a CR/LF pair because all its files are binary files.
If the number... more 
Header File
stdio.h
Category
Memory and String Manipulation Routines
Syntax
int _snprintf(char* buffer, size_t nsize, const char* format, ...);
int _snwprintf(wchar_t* buffer, size_t nsize, const wchar_t* format, ...);
Description
Sends formatted output to a string of a maximum length specified by nsize. _snprintf and _snwprintf are Microsoft compatible with the _snprintf and _snprintfw functions, respectively.
If the number of bytes to output is:
  • < nsize, then all of the characters have been written, including the terminating ‘\0’ character.
  • == nsize, then nsize characters are written with no terminating ‘\0’ character.
If nsize is 0, then the string will not be... more 
Header File
io.h
Category
Input/output Routines
Prototype
int access(const char *filename, int amode);
int _waccess(const wchar_t *filename, int amode);
Description
Determines accessibility of a file.
access checks the file named by filename to determine if it exists, and whether it can be read, written to, or executed.
The list of amode values is as follows:  
Header File
io.h
Category
Input/output Routines
Prototype
int chmod(const char *path, int amode);
int _wchmod(const wchar_t *path, int amode);
Description
Changes file access mode.
chmod sets the file-access permissions of the file given by path according to the mask given by amode. path points to a string.
amode can contain one or both of the symbolic constants S_IWRITE and S_IREAD (defined in sys\stat.h).  
Header File
io.h
Category
Input/output Routines
Prototype
int chsize(int handle, long size);
Description
Changes the file size.
chsize changes the size of the file associated with handle. It can truncate or extend the file, depending on the value of size compared to the file's original size.
The mode in which you open the file must allow writing.
If chsize extends the file, it will append null characters (\0). If it truncates the file, all data beyond the new end-of-file indicator is lost.
Return Value
On success, chsize returns 0. On failure, it returns -1 and the global variable errno is... more 
Header File
io.h
Category
Input/output Routines
Prototype
int close(int handle);
Description
Closes a file.
The close function closes the file associated with handle, a file handle obtained from a call to creat, creatnew, creattemp, dup, dup2, open, _rtl_creat, or _rtl_open.
It does not write a Ctrl-Z character at the end of the file. If you want to terminate the file with a Ctrl-Z, you must explicitly output one.
Return Value
Upon successful completion, close returns 0.
On error (if it fails because handle is not the handle of a valid, open file), close returns a value of -1 and the... more 
Header File
io.h
Category
Input/output Routines
Prototype
int creat(const char *path, int amode);
int _wcreat(const wchar_t *path, int amode);
Description
Creates a new file or overwrites an existing one.
Note: Remember that a backslash in a path requires '\\'.
creat creates a new file or prepares to rewrite an existing file given by path. amode applies only to newly created files.
A file created with creat is always created in the translation mode specified by the global variable _fmode (O_TEXT or O_BINARY).
If the file exists and the write attribute is set, creat truncates the file to a length of... more 
Header File
io.h
Category
Input/output Routines
Prototype
int creatnew(const char *path, int mode);
Description
Creates a new file.
creatnew is identical to _rtl_creat with one exception: If the file exists, creatnew returns an error and leaves the file untouched.
The mode argument to creatnew can be zero or an OR-combination of any one of the following constants (defined in dos.h):  
Header File
io.h
Category
Input/output Routines
Prototype
int creattemp(char *path, int attrib);
Description
Creates a unique file in the directory associated with the path name.
A file created with creattemp is always created in the translation mode specified by the global variable _fmode (O_TEXT or O_BINARY).
path is a path name ending with a backslash (\). A unique file name is selected in the directory given by path. The newly created file name is stored in the path string supplied. path should be long enough to hold the resulting file name. The file is not automatically deleted when the program... more 
dup 
Header File
io.h
Category
Input/output Routines
Prototype
int dup(int handle);
Description
Duplicates a file handle.
  • dup creates a new file handle that has the following in common with the original file handle:
  • Same open file or device
  • Same file pointer (that is, changing the file pointer of one changes the other)
  • Same access mode (read, write, read/write)
handle is a file handle obtained from a call to creat, open, dup, dup2, _rtl_creat, or _rtl_open.
Return Value
Upon successful completion, dup returns the new file handle, a nonnegative integer; otherwise, dup returns -1.
In the event of error, the global variable... more 
dup2 
Header File
io.h
Category
Input/output Routines
Prototype
int dup2(int oldhandle, int newhandle);
Description
Duplicates a file handle (oldhandle) onto an existing file handle (newhandle).
  • dup2 creates a new file handle that has the following in common with the original file handle:
  • Same open file or device
  • Same file pointer (that is, changing the file pointer of one changes the other)
  • Same access mode (read, write, read/write)
dup2 creates a new handle with the value of newhandle. If the file associated with newhandle is open when dup2 is called, the file is closed.
newhandle and oldhandle are file handles obtained from... more 
eof 
Header File
io.h
Category
Input/output Routines
Prototype
int eof(int handle);
Description
Checks for end-of-file.
eof determines whether the file associated with handle has reached end-of-file.
Return Value
If the current position is end-of-file, eof returns the value 1; otherwise, it returns 0. A return value of -1 indicates an error; the global variable errno is set to  
Header File
io.h
Category
Input/output Routines
Prototype
long filelength(int handle);
Description
Gets file size in bytes.
filelength returns the length (in bytes) of the file associated with handle.
Return Value
On success filelength returns a long value the file length in bytes. On error it returns -1 and the global variable errno is set to  
Header File
stdio.h
Category
Input/output Routines
Prototype
int _fileno(FILE *stream);
Description
Gets the file handle.
_fileno is a macro that returns the file handle for the given stream. If stream has more than one handle _fileno returns the handle assigned to the stream when it was first opened.
Return Value
_fileno returns the integer file handle associated with stream.
Example  
Header File
io.h
Category
Input/output Routines
Prototype
int getftime(int handle, struct ftime *ftimep);
int setftime(int handle, struct ftime *ftimep);
Description
Gets and sets the file date and time.
getftime retrieves the file time and date for the disk file associated with the open handle. The ftime structure pointed to by ftimep is filled in with the file's time and date.
setftime sets the file date and time of the disk file associated with the open handle to the date and time in the ftime structure pointed to by ftimep. The file must not be written to after the setftime call... more 
Header File
io.h
Category
Input/output Routines
Prototype
int isatty(int handle);
Description
Checks for device type.
isatty determines whether handle is associated with any one of the following character devices:
  • a terminal
  • a console
  • a printer
  • a serial port
Return Value
If the device is one of the four character devices listed above, isatty returns a nonzero integer. If it is not such a device, isatty returns 0.
Example  
lock 
Header File
io.h
Category
Input/output Routines
Prototype
int lock(int handle, long offset, long length);
Description
Sets file-sharing locks.
lock provides an interface to the operating system file-sharing mechanism.
A lock can be placed on arbitrary, nonoverlapping regions of any file. A program attempting to read or write into a locked region will retry the operation three times. If all three retries fail, the call fails with an error.
Return Value
lock returns 0 on success. On error, lock returns -1 and sets the global variable errno to  
Header File
io.h, sys\locking.h
Category
Input/output Routines
Prototype
int locking(int handle, int cmd, long length);
Description
Sets or resets file-sharing locks.
locking provides an interface to the operating system file-sharing mechanism. The file to be locked or unlocked is the open file specified by handle. The region to be locked or unlocked starts at the current file position, and is length bytes long.
Locks can be placed on arbitrary, nonoverlapping regions of any file. A program attempting to read or write into a locked region will retry the operation three times. If all three retries fail, the call fails with... more 
Header File
io.h
Category
Input/output Routines
Prototype
long lseek(int handle, long offset, int fromwhere);
Description
Moves file pointer.
lseek sets the file pointer associated with handle to a new position offset bytes beyond the file location given by fromwhere. fromwhere must be one of the following symbolic constants (defined in io.h):  
read 
Header File
io.h
Category
Input/output Routines
Prototype
int read(int handle, void *buf, unsigned len);
Description
Reads from file.
read attempts to read len bytes from the file associated with handle into the buffer pointed to by buf.
For a file opened in text mode, read removes carriage returns and reports end-of-file when it reaches a Ctrl-Z.
The file handle handle is obtained from a creat, open, dup, or dup2 call.
On disk files, read begins reading at the current file pointer. When the reading is complete, it increments the file pointer by the number of bytes read. On devices, the... more 
Header File
io.h
Category
Input/output Routines
Prototype
int setmode(int handle, int amode);
Description
Sets mode of an open file.
setmode sets the mode of the open file associated with handle to either binary or text. The argument amode must have a value of either O_BINARY or O_TEXT, never both. (These symbolic constants are defined in fcntl.h.)
Return Value
setmode returns the previous translation mode if successful. On error it returns -1 and sets the global variable errno to  
tell 
Header File
io.h
Category
Input/output Routines
Prototype
long tell(int handle);
Description
Gets the current position of a file pointer.
tell gets the current position of the file pointer associated with handle and expresses it as the number of bytes from the beginning of the file.
Return Value
tell returns the current file pointer position. A return of -1 (long) indicates an error, and the global variable errno is set to  
Header File
io.h, sys\stat.h
Category
Input/output Routines
Prototype
unsigned umask(unsigned mode);
Description
Sets file read/write permission mask.
The umask function sets the access permission mask used by open and creat. Bits that are set in mode will be cleared in the access permission of files subsequently created by open and creat.
The mode can have one of the following values, defined in sys\stat.h:  
Header File
io.h
Category
Input/output Routines
Prototype
int unlock(int handle, long offset, long length);
Description
Releases file-sharing locks.
unlock provides an interface to the operating system file-sharing mechanism. unlock removes a lock previously placed with a call to lock. To avoid error, all locks must be removed before a file is closed. A program must release all locks before completing.
Return Value
On success, unlock returns 0
O error, it returns -1.
Example  
Header File
io.h
Category
Memory and String Manipulation Routines
Prototype
int vsscanf(const char *buffer, const char *format, va_list arglist);
Description
Scans and formats input from a stream.
The v...scanf functions are known as alternate entry points for the ...scanf functions. They behave exactly like their ...scanf counterparts, but they accept a pointer to a list of arguments instead of an argument list.
Note: For details on format specifiers, see Scanf Format Specifiers.
vsscanf scans a series of input fields, one character at a time, reading from a stream. Then each field is formatted according to a format specifier passed to... more 
Header File
io.h
Category
Input/output Routines
Prototype
int write(int handle, void *buf, unsigned len);
Description
Writes to a file.
write writes a buffer of data to the file or device named by the given handle. handle is a file handle obtained from a creat, open, dup, or dup2 call.
This function attempts to write len bytes from the buffer pointed to by buf to the file associated with handle. Except when write is used to write to a text file, the number of bytes written to the file will be no more than the number requested. The maximum number of... more 
Copyright(C) 2008 CodeGear(TM). All Rights Reserved.
What do you think about this topic? Send feedback!