/share/man/man3/pthread_once.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 107 lines · 107 code · 0 blank · 0 comment · 0 complexity · eed8dab8e1a7b3bd9e54c888b84b6ba6 MD5 · raw file 

    

  1. .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
    2. 

  2. .\" All rights reserved.
    3. 

  3. .\"
    4. 

  4. .\" Redistribution and use in source and binary forms, with or without
    5. 

  5. .\" modification, are permitted provided that the following conditions
    6. 

  6. .\" are met:
    7. 

  7. .\" 1. Redistributions of source code must retain the above copyright
    8. 

  8. .\"    notice, this list of conditions and the following disclaimer.
    9. 

  9. .\" 2. Redistributions in binary form must reproduce the above copyright
    10. 

  10. .\"    notice, this list of conditions and the following disclaimer in the
    11. 

  11. .\"    documentation and/or other materials provided with the distribution.
    12. 

  12. .\" 3. All advertising materials mentioning features or use of this software
    13. 

  13. .\"    must display the following acknowledgement:
    14. 

  14. .\"	This product includes software developed by John Birrell.
    15. 

  15. .\" 4. Neither the name of the author nor the names of any co-contributors
    16. 

  16. .\"    may be used to endorse or promote products derived from this software
    17. 

  17. .\"    without specific prior written permission.
    18. 

  18. .\"
    19. 

  19. .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
    20. 

  20. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    21. 

  21. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    22. 

  22. .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    23. 

  23. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    24. 

  24. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    25. 

  25. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    26. 

  26. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    27. 

  27. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    28. 

  28. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    29. 

  29. .\" SUCH DAMAGE.
    30. 

  30. .\"
    31. 

  31. .\" $FreeBSD$
    32. 

  32. .\"
    33. 

  33. .Dd April 4, 1996
    34. 

  34. .Dt PTHREAD_ONCE 3
    35. 

  35. .Os
    36. 

  36. .Sh NAME
    37. 

  37. .Nm pthread_once
    38. 

  38. .Nd dynamic package initialization
    39. 

  39. .Sh LIBRARY
    40. 

  40. .Lb libpthread
    41. 

  41. .Sh SYNOPSIS
    42. 

  42. .In pthread.h
    43. 

  43. .Pp
    44. 

  44. pthread_once_t
    45. 

  45. .Fa once_control
    46. 

  46. = PTHREAD_ONCE_INIT;
    47. 

  47. .Ft int
    48. 

  48. .Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
    49. 

  49. .Sh DESCRIPTION
    50. 

  50. The first call to
    51. 

  51. .Fn pthread_once
    52. 

  52. by any thread in a process, with a given
    53. 

  53. .Fa once_control ,
    54. 

  54. will call the
    55. 

  55. .Fn init_routine
    56. 

  56. with no arguments.
    57. 

  57. Subsequent calls to
    58. 

  58. .Fn pthread_once
    59. 

  59. with the same
    60. 

  60. .Fa once_control
    61. 

  61. will not call the
    62. 

  62. .Fn init_routine .
    63. 

  63. On return from
    64. 

  64. .Fn pthread_once ,
    65. 

  65. it is guaranteed that
    66. 

  66. .Fn init_routine
    67. 

  67. has completed.
    68. 

  68. The
    69. 

  69. .Fa once_control
    70. 

  70. parameter is used to determine whether the associated initialization
    71. 

  71. routine has been called.
    72. 

  72. .Pp
    73. 

  73. The function
    74. 

  74. .Fn pthread_once
    75. 

  75. is not a cancellation point.
    76. 

  76. However, if
    77. 

  77. .Fn init_routine
    78. 

  78. is a cancellation point and is cancelled, the effect on
    79. 

  79. .Fa once_control
    80. 

  80. is as if
    81. 

  81. .Fn pthread_once
    82. 

  82. was never called.
    83. 

  83. .Pp
    84. 

  84. The constant
    85. 

  85. .Fa PTHREAD_ONCE_INIT
    86. 

  86. is defined by header
    87. 

  87. .In pthread.h .
    88. 

  88. .Pp
    89. 

  89. The behavior of
    90. 

  90. .Fn pthread_once
    91. 

  91. is undefined if
    92. 

  92. .Fa once_control
    93. 

  93. has automatic storage duration or is not initialized by
    94. 

  94. .Fa PTHREAD_ONCE_INIT .
    95. 

  95. .Sh RETURN VALUES
    96. 

  96. If successful, the
    97. 

  97. .Fn pthread_once
    98. 

  98. function will return zero.
    99. 

  99. Otherwise an error number will be returned to
    100. 

  100. indicate the error.
    101. 

  101. .Sh ERRORS
    102. 

  102. None.
    103. 

  103. .Sh STANDARDS
    104. 

  104. The
    105. 

  105. .Fn pthread_once
    106. 

  106. function conforms to
    107. 

  107. .St -p1003.1-96 .
    108.