Devices

Open, close, read, and write to devices. More...

Functions
devcall	close (int descrp)
devcall	control (int descrp, int func, long arg1, long arg2)
devcall	getc (int descrp)
syscall	getdev (const char *dev)
devcall	ioerr (void)
devcall	ionull (void)
devcall	open (int descrp,...)
devcall	putc (int descrp, char ch)
devcall	read (int descrp, void *buffer, uint count)
devcall	write (int descrp, const void *buffer, uint count)

Detailed Description

Open, close, read, and write to devices.

Function Documentation

devcall close

(

int

descrp

)

Close a device.

Parameters

descrp

Index of the device to close.

Returns

::OK if device was successfully closed; ::SYSERR otherwise.

Most device drivers will return ::SYSERR if the device is not open but otherwise will always be able to successfully close the device and return ::OK.

Caveat: You must not close the device while any threads are using it (e.g. for read() or write()), unless the corresponding device driver documents this as allowed.

devcall control	(	int	descrp,
		int	func,
		long	arg1,
		long	arg2
	)

Execute an I/O Control request on a device.

Parameters

descrp	Index of the device.
func	Device-specific specific control "function".
arg1	Additional argument for the device-specific control function.
arg2	Additional argument for the device-specific control function.

Returns

Returns ::SYSERR if the device index does not correspond to an appropriate device or if the control function is not recognized; otherwise returns a request-specific value that is typically ::SYSERR on failure, but may be either ::OK or request-specific data on success.

devcall getc

(

int

descrp

)

Read one character from a device.

Parameters

descrp

Index of device from which to read the character.

Returns

On success, returns the character read as an unsigned char cast to an int. On bad device descripter, returns ::SYSERR. On other failure, returns ::SYSERR or ::EOF depending on the specific device driver it calls.

syscall getdev

(

const char *

dev

)

Translates a device name into a device number.

Parameters

dev	Name of the device.

Returns

The number of the device, or ::SYSERR if the device was not found.

devcall ioerr

(

void

)

Unconditionally return an error (used for "error" entries in devtab).

Returns

::SYSERR

devcall ionull

(

void

)

Do nothing (use for irrelevant entries in devtab).

Returns

::OK

devcall open	(	int	descrp,
			...
	)

Open a device so that read(), write(), putc(), and/or getc() operations can be performed on it.

Parameters

descrp	Index of the device to open.
...	Zero or more additional parameters that will be passed to the device-specific open function.

Returns

On success, returns ::OK. If the device index is bad or if another error occurs, returns ::SYSERR. Generally, device drivers will at least return ::SYSERR in the case that the device is already open, but ::SYSERR may also be returned because of failure to allocate resources or for device-specific errors.

devcall putc	(	int	descrp,
		char	ch
	)

Write one character to a device.

Parameters

descrp	Index of device to which to write the character.
ch	character to write

Returns

On success, returns the character written as an unsigned char cast to an int. On bad device descripter, returns ::SYSERR. On other failure, returns ::SYSERR or ::EOF depending on the specific device driver it calls.

devcall read	(	int	descrp,
		void *	buffer,
		uint	count
	)

Read data from a device.

Parameters

descrp	Index of the device to read from.
buffer	Buffer into which to read the data.
count	Maximum number of bytes to read.

Returns

On success, returns the number of bytes read, which may be less than count in the event of a read error or end-of-file condition. Alternatively, ::SYSERR is returned if the device index is not valid or if a read error occurred before any data at all was successfully read.

devcall write	(	int	descrp,
		const void *	buffer,
		uint	count
	)

Write data to a device.

Parameters

descrp	Index of the device to write to.
buffer	Buffer of data to write.
count	Number of bytes of data to write.

Returns

On success, returns the number of bytes written, which may be less than count in the event of a write error. Alternatively, ::SYSERR is returned if the device index is not valid or if a write error occurred before any data at all was successfully written.

Note that, depending on the specific device, this function may simply buffer the data to be written at some later time via interrupt handling code.