digitalmars.com                      
Last update Sun Mar 4 12:00:58 2018

io.h

_access

Header
io.h
errno.h
Prototype
int _access(char *path, int mode);
Description
_access determines whether the file or directory specified by path exists and can be accessed in the file mode specified by mode. Values for mode can be one or more of the following OR'ed together:

F_OK or 0 Check for existence
X_OK or 1 Check for execute permission
W_OK or 2 Check for write permission
R_OK or 4 Check for read permission
With directories, _access determines only whether the specified directory exists; in DOS, all directories have read and write access.
Synonym
Function: access
Return Value
Returns 0 if the file exists and can be accessed in mode. A return value of -1 means that the file does not exist or cannot be accessed in mode, and errno is set to one of the following:

EACCES Access denied
ENOENT File or path name not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_chmod _fstat _open _stat
Example
/* Example for _access */

#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 char search[32];

 printf("Enter a file name: ");
 scanf("%s", search);

 /* Check for existence only */

 if ((_access(search, 0)) == -1)

   /* if access is unsuccessful,
      errno is set */
   perror("ERROR accessing file");

 else
    printf("File '%s' found.\n", search);
}
Output
If the file does not exist: 
Enter a file name: temp.dat
ERROR accessing file: No such file or directory
If the file does exist: 
Enter a file name: temp.dat
File 'temp.dat' found.

_chmod

Header
io.h
errno.h
sys\stat.h
sys\types
Prototype
int _chmod (const char *pathname, int pmode);
Description
_chmod changes the permission on a file, specified by pathname, to the permissions specified by pmode. The user must have write permission for the file. The following values are valid for pmode:
_S_IREAD Read permission
_S_IWRITE Write permission (implies file can be deleted)
You can also logically OR the values indicate read and write access by specifying _S_IREAD | _S_IWRITE. However, because all files are always readable, the modes _S_IWRITE and _S_IREAD | _S_IWRITE are equivalent.
Synonym
Function: chmod
Modes: S_IREAD, S_IWRITE
Return Value
0 if successful. Otherwise -1, and errno is set to ENOENT, and _doserror is set to the OS error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for _chmod */

#include <fcntl.h>
#include <io.h>
#include <sys\stat.h>
#include <stdio.h>
#include <stdlib.h>

char *pathname = "temp.dat";

void main()
{
 int result;

 result = _chmod(pathname, S_IREAD| S_IWRITE);

 if (result == 0)
    printf("Permission on file %s changed\n",
           pathname);
 else
    perror("Can't change file");
}
Output
Permission on file temp changed
or 
Can't change file: No such file or directory

_chsize

Header
io.h
errno
Prototype
int _chsize(int handle, long size);
Description
The _chsize function truncates or extends an open file. The argument handle is the handle of the file to truncate or extend and size is the new length of the file, in bytes. If the specified size is shorter than the existing file, the file will be truncated. If the specified size is longer than the existing file, the file will be extended and null characters ('\0') are appended.
Synonym
Function: chsize
Return Value
0 if successful. A return value of -1 indicates an error and _chsize sets errno to one of the following values:
EACCESS Specified file is locked against access.
EBADF Specified file is read-only or an invalid file handle.
ENOSPC No space is left on device.
See Also
filesize _filelength
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for _chsize
   Also demonstrates _open, fopen
*/
#include <dos.h>
#include <fcntl.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int fd;
 FILE *fp;
 char *fname[2] = {" file1"," file2"};
 long sizes[2] = {10000l, 20000l};

 fd = _open(fname[0], O_CREAT| O_WRONLY);
 if (fd == -1)
    perror("No fd");
 fp = fopen(fname[1]," wb");

 _chsize(fd, sizes[0]);
 _chsize(fileno(fp), sizes[1]);
}
Output
This program creates two files of the given size in the directory from
which it is run.

_close

Header
io.h
errno.h
Prototype
int _close(int handle);
Description
The _close function closes the file associated with file descriptor handle handle, freeing the file descriptor for use by another file. _close does not write a Ctrl-Z (EOF) character at the end of file.
Synonym
Function: close
Return Value
0 if successful. Otherwise, -1 and errno is set to EBADF, to indicate an invalid file-handle argument, and _doserrno is set to the OS error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_creat _open _unlink
Example
/* Example for _close and _open */

#include <dos.h>
#include <fcntl.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int fd, result;

 fd = _open("temp.dat", O_CREAT);
 if (fd < 0)
 {
    perror("Can't create temp.dat");
 }
 else
 {
    printf("Created temp.dat\n");
    result = _close(fd);
    printf("Close() result code is %d\n",
           result);
 }

}
Output
Created temp.dat
Close() result code is 0

_commit

Header
io.h
errno.h
Prototype
int _commit(int handle);
Description
The _commit function forces the operating system to write the file indicated by handle to disk. This function causes the file to be flushed immediately.
Return Value
Returns 0 if the file is successfully flushed to disk. Otherwise, returns -1, errno is set to EBADF, indicating an invalid handle argument, and _doserrno is set to the OS error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_creat _open _read _write
Example
/* Example for _commit */

#include <fcntl.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int fd, result;
 char *buf = "Hello from Digital Mars";

 fd = open("temp.dat", (O_CREAT| O_RDWR));
 write(fd, buf, 20);

 result = _commit(fd);

 if (result == 0)
    printf("Buffer successfully flushed to disk\n");
 else
    perror("ERROR flushing buffer");
}
Output
This program overwrites the contents of file temp.dat with the string: 
"Hello from Digital Mars".

_creat

Header
io.h
errno.h
sys\stat.h
sys\types.h
Prototype
int _creat(const char *name, int pmode);
Description
The _creat function can either create a new file or open and truncate an existing file. The permission setting, pmode, sets the new file's read, write, and execute permission after the file is closed for the first time. pmode values, defined in stat.h are:
_S_IREAD Read permission, owner
_S_IWRITE Write permission, owner
To specify both read and write, logically OR the values (_S_IREAD | _S_IWRITE). Note that _creat can open the file with read/ write permission regardless of the setting of pmode. The pmode takes effect only after the file has been closed for the first time. MS-DOS does not allow write-only permission. Therefore, modes _S_IWRITE and _S_IREAD | _S_IWRITE are equivalent.
Synonym
Function: creat
Modes: S_IREAD, S_IWRITE
Return Value
The file handle for the new file. If unsuccessful, returns -1 and sets errno, defined in errno.h, to one of the following:
EACCES Permission to access the file or a directory on the path has been denied.
EAGAIN The specified file exists, and has a locking or sharing violation.
EMFILE Too many open files.
ENOENT The file or path name can not be found.
_doserrno is set to the OS error code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
dos_creat _close fopen _open
Example
/* Example for _creat */

#include <io.h>
#include <sys\stat.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int fp;

 fp = _creat("file.dat", S_IREAD|S_IWRITE);

 if (fp == -1)
   printf("Cannot create file.dat\n");
 else
   printf("File.dat successfully created\n");
}
Output
File.dat successfully created

_dup

Header
io.h
Prototype
int _dup(int fd);
Description
The _dup function allows a second file handle to be associated with a currently open file. Once associated, any of the file handles can be used to carry out operations on the file. The access mode for the file is unchanged by the assignment of a new file handle.

The function causes a new file handle to be returned and associated with the file connected to the handle in the fd argument.

This function differs slightly from the _dup2 function.

Synonym
Function: dup
Return Value
Returns the new file handle. If unsuccessful returns -1 if and sets errno to EBADF (invalid file handle) or EMFILE (no more file handles available.)
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_close _creat _dup2 _open
Example
/* Example for _dup, _dup2 */

#include <dos.h>
#include <fcntl.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int file1, file2, file3;
 int result;

 _dos_open("temp.dat", _O_CREAT|_O_RDWR,
           &file1);

 _dos_write(file1, "This is an example. ", 21,
            &result);

 file2 = _dup(file1);
 _dup2(file1, file3);

 _dos_write(file1, "This is example 2. ", 20,
            &result);
 _dos_write(file1, "This is example 3. ", 20,
            &result);
 _dos_close(file1);
}
Output
This program produces no screen output. It writes the following string to the file temp.dat: 
This is an example. This is example 2. This is example 3.

_dup2

Header
io.h
Prototype
int dup2 (int fdl, int fd2);
Description
The _dup2 function is like the _dup function except that it causes the file handle in the fd2 argument to be associated with the file connected to the handle in the fd1 argument.
Synonym
Function: dup2
Return Value
Returns 0. If unsuccessful, returns -1 and sets errno to EBADF (invalid file handle) or EMFILE (no more file handles available.)
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_dup

_eof

Header
io.h
Prototype
int _eof(int handle);
Description
The _eof function determines if the end of the file associated with the handle argument has been reached.
Synonym
Function: eof
Return Value
Returns 1 if the current position is end-of-file; returns 0 if the current position is elsewhere. If an error occurs, -1 is returned and errno is set to EBADF (invalid file handle).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
clearerr feof ferror perror
Example
/* Example for _eof
   Also demonstrates _dos_open, _dos_read
*/
#include <dos.h>
#include <fcntl.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 int handle, count, total = 0;
 int result;
 char buf[10];

 result = _dos_open("temp.dat", _O_RDONLY,
                    &handle);
 if (result == 0)
 {
    while (!(_eof(handle)))
    {
       count = read (handle, buf, 10);
       if (count !=- 1)
            total += count;
    }

    printf("Number of bytes read = %d\n", total);
    _dos_close(handle);
 }
 else
    perror("Error opening file");
}
Output
Number of bytes read = 61

_filelength

Header
io.h
Prototype
long _filelength(int fd);
Description
The _filelength function returns the length in bytes of the file associated with the file descriptor fd. The fd argument must point to a file which is already open. The _filelength function differs from filesize in that it is used on a file that is already open.
Synonym
Function: filelength
Return Value
The length of the file in bytes as a long integer. The current read/ write position within the file is unaltered. In addition, if there is an error, these functions return a value of -1 and set errno to EBADF.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
filesize
Example
/* Example for _filelength() */

#include <stdio.h>
#include <stdlib.h>
#include <io.h>
#include <fcntl.h>

void main ()
{
 int fh;
 char fname[_MAX_PATH];
 long len;

 printf("Enter filename: ");
 gets(fname);

 fh = _open(fname, _O_RDONLY);
 if (fh < 0)
 {
    perror("Error opening file");
    exit(EXIT_FAILURE);
 }

 len = _filelength(fh);
 printf("The file length is %ld bytes\n",
        len);
 _close(fh);
}
Output
Enter filename: _filelen.c
The file length is 469 bytes

_isatty

Header
io.h
Prototype
int _isatty(int fd);
Description
The _isatty function determines if the handle fd is associated with a character device such as a terminal, printer, or a serial port.
Synonym
Function: isatty
Return Value
Returns a non-zero value if the device is a character device or a zero if it is not.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_fstat
Example
/* Example for _isatty

   _ISATTY.C
*/

#include <stdio.h>
#include <io.h>

void main ()
{
 if (_isatty(fileno(stdin)))
    printf("stdin is connected to the keyboard\n");
 else
    printf("stdin is connected to a file\n");
}
Output
c:\dm\examples>_isatty
stdin is connected to the keyboard

c:\dm\examples>_isatty <_isatty.c
stdin is connected to a file

_locking

Header
sys\locking.h
io.h
Prototype
int _locking(int fd, int mode, long size);
Description
The _locking function locks or unlocks a section of the file associated with file handle fd. This operation locks records in files that are shared by multiple applications in a multi-tasking or network environment. Locking a section of the file prevents other applications from reading or writing that section while it is being updated. The section is then unlocked to allow other applications to read and write to it. The file is locked from the current position of the file pointer for the next size bytes. The mode argument specifies which locking functions to apply:

Value Description
_LK_LOCK, _LK_RLCK Locks the specified number of bytes. If they cannot be locked it will retry after 1 second. This is repeated until 10 attempts have failed, at which point the function will return an error.
_LK_NBLCK, _LK_NBRLCK Locks the specified number of bytes. If they cannot be locked, returns an error.
_LK_UNLCK Unlocks the specified number of bytes. The file pointer and size must have exactly the same values as when the section was locked.
Multiple regions of a file can be locked, but no regions may overlap. A call to locking, unlocks no more than one region. To use locking, share. exe must be loaded.
Synonym
Function: locking
Return Value
Returns 0 if successful. If an error occurs, returns -1 and errno is set to one of the following values:

Value Meaning
EACCES Locking violation (file already locked or unlocked)
EBADF Invalid file handle
EDEADLOCK Locking violation. Returned when _LK_LOCK or _LK_RLCK is specified and file cannot be locked after 10 attempts
EINVAL Invalid argument to function
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
lock
Example
/* Example of _locking /*

#include <dos.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys\locking.h>
#include <sys\types.h>
#include <fcntl.h>

void main ()
{
 int fd;

 fd = _open("temp.fil",_O_RDONLY);
 if (fd == -1)
 {
    perror("Error opening file");
    exit(EXIT_FAILURE);
 }
 _lseek (fd, 0L, SEEK_SET);
 if ((_locking(fd,_LK_NBLCK, 20L)) == -1)
 {
    perror("Locking operation failed");
    exit(EXIT_FAILURE);
 }
 else
 {
    printf("Locking operation successful\n");
    _lseek(fd, 0L, SEEK_SET);
    _locking(fd, _LK_UNLCK, 20L);
 }
 close(fd);
}
Output
Locking operation successful

_lseek

Header
io.h
Prototype
long _lseek(int fd, long offset, int mode);
Description
The _lseek function moves the read/ write pointer for a file given by file descriptor fd. The pointer is moved offset bytes from the position indicated by mode. Values for mode are:
Macro Description
SEEK_SET Beginning of the file.
SEEK_CUR Current location.
SEEK_END End of the file.
Synonym
Function: lseek
Return Value
Returns the offset in bytes of the new position from the beginning of the file. A -1L is returned on error, and errno is set to EBADF or EINVAL.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
fseek
Example
/* Example of _lseek */

#include <io.h>
#include <dos.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>

void main ()
{
 int fp;
 long offset, lpos;

 fp = _open("\\dm\\include\\io.h", _O_RDONLY);
 if (fp < 0)
    perror("Error opening file");
 else
 {
    offset = 35L;
    lpos = _lseek(fp, offset, SEEK_SET);
    printf("Position of seek = %ld\n", lpos);
    offset = 10L;
    lpos = _lseek(fp, offset, SEEK_CUR);
    printf("Position of seek = %ld\n", lpos);
    offset = 0L;
    lpos = _lseek(fp, offset, SEEK_END);
    printf("Position of seek = %ld\n", lpos);
    close (fp);
 }
}
Output
Position of seek = 35
Position of seek = 45
Position of seek = 2759

_mktemp

Header
io.h
Prototype
char *_mktemp(char *template);
Description
The _mktemp function generates unique filenames from the template specified in the template argument. The argument has the following form:

baseXXXXXX

The base is the part of the filename that you supply; the X's are placeholders for the part that _mktemp generates. The generated filename contains an alphanumeric character, followed by a 5-digit value that identifies the calling process. The first time _mktemp is called with a given template, the function selects 0 as the first alphanumeric character. In subsequent calls, the function uses the lowercase letters 'a' through 'z'.

The _mktemp does not create or open files.

Synonym
Function: mktemp
Return Value
These functions return a pointer to the modified template. The return value is NULL if the template is specified incorrectly or if no more unique names can be created from the given template.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
fopen _getpid _open _tempnam tmpfile
Example
/* Example of _mktemp */

#include <io.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

void main ()
{
 char template[] = "tzXXXXXX";
 char names[27][sizeof(template)];
 char *result;
 int i;
 FILE *fp;

 for (i = 0; i < sizeof(names)/sizeof(names[0]); i++)
 {
    strcpy(names[i], template);
    result = _mktemp(names[i]);
    printf("mktemp [%2d] = \"%s\"\n",
           i, result);
    fp = fopen(result, "w");
    if (fp == NULL)
    {
      printf("unable to create file \"%s\"\n",
             result);
      exit(EXIT_FAILURE);
    }
    fclose(fp);
 }
}
Output
mktemp [0] = "tz008437"
mktemp [1] = "tza08437"
mktemp [2] = "tzb08437"
mktemp [3] = "tzc08437"
mktemp [4] = "tzd08437"
mktemp [5] = "tze08437"
mktemp [6] = "tzf08437"
mktemp [7] = "tzg08437"
mktemp [8] = "tzh08437"
mktemp [9] = "tzi08437"
mktemp [10] = "tzj08437"
mktemp [11] = "tzk08437"
mktemp [12] = "tzl08437"
mktemp [13] = "tzm08437"
mktemp [14] = "tzn08437"
mktemp [15] = "tzo08437"
mktemp [16] = "tzp08437"
mktemp [17] = "tzq08437"
mktemp [18] = "tzr08437"
mktemp [19] = "tzs08437"
mktemp [20] = "tzt08437"
mktemp [21] = "tzu08437"
mktemp [22] = "tzv08437"
mktemp [23] = "tzw08437"
mktemp [24] = "tzx08437"
mktemp [25] = "tzy08437"
mktemp [26] = "tzz08437"

_open

Header
io.h
fcntl.h
sys\stat.h (for creating a file)
sys\types.h
Prototype
int _open(const char *file, int oflag[, int pmode]);
Description
These functions open a file for reading, writing, or appending. The *file argument is the name of the file to open.

Argument oflag specifies the operation allowed. It can be one or more of the following flags OR'ed together:

Flag Operation Performed
_O_APPEND Position file pointer to end
_O_BINARY Open file in binary mode
_O_CREAT Create file if it does not exist
_O_EXCL Used with O_CREAT, returns an error if file exists
_O_RDONLY Open file for reading only
_O_RDWR Open file for reading and writing
_O_TEXT Open file in text mode
_O_TRUNC Truncates existing file
_O_WRONLY Opens file for writing only
The pmode argument, which signifies permission mode, is required only when you are creating a file by specifying the flag O_CREAT or _O_CREAT. If you do not indicate permission mode, the open function might pull random values from the stack. If the file specified in the file argument exists (you are not creating a new file), the pmode argument is ignored. The pmode argument can be one or more of the following flags OR'ed together:

Flag Permission
_S_IWRITE Permit writing
_S_IREAD Permit reading
The pmode flags are found in the sys\stat.h file.
Synonym
Function: open
Flags: O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY, S_IWRITE, S_IREAD
Return Value
Both functions return a file handle for the opened file. If an error occurs, -1 is returned and variable errno is set to one of the following values:

EEXIST File already exists
EINVAL Invalid oflag or pmode argument
EMFILE No more file handles available
ENOENT File or path name not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_close _sopen
Example
/* Example of _open */

#include <dos.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>

void main ()
{
 int fd;
 char fn[_MAX_PATH];
 printf("Enter a filename: ");
 scanf("%s", fn);

 fd = _open(fn, _O_RDONLY);
 if (fd == -1)
 {
   printf("Cannot open file \"%s\"\n", fn);
   exit(EXIT_FAILURE);
 }
 printf("File \"%s\" opened successfully", fn);
 _close(fd);
}
Output
Enter a filename: _open.c
File "_open.c" opened successfully

_read

Header
io.h
Prototype
int _read(int fd, void *buffer, unsigned int len);
Description
The _read function gets the number of bytes specified in len from the file associated with file descriptor fd. The bytes are read into buffer. After the read operation, the pointer points to the next unread byte.
Return Value
Returns the number of characters actually read, which may be less than len if EOF was encountered or if the file was opened in text mode. If an error occurs, -1 is returned and errno is set to EBADF (invalid file handle). Returns 0 if an attempted read occurs at EOF.

If a file is opened in text mode, the return value might not correspond to the number of bytes actually read. In text mode, each carriage-return-line-feed pair is replaced with a single line-feed character. Only the single line-feed character is counted in the return value. Also, in text mode, a CTRL/ Z character is treated as an end-of-file indicator.

Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Synonym
Function: read
See Also
_creat _open _write
Example
/* Example of _read */

#include <stdio.h>
#include <stdlib.h>
#include <dos.h>
#include <io.h>
#include <string.h>
#include <fcntl.h>

#define BUFSIZE 255

void main ()
{
 char buffer[BUFSIZE + 1];
 char fn[_MAX_PATH];
 int fd, numread;

 printf("Enter a filename: ");
 scanf("%s", fn);

 fd = _open(fn, _O_RDONLY);
 if (fd == -1)
 {
    perror("Open failed");
    exit(EXIT_FAILURE);
 }
 memset (buffer, 0, BUFSIZE + 1);
 numread = _read (fd, buffer, BUFSIZE);
 printf("Actual number of characters read was %d\n",
        numread);

 _close (fd);
}
Output
Enter a filename: _read.c
Actual number of characters read was 239

_setmode

Header
fcntl.h
io.h
Prototype
int _setmode(int handle, int mode);
Description
The _setmode function sets the mode for an open file.

The mode argument can be one of the following:

_O_BINARY Binary mode. No character translations.
_O_TEXT Text mode. Carriage-return/line-feed combinations are translated into a single line-feed character on input. Line-feed characters are translated into carriage-return/ line-feed combinations on output.
Synonym
Function: setmode
Return Value
If successful, returns the previous mode. If unsuccessful, returns -1 and set errno to EBADF (invalid file handle) or EINVAL (invalid mode argument).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
fopen _open
Example
/* Example of _setmode */

#include <stdio.h>
#include <io.h>
#include <fcntl.h>

void main ()
{
 int result;
 result = _setmode(_fileno(stdprn), _O_TEXT);
 if (result == -1)
    perror("Error setting mode");
 else
    printf("Printer successfully set to text mode\n");
}
Output
Printer successfully set to text mode

_sopen

Header
io.h
share.h
fcntl.h
sys\types.h
sys\stat.h
Prototype
int _sopen(const char *file, int oflag, int shflag[, int pmode]);
Description
The _sopen function is similar to the standard library _open function; each opens a file. However, _sopen also prepares the file for DOS sharing. The DOS utility SHARE must be installed if files will be opened in shared mode. Attempting to use sopen with DOS 2.x causes an error.

Arguments for _sopen are:

Argument Description
char *file Name of file to open
int oflag Operations allowed
int shflag Type of sharing allowed
int pmode Optional permission mode
The oflag argument can be one or more of the following values, OR'ed together:

Value Description
_O_APPEND Position file pointer to end
_O_BINARY Open file in binary (untranslated) mode
_O_CREAT Create file if it does not exist
_O_EXCL Used with _O_CREAT to return an error if file already exists
_O_RDONLY Open file for reading only
_O_RDWR Open file for reading and writing
_O_TEXT Open file in text (translated) mode
_O_TRUNC Truncate an existing file
_O_WRONLY Open file for writing only
The shflag argument can be one of the following:

Value Description
_SH_COMPAT Set compatibility mode
_SH_DENYRW Deny read and write access
_SH_DENYWR Deny write access
_SH_DENYRD Deny read access
_SH_DENYNO Permit read and write access
The pmode argument is used with _O_CREAT and can be one or both of the following OR'ed together:

Value Description
_S_IWRITE Permit writing
_S_IREAD Permit reading
Synonym
Function: sopen Values: O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TEXT, O_TRUC, O_WRONLY, SH_COMPAT, SH_DENYRW, SH_DENYWR, SH_DENYRD, SH_DENYNO, S_IWRITE, S_IREAD
Return Value
Returns a file handle for the opened file. If an error occurs, -1 is returned and errno is set to one of the following values:

EACCES Access violation
EEXIST File already exists
EINVAL Invalid oflag or pmode argument
EMFILE No more file handles available
ENOENT File or path name not found
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example of _sopen */

#include <dos.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <share.h>

void main()
{
 int fd;
 char fn[_MAX_PATH];

 printf("Enter a filename: ");
 scanf("%s", fn);

 fd = _sopen(fn, _O_RDONLY | _SH_DENYNO, 0);
 if (fd == -1)
 {
    perror("Cannot open file");
    exit(EXIT_FAILURE);
 }
 printf("File opened successfully");
 _close(fd);
}
Output
Enter a filename: _sopen.c
File opened successfully

_tell

Header
io.h
Prototype
long _tell(int handle);
Description
The _tell function returns the current position of the file pointer associated with the handle argument. The position is specified as the number of bytes from the beginning of the file.
Synonym
Function: tell
Return Value
Returns the file pointer position if successful; otherwise returns -1L, and errno is set to EBADF, indicating an invalid file handle.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
ftell
Example
/* Example for _tell */

#include <stdlib.h>
#include <stdio.h>
#include <io.h>
#include <string.h>

void main()
{
 char fname[_MAX_PATH];
 char line[128];
 FILE *fp;
 long offset;

 printf("Enter a filename: ");
 gets(fname);

 fp = fopen(fname, "r");
 if (fp == NULL)
 {
    perror("Unable to open input file");
    exit(EXIT_FAILURE);
 }

 setbuf(fp, NULL);
 fgets(line, 128, fp);

 if (line[strlen(line) - 1] == '\n')
     line[strlen(line) - 1] = '\x00';

 offset = _tell(_fileno(fp));

 printf("After reading the first line in file \"%s\":\n \"%s\"\n",
        fname, line);
 printf("The file pointer is at offset: %d\n",
        offset);

 fclose (fp);
}
Output
Enter a filename: _tell.c
After reading the first line in file "_tell.c":
"/*"
The file pointer is at offset: 4

_write

Header
io.h
Prototype
int _write(int fd, void *buffer, unsigned int length);
Description
This function writes length bytes from buffer to the file specified by file descriptor fd. This binary-only operation is not buffered.

Data is written, starting at the current position of the file pointer associated with the given file. If the file is open for appending, data is written at the end of the file. After the write operation, the file pointer is increased by the number of bytes written.

Synonym
Function: write
Return Value
Returns the number of bytes written. If an error occurs, -1 is returned and errno is set to EBADF (invalid file handle) or ENOSPC (no space left on device).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_read _open
Example
/* Example for _write */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <io.h>
#include <dos.h>
#include <fcntl.h>

void main()
{
 int fh;
 char *str = "Write this data to file";
 char buffer[128];
 int count, nwritten, nread;

 count = strlen(str) + 1;

 fh = _open("file.dat", _O_RDWR | _O_CREAT);

 if (fh < 0)
 {
    perror("Unable to create file: file.dat");
    exit(EXIT_FAILURE);
 }

 printf("Writing string \"%s\" to file...\n",
        str);
 nwritten = _write(fh, str, count);
 printf("%d bytes written\n", nwritten);
 _lseek(fh, 0, SEEK_SET);
 printf("Reading back from file...\n");
 nread = _read(fh, buffer, count);
 printf("%d bytes read from file\nString read is \"%s\"\n",
        nread, buffer);
 _close(fh);
}
Output
Writing string "Write this data to file" to
file...
24 bytes written
Reading back from file...
24 bytes read from file
String read is "Write this data to file"

_umask

Header
io.h
sys\types.h
sys\stat.h
Prototype
unsigned _umask(int mode);
Description
The _umask function sets the file-permission mask for the current process to the mode specified by the mode argument. The permission mask modifies the permission setting of new files created using functions _open, _creat, or _sopen. If a bit in the mask is set to 1, the corresponding bit in the file's requested permission is set to 0. If a bit in the mask is 0, the corresponding bit remains unchanged. For example, if the write bit is set, new files will be read-only.

Values for the mode argument are:

S_IWRITE Write access
S_IREAD Read access
S_IREAD | S_IWRITE Read and write access
Synonym
Function: umask
Return Value
Returns the previous value of the file permission mask.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_chmod _creat _open _sopen
Example
/* Example for _umask */

#include <stdio.h>
#include <stdlib.h>
#include <io.h>
#include <sys\types.h>
#include <sys\stat.h>

void main()
{
 FILE *fp;
 struct _stat statbuf;

 _umask (_S_IWRITE);

 fp = fopen("new.dat", "w");
 if (fp == NULL)
 {
    perror("Error creating file");
    exit(EXIT_FAILURE);
 }
 fclose (fp);

 if (_stat("new.dat", &statbuf) != 0)
 {
    perror("Error calling _stat");
    exit(EXIT_FAILURE);
 }

 if (statbuf.st_mode & _S_IWRITE)
    printf("_umask did not work\n");
 else
    printf("_umask worked\n");
}
Output
_umask worked

_unlink

Header
io.h
stdio.h
Prototype
int _unlink(const char *filename);
Description
The _unlink function deletes the file specified by the string filename.
Return Value
Returns 0 if the file was successfully deleted. Otherwise, returns -1 and sets errno to EACCES (the file is read-only) or ENOENT (file or path not found, or name is a directory).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_close remove
Example
/* Example for remove */

#include <stdio.h>
#include <io.h>
#include <stdlib.h>

void main()
{
 int value;
 char buffer[13];
 char *result;

 printf("Enter file to remove: ");
 result = gets(buffer);
 value = _unlink(result);
 if (value == 0)
    printf("Erased \"%s\" from disk\n",
           result);
 else
 {
    perror("Unable to erase file");
    exit(EXIT_FAILURE);
 }
}
Output
Enter file to remove: delete.me
Erased "delete.me" from disk

filesize

Header
io.h
Prototype
long filesize(const char *filename);
Description
filesize determines the size of a file in bytes. The filename must be an existing file that is not currently open.
Return Value
The length of the file in bytes; otherwise a -1L is returned, errno is set, and _doserrno is set to the OS return code.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_stat _fstat
Example
/* Example for filesize */

#include <io.h>
#include <stdio.h>
#include <stdlib.h>

void main()
{
 long size;

 size = filesize ("c:\\dm\\include\\io.h");
 if (size == -1)
 {
    perror("Couldn't get size of io.h");
    exit(EXIT_FAILURE);
 }
 printf("io.h filesize = %ld\n", size);
}
Output
io.h filesize = 2759

getDS

Header
io.h
Prototype
unsigned short getDS(void);
Description
The getDS function returns the value of the data segment register. In 32-bit memory models, getDS returns the actual value in the DS register which is the protected mode segment selector and not the base address of DGROUP. Use __X386_get_abs_address to find DGROUP.
Return Value
The current value in the data segment register DS.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_segread
Example
/* Example for getDS */

#include <io.h>
#include <stdio.h>

void main()
{
  printf("The data segment is %04X\n",
         getDS());
}
Output
The data segment is 1FE7

getftime

Header
io.h
Prototype
int getftime(int handle, struct ftime *ftimep);
Description
The getftime function gets date and time information for the file associated with the handle argument. The information is copied into the structure pointed to by the ftimep argument. This structure, which is of type ftime and is defined in io.h, is described in the setftime function.
Return Value
When the function is successful, zero is returned. If an error occurs, -1 is returned and errno is set to EINVFNC (invalid function number) or EBADF (bad file number).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
setftime

lock

Header
io.h
Prototype
int lock(int handle, long offset, long length);
Description
This function provides an interface to DOS file-sharing. Argument handle specifies a file handle, offset indicates the offset, and length indicates the file length. To use lock, share. exe must be loaded and DOS 3.x or higher must be running.
Return Value
Returns 0. If unsuccessful, returns -1 and sets errno to EACCES.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
unlock

remove

Header
io.h
stdio.h
Prototype
int remove(const char *filename);
Description
remove deletes the file specified by the string filename.
Return Value
Returns 0 if the file was successfully deleted or -1 if an error occurred and errno is set.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
_unlink
Example
/* Example for remove */

#include <stdio.h>
#include <io.h>
#include <stdlib.h>

void main()
{
 int value;
 char buffer[13];
 char *result;

 printf("Enter file to remove: ");
 result = gets (buffer);
 value = remove (result);
 if (value == 0)
    printf("Erased \"%s\" from disk\n",
           result);
 else
 {
     perror("Unable to erase file");
     exit(EXIT_FAILURE);
 }
}
Output
Enter file to remove: delete.me
Erased "delete.me" from disk

rename

Header
stdio.h
io.h
Prototype
int rename (const char *oldname, const char *newname);
Description
Changes the name of a file from oldname to newname. Both oldname and newname may contain drive and path names but both names must refer to the same drive.
Return Value
0 if the file name was successfully changed. If unsuccessful, returns non-zero and sets errno to EACCESS or ENOENT.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
Example
/* Example for rename */

#include <stdio.h>
#include <stdlib.h>

void main()
{
 char oldn[_MAX_PATH];
 char newn[_MAX_PATH];
 int result;

 printf("Enter the old filename: ");
 gets(oldn);

 printf("Enter the new filename: ");
 gets(newn);

 result = rename(oldn, newn);

 if (result == 0)
    printf("File successfully renamed.\n");
 else
    perror("Unable to rename file");
}
Output
Enter the old filename: filename.old
Enter the new filename: filename.new
File successfully renamed.

setftime

Header
io.h
Prototype
int setftime(int handle, struct ftime *ftime);
Description
The setftime function sets a file's date and time. The handle argument specifies the file for which to set the data and time; the ftime argument specifies the date and time. The ftime structure, which is defined in io.h, is shown below:

struct ftime
{
 unsigned ft_tsec: 5;  /* seconds */
 unsigned ft_min: 6;   /* minutes */
 unsigned ft_hour: 5;  /* hours */
 unsigned ft_day: 5;   /* days */
 unsigned ft_month: 4; /* months */
 unsigned ft_year: 7;  /* year -1980 */
};
Return Value
If successful, zero is returned. If unsuccessful, -1 is returned and errno is set to EINVFNC (invalid function number) or EBADF (bad file number).
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
getftime
Example
/* Example for setftime */

#include <stdio.h>
#include <stdlib.h>
#include <io.h>
#include <dos.h>
#include <fcntl.h>

void evenftime (struct ftime *time)
{
 time-> ft_tsec = 0;
 time-> ft_min = 0;
 time-> ft_hour = 0;
 time-> ft_day = 1;
}
int dofile (char *fname)
{
 int fh;
 struct ftime time;
 char buffer[128];

 fh = _open(fname, _O_RDONLY);
 if (fh < 0)
 {
    sprintf(buffer, "Unable to open file: %s",
            fname);
    perror(buffer);
 }
 printf("setftime: %s\n", fname);

 getftime(fh, &time);
 evenftime(&time);
 setftime(fh, &time);

 _close(fh);
}

void main(int argc, char *argv[])
{
 int args;
 struct FIND *find;

 if (argc < 2)
 {
    printf("Usage: SETFTIME filespec [filespec [filespec [...]]]\n");
    exit(EXIT_FAILURE);
 }

 for (args = 1; args < argc; args++)
 {
    find = findfirst(argv[args], 0);

    while (find)
    {
      dofile (find->name);
      find = findnext();
    }
 }
}
Output
c:\dm\examples> dir setftime.c

Volume in drive C is DIGIMARS
Volume Serial Number is 1CD4-5ECB
Directory of c:\dm\examples

SETFTIME C 1,043 06-28-94 9:25a
1 file(s) 1,043 bytes
100,184,064 bytes free

c:\dm\examples> setftime setftime.c
setftime: SETFTIME.C

c:\dm\examples> dir setftime.c

Volume in drive C is DIGIMARS
Volume Serial Number is 1CD4-5ECB
Directory of c:\dm\examples

SETFTIME C 1,043 06-01-94 12:00a
1 file(s) 1,043 bytes
100,184,064 bytes free

unlock

Header
io.h
Prototype
int unlock(int handle, long offset, long length);
Description
The unlock function releases the file-sharing locks for the file associated with the handle argument. You should unlock all file-sharing locks before closing a file.
Return Value
Returns zero. If unsuccessful, returns -1 and sets errno and _doserrno.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
lock
Example
See lock
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums