PERFORCE change 151442 for review

[Ed Schouten]

http://perforce.freebsd.org/chv.cgi?CH=151442

Change 151442 by ed at ed_dull on 2008/10/16 07:23:11

	Finally take some time to write the ttydisc_getc(9) manpage.

Affected files ...

.. //depot/projects/mpsafetty/share/man/man9/Makefile#9 edit
.. //depot/projects/mpsafetty/share/man/man9/ttydisc_getc.9#3 edit

Differences ...

==== //depot/projects/mpsafetty/share/man/man9/Makefile#9 (text+ko) ====

@@ -1180,6 +1180,7 @@
 	timeout.9 untimeout.9
 MLINKS+=tty_alloc.9 tty_makedev.9 \
 	tty_alloc.9 tty_rel_gone.9 \
+	ttydisc_getc.9 ttydisc_getc_poll.9 \
 	ttydisc_getc.9 ttydisc_getc_uio.9 \
 	ttydisc_rint.9 ttydisc_can_bypass.9 \
 	ttydisc_rint.9 ttydisc_rint_bypass.9 \

==== //depot/projects/mpsafetty/share/man/man9/ttydisc_getc.9#3 (text+ko) ====

@@ -29,15 +29,73 @@
 .Os
 .Sh NAME
 .Nm ttydisc_getc ,
+.Nm ttydisc_getc_poll ,
 .Nm ttydisc_getc_uio
 .Nd "TTY character transmission"
 .Sh SYNOPSIS
 .In sys/tty.h
 .Ft size_t
 .Fn ttydisc_getc "struct tty *tp" "void *buf" "size_t len"
+.Ft size_t
+.Fn ttydisc_getc_poll "struct tty *tp"
 .Ft int
 .Fn ttydisc_getc_uio "struct tty *tp" "struct uio *uio"
 .Sh DESCRIPTION
+The 
+.Fn ttydisc_getc
+and
+.Fn ttydisc_getc_uio
+are used to obtain data from the output buffer of TTY
+.Fa tp .
+This data can then be physically sent by the device driver.
+.Pp
+The
+.Fn ttydisc_getc
+function copies
+.Fa len
+bytes of data to
+.Fa buf .
+The TTY lock must be held when calling
+.Fn ttydisc_getc .
+.Pp
+The
+.Fn ttydisc_getc_uio
+is an optimised version that copies data directly to userspace.
+The
+.Fa uio
+argument points to an I/O vector.
+Like
+.Fn ttydisc_getc ,
+this function also requires the TTY lock to be held, but during its
+invocation may be dropped, which is required to copy data to userspace.
+.Pp
+The
+.Fn ttydisc_getc_poll
+function returns an estimate of the amount of data that is stored in the
+output buffers of TTY
+.Fa tp .
+Device drivers should not rely on it being accurate.
+It should only be used by drivers like
+.Xr pts 4
+to implement
+.Xr select 2 .
+.Sh RETURN VALUES
+The
+.Fn ttydisc_getc
+function returns the amount of bytes that have been copied to
+.Fa buf .
+.Pp
+The
+.Fn ttydisc_getc_poll
+function returns the amount of bytes that are still present inside the
+TTY output buffers.
+.Pp
+The
+.Fn ttydisc_getc_uio
+function returns 0 when data has been copied to userspace successfully.
+It may return an error number when an error occurs, such as a failing
+call to
+.Xr uiomove 9 .
 .Sh SEE ALSO
 .Xr tty_alloc 9 ,
 .Xr tty_lock 9 ,