man3/sem_getvalue.3

   1 '\" t
   2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH sem_getvalue 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 sem_getvalue \- get the value of a semaphore
   9 .SH LIBRARY
  10 POSIX threads library
  11 .RI ( libpthread ", " \-lpthread )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <semaphore.h>
  15 .P
  16 .BI "int sem_getvalue(sem_t *restrict " sem ", int *restrict " sval );
  17 .fi
  18 .SH DESCRIPTION
  19 .BR sem_getvalue ()
  20 places the current value of the semaphore pointed to
  21 .I sem
  22 into the integer pointed to by
  23 .IR sval .
  24 .P
  25 If one or more processes or threads are blocked
  26 waiting to lock the semaphore with
  27 .BR sem_wait (3),
  28 POSIX.1 permits two possibilities for the value returned in
  29 .IR sval :
  30 either 0 is returned;
  31 or a negative number whose absolute value is the count
  32 of the number of processes and threads currently blocked in
  33 .BR sem_wait (3).
  34 Linux adopts the former behavior.
  35 .SH RETURN VALUE
  36 .BR sem_getvalue ()
  37 returns 0 on success;
  38 on error, \-1 is returned and
  39 .I errno
  40 is set to indicate the error.
  41 .SH ERRORS
  42 .TP
  43 .B EINVAL
  44 .I sem
  45 is not a valid semaphore.
  46 (The glibc implementation currently does not check whether
  47 .I sem
  48 is valid.)
  49 .SH ATTRIBUTES
  50 For an explanation of the terms used in this section, see
  51 .BR attributes (7).
  52 .TS
  53 allbox;
  54 lbx lb lb
  55 l l l.
  56 Interface       Attribute       Value
  57 T{
  58 .na
  59 .nh
  60 .BR sem_getvalue ()
  61 T}      Thread safety   MT-Safe
  62 .TE
  63 .SH STANDARDS
  64 POSIX.1-2008.
  65 .SH HISTORY
  66 POSIX.1-2001.
  67 .SH NOTES
  68 The value of the semaphore may already have changed by the time
  69 .BR sem_getvalue ()
  70 returns.
  71 .SH SEE ALSO
  72 .BR sem_post (3),
  73 .BR sem_wait (3),
  74 .BR sem_overview (7)