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

["Carlos O'Donell" <carlos at redhat dot com>]

On 01/27/2014 09:49 PM, Alexandre Oliva wrote:
> for ChangeLog
> 
> 	* manual/pipe.texi: Document MTASC-safety properties.

OK to checkin.

> ---
>  manual/pipe.texi |  110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 110 insertions(+)
> 
> diff --git a/manual/pipe.texi b/manual/pipe.texi
> index 21a8a34..2d7e30e 100644
> --- a/manual/pipe.texi
> +++ b/manual/pipe.texi
> @@ -56,6 +56,8 @@ The @code{pipe} function is declared in the header file
>  @comment unistd.h
>  @comment POSIX.1
>  @deftypefun int pipe (int @var{filedes}@t{[2]})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> +@c On Linux, syscall pipe2.  On HURD, call socketpair.
>  The @code{pipe} function creates a pipe and puts the file descriptors
>  for the reading and writing ends of the pipe (respectively) into
>  @code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
> @@ -108,6 +110,41 @@ much flexibility as using the low-level functions directly.
>  @comment stdio.h
>  @comment POSIX.2, SVID, BSD
>  @deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
> +@c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
> +@c  malloc dup @ascuheap @acsmem
> +@c  _IO_init ok
> +@c   _IO_no_init ok
> +@c    _IO_old_init ok
> +@c     _IO_lock_init ok
> +@c  _IO_new_file_init @asucorrupt @acucorrupt @aculock @acsfd
> +@c   _IO_link_in @asucorrupt @acucorrupt @aculock @acsfd
> +@c     the linked list is guarded by a recursive lock;
> +@c     it may get corrupted with async signals and cancellation
> +@c    _IO_lock_lock dup @aculock
> +@c    _IO_flockfile dup @aculock
> +@c    _IO_funlockfile dup @aculock
> +@c    _IO_lock_unlock dup @aculock
> +@c  _IO_new_proc_open @asucorrupt @acucorrupt @aculock @acsfd
> +@c    the linked list is guarded by a recursive lock;
> + @c   it may get corrupted with async signals and cancellation
> +@c   _IO_file_is_open ok
> +@c   pipe2 dup @acsfd
> +@c   pipe dup @acsfd
> +@c   _IO_fork=fork @aculock
> +@c   _IO_close=close_not_cancel dup @acsfd
> +@c   fcntl dup ok
> +@c   _IO_lock_lock @aculock
> +@c   _IO_lock_unlock @aculock
> +@c   _IO_mask_flags ok [no @mtasurace:stream, nearly but sufficiently exclusive access]
> +@c  _IO_un_link @asucorrupt @acucorrupt @aculock @acsfd
> +@c    the linked list is guarded by a recursive lock;
> +@c    it may get corrupted with async signals and cancellation
> +@c   _IO_lock_lock dup @aculock
> +@c   _IO_flockfile dup @aculock
> +@c   _IO_funlockfile dup @aculock
> +@c   _IO_lock_unlock dup @aculock
> +@c  free dup @ascuheap @acsmem
>  The @code{popen} function is closely related to the @code{system}
>  function; see @ref{Running a Command}.  It executes the shell command
>  @var{command} as a subprocess.  However, instead of waiting for the
> @@ -131,6 +168,77 @@ cannot be forked, or if the program cannot be executed.
>  @comment stdio.h
>  @comment POSIX.2, SVID, BSD
>  @deftypefun int pclose (FILE *@var{stream})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuplugin{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
> +@c Although the stream cannot be used after the call, even in case of
> +@c async cancellation, because the stream must not be used after pclose
> +@c is called, other stdio linked lists and their locks may be left in
> +@c corrupt states; that's where the corrupt and lock annotations come
> +@c from.
> +@c
> +@c pclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c  _IO_new_fclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
> +@c   _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
> +@c   _IO_acquire_lock dup @aculock
> +@c    _IO_flockfile dup @aculock
> +@c   _IO_file_close_it @ascuheap @ascuplugin @asucorrupt @aculock @acucorrupt @acsfd @acsmem
> +@c    _IO_file_is_open dup ok
> +@c    _IO_do_flush @asucorrupt @ascuplugin @acucorrupt
> +@c     _IO_do_write @asucorrupt @acucorrupt
> +@c      new_do_write @asucorrupt @acucorrupt
> +@c       _IO_SYSSEEK ok
> +@c        lseek64 dup ok
> +@c       _IO_SYSWRITE ok
> +@c        write_not_cancel dup ok
> +@c        write dup ok
> +@c       _IO_adjust_column ok
> +@c       _IO_setg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c     _IO_wdo_write @asucorrupt @ascuplugin @acucorrupt
> +@c      _IO_new_do_write=_IO_do_write dup @asucorrupt @acucorrupt
> +@c      *cc->__codecvt_do_out @ascuplugin
> +@c      _IO_wsetg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_unsave_markers @ascuheap @asucorrupt @acucorrupt @acsmem
> +@c     _IO_have_backup dup ok
> +@c     _IO_free_backup_area dup @ascuheap @asucorrupt @acucorrupt @acsmem
> +@c    _IO_SYSCLOSE @aculock @acucorrupt @acsfd
> +@c     _IO_lock_lock dup @aculock
> +@c     _IO_close=close_not_cancel dup @acsfd
> +@c     _IO_lock_unlock dup @aculock
> +@c     _IO_waitpid=waitpid_not_cancel dup ok
> +@c    _IO_have_wbackup ok
> +@c    _IO_free_wbackup_area @ascuheap @asucorrupt @acucorrupt @acsmem
> +@c     _IO_in_backup dup ok
> +@c     _IO_switch_to_main_wget_area @asucorrupt @acucorrupt
> +@c     free dup @ascuheap @acsmem
> +@c    _IO_wsetb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_wsetg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_wsetp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_setb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_setg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_setp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
> +@c    _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
> +@c   _IO_release_lock dup @aculock
> +@c    _IO_funlockfile dup @aculock
> +@c   _IO_FINISH @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
> +@c    _IO_new_file_finish @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
> +@c     _IO_file_is_open dup ok
> +@c     _IO_do_flush dup @ascuplugin @asucorrupt @acucorrupt
> +@c     _IO_SYSCLOSE dup @aculock @acucorrupt @acsfd
> +@c     _IO_default_finish @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
> +@c      FREE_BUF @acsmem
> +@c       munmap dup @acsmem
> +@c      free dup @ascuheap @acsmem
> +@c      _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
> +@c      _IO_lock_fini ok
> +@c       libc_lock_fini_recursive ok
> +@c   libc_lock_lock dup @asulock @aculock
> +@c   gconv_release_step ok
> +@c   libc_lock_unlock dup @asulock @aculock
> +@c   _IO_have_backup ok
> +@c   _IO_free_backup_area @ascuheap @asucorrupt @acucorrupt @acsmem
> +@c    _IO_in_backup ok
> +@c    _IO_switch_to_main_get_area @asucorrupt @acucorrupt
> +@c    free dup @ascuheap @acsmem
> +@c   free dup @ascuheap @acsmem
>  The @code{pclose} function is used to close a stream created by @code{popen}.
>  It waits for the child process to terminate and returns its status value,
>  as for the @code{system} function.
> @@ -168,6 +276,8 @@ The @code{mkfifo} function is declared in the header file
>  @comment sys/stat.h
>  @comment POSIX.1
>  @deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c On generic Posix, calls xmknod.
>  The @code{mkfifo} function makes a FIFO special file with name
>  @var{filename}.  The @var{mode} argument is used to set the file's
>  permissions; see @ref{Setting Permissions}.
>