test-container: Fix "unused code" warnings on HURD

[thirdparty/glibc.git] / manual / ipc.texi

@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

@Theglibc{} 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{@aculock{}}}
@c lll_lock asulock aculock
@c twalk mtsrace{:root}
@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