Re: [PATCH] Add "Inter-process Communication" chapter to the glibc manual.

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

On 02/26/2014 10:06 AM, Florian Weimer wrote:
> On 02/26/2014 04:00 PM, Carlos O'Donell wrote:
>> On 02/26/2014 03:47 AM, Florian Weimer wrote:
>>> On 02/26/2014 05:54 AM, Carlos O'Donell wrote:
>>> 
>>>> +The @glibcadj{} implements the semaphore APIs as defined in
>>>> POSIX and +System V. Semaphores can be used by multiple
>>>> processes to coordinate shared +resources. The following is a
>>>> complete list of the semaphore functions provided +by
>>>> @theglibc{}.
>>> 
>>> I think the GNU style calls for two spaces at the end of a
>>> sentence.
>> 
>> It is, but AFAIK makes no difference in the output since such
>> formatting is handled by texinfo (the pdf shows no difference).
> 
> Yes, the TeX and HTML pipeline never cared.  But I think the regular
> Info output was affected.  The old makeinfo implementation used to
> copy over all kinds of formatting artifacts.  I don't see this
> anymore, perhaps it was fixed in the Perl reimplementation.

I find the info odd in that sometimes it uses double space and
other times it doesn't. Looks buggy to me.

I've checked in the following:

v1
- Original patch.
v2
- Added double space after periods.
v3
- Added %MENU comment for info generation.

It's better than nothing and is a step forward for documenting
the IPC functions.

2014-02-26  Carlos O'Donell  <carlos@redhat.com>

	* manual/ipc.texi: New file.
	* manual/Makefile (chapters): Add ipc.
	* manual/job.texi: Add "Inter-Process Communication" to next.
	* manual/process.texi: Add "Inter-Process Communication" to prev.

diff --git a/manual/Makefile b/manual/Makefile
index 5f98b2a..1129136 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -41,8 +41,8 @@ chapters = $(addsuffix .texi, \
 		       intro errno memory ctype string charset locale	\
 		       message search pattern io stdio llio filesys	\
 		       pipe socket terminal syslog math arith time	\
-		       resource setjmp signal startup process job nss	\
-		       users sysinfo conf crypt debug threads probes)
+		       resource setjmp signal startup process ipc job	\
+		       nss users sysinfo conf crypt debug threads probes)
 add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
 appendices = lang.texi header.texi install.texi maint.texi platform.texi \
 	     contrib.texi
diff --git a/manual/ipc.texi b/manual/ipc.texi
new file mode 100644
index 0000000..3cd573e
--- /dev/null
+++ b/manual/ipc.texi
@@ -0,0 +1,116 @@
+@node Inter-Process Communication, Job Control, Processes, Top
+@c %MENU% All about inter-process communication
+@chapter Inter-Process Communication
+@cindex ipc
+
+This chapter describes the @glibcadj{} inter-process communication primitives.
+
+@menu
+* Semaphores::	Support for creating and managing semaphores
+@end menu
+
+@node Semaphores
+@section Semaphores
+
+The @glibcadj{} implements the semaphore APIs as defined in POSIX and
+System V.  Semaphores can be used by multiple processes to coordinate shared
+resources.  The following is a complete list of the semaphore functions provided
+by @theglibc{}.
+
+@c Need descriptions for all of these functions.
+
+@subsection System V Semaphores
+@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}}
+@c syscall(ipc) ok
+@c
+@c AC-unsafe because we need to translate the new kernel
+@c semid_ds buf into the userspace layout.  Cancellation
+@c at that point results in an inconsistent userspace
+@c semid_ds.
+@end deftypefun
+
+@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@subsection POSIX Semaphores
+
+@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Does not atomically update sem_t therefore AC-unsafe
+@c because it can leave sem_t partially initialized.
+@end deftypefun
+
+@deftypefun int sem_destroy (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Function does nothing and is therefore always safe.
+@end deftypefun
+
+@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...);
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
+@c pthread_once asuinit
+@c
+@c We are AC-Unsafe becuase we use pthread_once to initialize
+@c a global variable that holds the location of the mounted
+@c shmfs on Linux.
+@end deftypefun
+
+@deftypefun int sem_close (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@asucorrupt{}}}
+@c lll_lock asulock aculock
+@c twalk asucorrupt
+@c
+@c We are AS-unsafe because we take a non-recursive lock.
+@c We are AC-unsafe because several internal data structures
+@c are not updated atomically.
+@end deftypefun
+
+@deftypefun int sem_unlink (const char *@var{name});
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
+@c pthread_once asuinit acucorrupt aculock
+@c mempcpy acucorrupt
+@end deftypefun
+
+@deftypefun int sem_wait (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c atomic_increment (nwaiters) acucorrupt
+@c
+@c Given the use atomic operations this function seems
+@c to be AS-safe.  It is AC-unsafe because there is still
+@c a window between atomic_decrement and the pthread_push
+@c of the handler that undoes that operation.  A cancellation
+@c at that point would fail to remove the process from the
+@c waiters count.
+@end deftypefun
+
+@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Same safety issues as sem_wait.
+@end deftypefun
+
+@deftypefun int sem_trywait (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c All atomic operations are safe in all contexts.
+@end deftypefun
+
+@deftypefun int sem_post (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Same safety as sem_trywait.
+@end deftypefun
+
+@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Atomic write of a value is safe in all contexts.
+@end deftypefun
diff --git a/manual/job.texi b/manual/job.texi
index 4e58f54..4f9bd81 100644
--- a/manual/job.texi
+++ b/manual/job.texi
@@ -1,4 +1,4 @@
-@node Job Control, Name Service Switch, Processes, Top
+@node Job Control, Name Service Switch, Inter-Process Communication, Top
 @c %MENU% All about process groups and sessions
 @chapter Job Control
 
diff --git a/manual/process.texi b/manual/process.texi
index aee65b9..aa59040 100644
--- a/manual/process.texi
+++ b/manual/process.texi
@@ -1,4 +1,4 @@
-@node Processes, Job Control, Program Basics, Top
+@node Processes, Inter-Process Communication, Program Basics, Top
 @c %MENU% How to create processes and run other programs
 @chapter Processes
 
---
Cheers,
Carlos.