From owner-p4-projects@FreeBSD.ORG Thu Oct 16 07:23:45 2008 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 7E66F10656E5; Thu, 16 Oct 2008 07:23:45 +0000 (UTC) Delivered-To: perforce@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 41A481065690 for ; Thu, 16 Oct 2008 07:23:45 +0000 (UTC) (envelope-from ed@FreeBSD.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id 222FC8FC33 for ; Thu, 16 Oct 2008 07:23:45 +0000 (UTC) (envelope-from ed@FreeBSD.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.3/8.14.3) with ESMTP id m9G7Njxt084976 for ; Thu, 16 Oct 2008 07:23:45 GMT (envelope-from ed@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.3/8.14.3/Submit) id m9G7NjWD084974 for perforce@freebsd.org; Thu, 16 Oct 2008 07:23:45 GMT (envelope-from ed@FreeBSD.org) Date: Thu, 16 Oct 2008 07:23:45 GMT Message-Id: <200810160723.m9G7NjWD084974@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to ed@FreeBSD.org using -f From: Ed Schouten To: Perforce Change Reviews Cc: Subject: PERFORCE change 151442 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 16 Oct 2008 07:23:45 -0000 http://perforce.freebsd.org/chv.cgi?CH=151442 Change 151442 by ed@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 ,