logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

posix_memalign.3p (4124B)

    

  1. '\" et
  2. .TH POSIX_MEMALIGN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. posix_memalign
  12. \(em aligned memory allocation
  13. (\fBADVANCED REALTIME\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <stdlib.h>
  18. .P
  19. int posix_memalign(void **\fImemptr\fP, size_t \fIalignment\fP, size_t \fIsize\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIposix_memalign\fR()
  24. function shall allocate
  25. .IR size
  26. bytes aligned on a boundary specified by
  27. .IR alignment ,
  28. and shall return a pointer to the allocated memory in
  29. .IR memptr .
  30. The value of
  31. .IR alignment
  32. shall be a power of two multiple of
  33. .IR sizeof (\c
  34. .BR "void *" ).
  35. .P
  36. Upon successful completion, the value pointed to by
  37. .IR memptr
  38. shall be a multiple of
  39. .IR alignment .
  40. .P
  41. If the size of the space requested is 0, the behavior is
  42. implementation-defined: either a null pointer shall be returned in
  43. .IR memptr ,
  44. or the behavior shall be as if the size were some non-zero value,
  45. except that the behavior is undefined if the the value returned in
  46. .IR memptr
  47. is used to access an object.
  48. .P
  49. The
  50. \fIfree\fR()
  51. function shall deallocate memory that has previously been allocated by
  52. \fIposix_memalign\fR().
  53. .SH "RETURN VALUE"
  54. Upon successful completion,
  55. \fIposix_memalign\fR()
  56. shall return zero; otherwise, an error number shall be returned to
  57. indicate the error and the contents of
  58. .IR memptr
  59. shall either be left unmodified or be set to a null pointer.
  60. .P
  61. If
  62. .IR size
  63. is 0, either:
  64. .IP " *" 4
  65. \fIposix_memalign\fR()
  66. shall not attempt to allocate any space, in which case either an
  67. implementation-defined error number shall be returned, or zero shall
  68. be returned with a null pointer returned in
  69. .IR memptr ,
  70. or
  71. .IP " *" 4
  72. \fIposix_memalign\fR()
  73. shall attempt to allocate some space and, if the allocation succeeds,
  74. zero shall be returned and a pointer to the allocated space shall be
  75. returned in
  76. .IR memptr .
  77. The application shall ensure that the pointer is not used to access
  78. an object.
  79. .SH ERRORS
  80. The
  81. \fIposix_memalign\fR()
  82. function shall fail if:
  83. .TP
  84. .BR EINVAL
  85. The value of the alignment parameter is not a power of two multiple of
  86. .IR sizeof (\c
  87. .BR "void *" ).
  88. .TP
  89. .BR ENOMEM
  90. There is insufficient memory available with the requested alignment.
  91. .LP
  92. .IR "The following sections are informative."
  93. .SH EXAMPLES
  94. The following example shows how applications can obtain consistent
  95. behavior on error by setting *\c
  96. .IR memptr
  97. to be a null pointer before calling
  98. \fIposix_memalign\fR().
  99. .sp
  100. .RS 4
  101. .nf
  103. void *ptr = NULL;
  104. \&...
  105. //do some work, which might goto error
  106. if (posix_memalign(&ptr, align, size))
  107.     goto error;
  108. .P
  109. //do some more work, which might goto error
  110. \&...
  111. error:
  112.     free(ptr);
  113.     //more cleanup;
  114. .fi
  115. .P
  116. .RE
  117. .SH "APPLICATION USAGE"
  118. The
  119. \fIposix_memalign\fR()
  120. function is part of the Advisory Information option and need not be
  121. provided on all implementations.
  122. .SH RATIONALE
  123. None.
  124. .SH "FUTURE DIRECTIONS"
  125. None.
  126. .SH "SEE ALSO"
  127. .IR "\fIfree\fR\^(\|)",
  128. .IR "\fImalloc\fR\^(\|)"
  129. .P
  130. The Base Definitions volume of POSIX.1\(hy2017,
  131. .IR "\fB<stdlib.h>\fP"
  132. .\"
  133. .SH COPYRIGHT
  134. Portions of this text are reprinted and reproduced in electronic form
  135. from IEEE Std 1003.1-2017, Standard for Information Technology
  136. -- Portable Operating System Interface (POSIX), The Open Group Base
  137. Specifications Issue 7, 2018 Edition,
  138. Copyright (C) 2018 by the Institute of
  139. Electrical and Electronics Engineers, Inc and The Open Group.
  140. In the event of any discrepancy between this version and the original IEEE and
  141. The Open Group Standard, the original IEEE and The Open Group Standard
  142. is the referee document. The original Standard can be obtained online at
  143. http://www.opengroup.org/unix/online.html .
  144. .PP
  145. Any typographical or formatting errors that appear
  146. in this page are most likely
  147. to have been introduced during the conversion of the source files to
  148. man page format. To report such errors, see
  149. https://www.kernel.org/doc/man-pages/reporting_bugs.html .