www.digitalmars.com [Home] [Search] [Contents]

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

Complex Class Functions

These functions are described in Chapter 25, "The Complex Class
Library".


_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); 

	   if ((fh = _open (fname, _O_RDONLY)) < 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:\SC\EXAMPLES>_isatty
stdin is connected to the keyboard

C:\SC\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; 
	
	   if ((fd = _open("temp.fil",_O_RDONLY))== -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 ("\\sc\\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], fn[_MAX_PATH];
	   int fd, numread; 
	
	   printf ("Enter a filename: ");
	   scanf ("%s", fn); 

	   if ((fd = _open (fn, _O_RDONLY)) == -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 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); 

	   if ((fp = fopen(fname, "r")) == 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); 

	   if ((fp = fopen ("new.dat", "w")) == 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:\\sc\\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], 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]; 

	   if ((fh = _open (fname, _O_RDONLY)) < 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:\SC\EXAMPLES> dir setftime.c

	Volume in drive C is DIGIMARS
	Volume Serial Number is 1CD4-5ECB
	Directory of C:\SC\EXAMPLES
	 
	SETFTIME C 1,043 06-28-94 9:25a
	1 file(s) 1,043 bytes
	100,184,064 bytes free
	 
	C:\SC\EXAMPLES> setftime setftime.c
	setftime: SETFTIME.C

	C:\SC\EXAMPLES> dir setftime.c

	Volume in drive C is DIGIMARS
	Volume Serial Number is 1CD4-5ECB
	Directory of C:\SC\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