This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [MTASCsft PATCH 34/??] MT-, AS- and AC-Safety docs: manual/terminal.texi


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
> 
> 


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]