This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [MTASCsft PATCH 34/??] MT-, AS- and AC-Safety docs: manual/terminal.texi
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Alexandre Oliva <aoliva at redhat dot com>
- Cc: codonell at redhat dot com, libc-alpha at sourceware dot org
- Date: Sat, 01 Feb 2014 00:33:10 -0500
- Subject: Re: [MTASCsft PATCH 34/??] MT-, AS- and AC-Safety docs: manual/terminal.texi
- Authentication-results: sourceware.org; auth=none
- References: <ortxelb5zd dot fsf at livre dot home> <or4n4uoncj dot fsf at livre dot home> <orvbx4eo5o dot fsf_-_ at livre dot home> <52EC5A75 dot 2050609 at redhat dot com> <ory51vjtjv dot fsf at livre dot home>
On 02/01/2014 12:22 AM, Alexandre Oliva wrote:
> On Feb 1, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
>
>> On 01/27/2014 11:16 PM, Alexandre Oliva wrote:
>>> There are some, erhm, creative notations introduced in this patch:
>>> brk(filedes) and tcattr(filedes) denote the brk flag and the terminal
>>> attributes, respectively, of of a file descriptor passed as argument
>>> named filedes.
>
>> These are just markers for similar functions?
>> The user doesn't have to know what they mean.
>
> brk, as a member of tcattr, tried to allow for finer-grained locking
> without really accomplishing it, so we dropped it in favor of tcattr.
> That, along with documentation under term and :identifier, enables the
> user to use them without really knowing what they mean.
>
> Well, except that they have to realize that tcattr(fd) may conflict even
> for different fds, if they refer to the same terminal. But that's
> covered in the documentation of term.
>
> Here's the revised patch. If this one and the (a?) revised intro patch
> are approved, I'll go ahead and install errno and filesys as well, that
> were waiting for the documentation of /conditionals.
>
> Thanks,
>
>
> MT-, AS- and AC-safety docs: manual/terminal.texi
>
> From: Alexandre Oliva <aoliva@redhat.com>
>
> for ChangeLog
>
> * manual/terminal.texi: Document MTASC-safety properties.
OK to checkin now.
> ---
> manual/terminal.texi | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 174 insertions(+)
>
> diff --git a/manual/terminal.texi b/manual/terminal.texi
> index 9e9c057..0f0354b 100644
> --- a/manual/terminal.texi
> +++ b/manual/terminal.texi
> @@ -44,6 +44,9 @@ file @file{unistd.h}.
> @comment unistd.h
> @comment POSIX.1
> @deftypefun int isatty (int @var{filedes})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c isatty ok
> +@c tcgetattr dup ok
> This function returns @code{1} if @var{filedes} is a file descriptor
> associated with an open terminal device, and @math{0} otherwise.
> @end deftypefun
> @@ -55,6 +58,20 @@ associated file name using the @code{ttyname} function. See also the
> @comment unistd.h
> @comment POSIX.1
> @deftypefun {char *} ttyname (int @var{filedes})
> +@safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
> +@c ttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
> +@c isatty dup ok
> +@c fstat dup ok
> +@c memcpy dup ok
> +@c getttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
> +@c opendir @ascuheap @acsmem @acsfd
> +@c readdir ok [protected by exclusive access]
> +@c strcmp dup ok
> +@c free dup @asulock @aculock @acsfd @acsmem
> +@c malloc dup @asulock @aculock @acsfd @acsmem
> +@c closedir @ascuheap @acsmem @acsfd
> +@c mempcpy dup ok
> +@c stat dup ok
> If the file descriptor @var{filedes} is associated with a terminal
> device, the @code{ttyname} function returns a pointer to a
> statically-allocated, null-terminated string containing the file name of
> @@ -65,6 +82,18 @@ isn't associated with a terminal, or the file name cannot be determined.
> @comment unistd.h
> @comment POSIX.1
> @deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
> +@c ttyname_r @ascuheap @acsmem @acsfd
> +@c isatty dup ok
> +@c fstat dup ok
> +@c memcpy dup ok
> +@c getttyname_r @ascuheap @acsmem @acsfd
> +@c opendir @ascuheap @acsmem @acsfd
> +@c readdir ok [protected by exclusive access]
> +@c strcmp dup ok
> +@c closedir @ascuheap @acsmem @acsfd
> +@c stpncpy dup ok
> +@c stat dup ok
> The @code{ttyname_r} function is similar to the @code{ttyname} function
> except that it places its result into the user-specified buffer starting
> at @var{buf} with length @var{len}.
> @@ -264,6 +293,9 @@ array.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Converting the kernel-returned termios data structure to the userland
> +@c format does not ensure atomic or consistent writing.
> This function is used to examine the attributes of the terminal
> device with file descriptor @var{filedes}. The attributes are returned
> in the structure that @var{termios-p} points to.
> @@ -284,6 +316,9 @@ The @var{filedes} is not associated with a terminal.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Converting the incoming termios data structure to the kernel format
> +@c does not ensure atomic or consistent reading.
> This function sets the attributes of the terminal device with file
> descriptor @var{filedes}. The new attributes are taken from the
> structure that @var{termios-p} points to.
> @@ -1016,6 +1051,10 @@ store them:
> @comment termios.h
> @comment POSIX.1
> @deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Direct access to a single termios field, except on Linux, where
> +@c multiple accesses may take place. No worries either way, callers
> +@c must ensure mutual exclusion on such non-opaque types.
> This function returns the output line speed stored in the structure
> @code{*@var{termios-p}}.
> @end deftypefun
> @@ -1023,6 +1062,7 @@ This function returns the output line speed stored in the structure
> @comment termios.h
> @comment POSIX.1
> @deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> This function returns the input line speed stored in the structure
> @code{*@var{termios-p}}.
> @end deftypefun
> @@ -1030,6 +1070,7 @@ This function returns the input line speed stored in the structure
> @comment termios.h
> @comment POSIX.1
> @deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> This function stores @var{speed} in @code{*@var{termios-p}} as the output
> speed. The normal return value is @math{0}; a value of @math{-1}
> indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
> @@ -1039,6 +1080,7 @@ returns @math{-1}.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> This function stores @var{speed} in @code{*@var{termios-p}} as the input
> speed. The normal return value is @math{0}; a value of @math{-1}
> indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
> @@ -1048,6 +1090,14 @@ returns @math{-1}.
> @comment termios.h
> @comment BSD
> @deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c There's no guarantee that the two calls are atomic, but since this is
> +@c not an opaque type, callers ought to ensure mutual exclusion to the
> +@c termios object.
> +
> +@c cfsetspeed ok
> +@c cfsetispeed ok
> +@c cfsetospeed ok
> This function stores @var{speed} in @code{*@var{termios-p}} as both the
> input and output speeds. The normal return value is @math{0}; a value
> of @math{-1} indicates an error. If @var{speed} is not a speed,
> @@ -1625,6 +1675,10 @@ uses.
> @comment termios.h
> @comment BSD
> @deftypefun void cfmakeraw (struct termios *@var{termios-p})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c There's no guarantee the changes are atomic, but since this is not an
> +@c opaque type, callers ought to ensure mutual exclusion to the termios
> +@c object.
> This function provides an easy way to set up @code{*@var{termios-p}} for
> what has traditionally been called ``raw mode'' in BSD. This uses
> noncanonical input, and turns off most processing to give an unmodified
> @@ -1678,6 +1732,8 @@ Various flags
> @comment sgtty.h
> @comment BSD
> @deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Direct ioctl, BSD only.
> This function gets the attributes of a terminal.
>
> @code{gtty} sets *@var{attributes} to describe the terminal attributes
> @@ -1687,6 +1743,8 @@ of the terminal which is open with file descriptor @var{filedes}.
> @comment sgtty.h
> @comment BSD
> @deftypefun int stty (int @var{filedes}, const struct sgttyb *@var{attributes})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Direct ioctl, BSD only.
>
> This function sets the attributes of a terminal.
>
> @@ -1710,6 +1768,12 @@ operation is performed and no signal is sent. @xref{Job Control}.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
> +@safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acunsafe{@acucorrupt{/bsd}}}
> +@c On Linux, this calls just one out of two ioctls; on BSD, it's two
> +@c ioctls with a select (for the delay only) in between, the first
> +@c setting and the latter clearing the break status. The BSD
> +@c implementation may leave the break enabled if cancelled, and threads
> +@c and signals may cause the break to be interrupted before requested.
> This function generates a break condition by transmitting a stream of
> zero bits on the terminal associated with the file descriptor
> @var{filedes}. The duration of the break is controlled by the
> @@ -1738,6 +1802,8 @@ The @var{filedes} is not associated with a terminal device.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int tcdrain (int @var{filedes})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Direct ioctl.
> The @code{tcdrain} function waits until all queued
> output to the terminal @var{filedes} has been transmitted.
>
> @@ -1772,6 +1838,8 @@ The operation was interrupted by delivery of a signal.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int tcflush (int @var{filedes}, int @var{queue})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Direct ioctl.
> The @code{tcflush} function is used to clear the input and/or output
> queues associated with the terminal file @var{filedes}. The @var{queue}
> argument specifies which queue(s) to clear, and can be one of the
> @@ -1822,6 +1890,11 @@ from POSIX and we cannot change it.
> @comment termios.h
> @comment POSIX.1
> @deftypefun int tcflow (int @var{filedes}, int @var{action})
> +@safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}}
> +@c Direct ioctl on Linux. On BSD, the TCO* actions are a single ioctl,
> +@c whereas the TCI actions first call tcgetattr and then write to the fd
> +@c the c_cc character corresponding to the action; there's a window for
> +@c another thread to change the xon/xoff characters.
> The @code{tcflow} function is used to perform operations relating to
> XON/XOFF flow control on the terminal file specified by @var{filedes}.
>
> @@ -1931,6 +2004,14 @@ functions are declared in the header file @file{stdlib.h}.
> @comment stdlib.h
> @comment GNU
> @deftypefun int getpt (void)
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> +@c On BSD, tries to open multiple potential pty names, returning on the
> +@c first success. On Linux, try posix_openpt first, then fallback to
> +@c the BSD implementation. The posix implementation opens the ptmx
> +@c device, checks with statfs that /dev/pts is a devpts or that /dev is
> +@c a devfs, and returns the fd; static variables devpts_mounted and
> +@c have_no_dev_ptmx are safely initialized so as to avoid repeated
> +@c tests.
> The @code{getpt} function returns a new file descriptor for the next
> available master pseudo-terminal. The normal return value from
> @code{getpt} is a non-negative integer file descriptor. In the case of
> @@ -1948,6 +2029,32 @@ This function is a GNU extension.
> @comment stdlib.h
> @comment SVID, XPG4.2
> @deftypefun int grantpt (int @var{filedes})
> +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
> +@c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c unix/grantpt:pts_name @acsuheap @acsmem
> +@c ptsname_internal dup ok (but this is Linux-only!)
> +@c memchr dup ok
> +@c realloc dup @acsuheap @acsmem
> +@c malloc dup @acsuheap @acsmem
> +@c free dup @acsuheap @acsmem
> +@c fcntl dup ok
> +@c getuid dup ok
> +@c chown dup ok
> +@c sysconf(_SC_GETGR_R_SIZE_MAX) ok
> +@c getgrnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c getgid dup ok
> +@c chmod dup ok
> +@c fork dup @aculock
> +@c [child]
> +@c setrlimit
> +@c dup2
> +@c CLOSE_ALL_FDS
> +@c execle
> +@c _exit
> +@c waitpid dup ok
> +@c WIFEXITED dup ok
> +@c WEXITSTATUS dup ok
> +@c free dup @ascuheap @acsmem
> The @code{grantpt} function changes the ownership and access permission
> of the slave pseudo-terminal device corresponding to the master
> pseudo-terminal device associated with the file descriptor
> @@ -1985,6 +2092,13 @@ with @var{filedes} could not be accessed.
> @comment stdlib.h
> @comment SVID, XPG4.2
> @deftypefun int unlockpt (int @var{filedes})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
> +@c unlockpt @ascuheap/bsd @acsmem @acsfd
> +@c /bsd
> +@c ptsname_r dup @ascuheap @acsmem @acsfd
> +@c revoke ok (syscall)
> +@c /linux
> +@c ioctl dup ok
> The @code{unlockpt} function unlocks the slave pseudo-terminal device
> corresponding to the master pseudo-terminal device associated with the
> file descriptor @var{filedes}. On many systems, the slave can only be
> @@ -2008,6 +2122,9 @@ device.
> @comment stdlib.h
> @comment SVID, XPG4.2
> @deftypefun {char *} ptsname (int @var{filedes})
> +@safety{@prelim{}@mtunsafe{@mtasurace{:ptsname}}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
> +@c ptsname @mtasurace:ptsname @ascuheap/bsd @acsmem @acsfd
> +@c ptsname_r dup @ascuheap/bsd @acsmem @acsfd
> If the file descriptor @var{filedes} is associated with a
> master pseudo-terminal device, the @code{ptsname} function returns a
> pointer to a statically-allocated, null-terminated string containing the
> @@ -2018,6 +2135,37 @@ might be overwritten by subsequent calls to @code{ptsname}.
> @comment stdlib.h
> @comment GNU
> @deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
> +@c ptsname_r @ascuheap/bsd @acsmem @acsfd
> +@c /hurd
> +@c term_get_peername ok
> +@c strlen dup ok
> +@c memcpy dup ok
> +@c /bsd
> +@c isatty dup ok
> +@c strlen dup ok
> +@c ttyname_r dup @ascuheap @acsmem @acsfd
> +@c stat dup ok
> +@c /linux
> +@c ptsname_internal ok
> +@c isatty dup ok
> +@c ioctl dup ok
> +@c strlen dup ok
> +@c itoa_word dup ok
> +@c stpcpy dup ok
> +@c memcpy dup ok
> +@c fxstat64 dup ok
> +@c MASTER_P ok
> +@c major ok
> +@c gnu_dev_major ok
> +@c minor ok
> +@c gnu_dev_minor ok
> +@c minor dup ok
> +@c xstat64 dup ok
> +@c S_ISCHR dup ok
> +@c SLAVE_P ok
> +@c major dup ok
> +@c minor dup ok
> The @code{ptsname_r} function is similar to the @code{ptsname} function
> except that it places its result into the user-specified buffer starting
> at @var{buf} with length @var{len}.
> @@ -2083,6 +2231,22 @@ These functions, derived from BSD, are available in the separate
> @comment pty.h
> @comment BSD
> @deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp})
> +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
> +@c openpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c getpt @acsfd
> +@c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c unlockpt dup @ascuheap/bsd @acsmem @acsfd
> +@c openpty:pts_name @acsuheap @acsmem @acsfd
> +@c ptsname_r dup @ascuheap/bsd @acsmem @acsfd
> +@c realloc dup @acsuheap @acsmem
> +@c malloc dup @acsuheap @acsmem
> +@c free dup @acsuheap @acsmem
> +@c open dup @acsfd
> +@c free dup @acsuheap @acsmem
> +@c tcsetattr dup ok
> +@c ioctl dup ok
> +@c strcpy dup ok
> +@c close dup @acsfd
> This function allocates and opens a pseudo-terminal pair, returning the
> file descriptor for the master in @var{*amaster}, and the file
> descriptor for the slave in @var{*aslave}. If the argument @var{name}
> @@ -2114,6 +2278,16 @@ device instead.
> @comment pty.h
> @comment BSD
> @deftypefun int forkpty (int *@var{amaster}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp})
> +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
> +@c forkpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c openpty dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c fork dup @aculock
> +@c close dup @acsfd
> +@c /child
> +@c close dup @acsfd
> +@c login_tty dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
> +@c _exit dup ok
> +@c close dup @acsfd
> This function is similar to the @code{openpty} function, but in
> addition, forks a new process (@pxref{Creating a Process}) and makes the
> newly opened slave pseudo-terminal device the controlling terminal
>
>