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

ftok.3p (4755B)

    

  1. '\" et
  2. .TH FTOK "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. ftok
  12. \(em generate an IPC key
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/ipc.h>
  17. .P
  18. key_t ftok(const char *\fIpath\fP, int \fIid\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIftok\fR()
  23. function shall return a key based on
  24. .IR path
  25. and
  26. .IR id
  27. that is usable in subsequent calls to
  28. \fImsgget\fR(),
  29. \fIsemget\fR(),
  30. and
  31. \fIshmget\fR().
  32. The application shall ensure that the
  33. .IR path
  34. argument is the pathname of an existing file that the process is
  35. able to
  36. \fIstat\fR(),
  37. with the exception that if
  38. \fIstat\fR()
  39. would fail with
  40. .BR [EOVERFLOW] 
  41. due to file size,
  42. \fIftok\fR()
  43. shall still succeed.
  44. .P
  45. The
  46. \fIftok\fR()
  47. function shall return the same key value for all paths that name the
  48. same file, when called with the same
  49. .IR id
  50. value, and should return different key values when called with different
  51. .IR id
  52. values or with paths that name different files existing on the same
  53. file system at the same time. It is unspecified whether
  54. \fIftok\fR()
  55. shall return the same key value when called again after the file named
  56. by
  57. .IR path
  58. is removed and recreated with the same name.
  59. .P
  60. Only the low-order 8-bits of
  61. .IR id
  62. are significant. The behavior of
  63. \fIftok\fR()
  64. is unspecified if these bits are 0.
  65. .SH "RETURN VALUE"
  66. Upon successful completion,
  67. \fIftok\fR()
  68. shall return a key. Otherwise,
  69. \fIftok\fR()
  70. shall return (\fBkey_t\fP)\-1 and set
  71. .IR errno
  72. to indicate the error.
  73. .SH ERRORS
  74. The
  75. \fIftok\fR()
  76. function shall fail if:
  77. .TP
  78. .BR EACCES
  79. Search permission is denied for a component of the path prefix.
  80. .TP
  81. .BR EIO
  82. An error occurred while reading from the file system.
  83. .TP
  84. .BR ELOOP
  85. A loop exists in symbolic links encountered during resolution of the
  86. .IR path
  87. argument.
  88. .TP
  89. .BR ENAMETOOLONG
  90. .br
  91. The length of a component of a pathname is longer than
  92. {NAME_MAX}.
  93. .TP
  94. .BR ENOENT
  95. A component of
  96. .IR path
  97. does not name an existing file or
  98. .IR path
  99. is an empty string.
  100. .TP
  101. .BR ENOTDIR
  102. A component of the path prefix names an existing file that is neither
  103. a directory nor a symbolic link to a directory, or the
  104. .IR path
  105. argument contains at least one non-\c
  106. <slash>
  107. character and ends with one or more trailing
  108. <slash>
  109. characters and the last pathname component names an existing file
  110. that is neither a directory nor a symbolic link to a directory.
  111. .P
  112. The
  113. \fIftok\fR()
  114. function may fail if:
  115. .TP
  116. .BR ELOOP
  117. More than
  118. {SYMLOOP_MAX}
  119. symbolic links were encountered during resolution of the
  120. .IR path
  121. argument.
  122. .TP
  123. .BR ENAMETOOLONG
  124. .br
  125. The length of a pathname exceeds
  126. {PATH_MAX},
  127. or pathname resolution of a symbolic link produced an intermediate
  128. result with a length that exceeds
  129. {PATH_MAX}.
  130. .LP
  131. .IR "The following sections are informative."
  132. .SH EXAMPLES
  133. .SS "Getting an IPC Key"
  134. .P
  135. The following example gets a key based on the pathname
  136. .BR /tmp
  137. and the ID value
  138. .IR a .
  139. It also assigns the value of the resulting key to the
  140. .IR semkey
  141. variable so that it will be available to a later call to
  142. \fIsemget\fR(),
  143. \fImsgget\fR(),
  144. or
  145. \fIshmget\fR().
  146. .sp
  147. .RS 4
  148. .nf
  150. #include <sys/ipc.h>
  151. \&...
  152. key_t semkey;
  153. .P
  154. if ((semkey = ftok("/tmp", \(aqa\(aq)) == (key_t) -1) {
  155.     perror("IPC error: ftok"); exit(1);
  156. }
  157. .fi
  158. .P
  159. .RE
  160. .SH "APPLICATION USAGE"
  161. For maximum portability,
  162. .IR id
  163. should be a single-byte character.
  164. .P
  165. Applications should not assume that the resulting key value is unique.
  166. .SH RATIONALE
  167. None.
  168. .SH "FUTURE DIRECTIONS"
  169. Future versions of this standard may add new interfaces to provide
  170. unique keys.
  171. .SH "SEE ALSO"
  172. .IR "\fImsgget\fR\^(\|)",
  173. .IR "\fIsemget\fR\^(\|)",
  174. .IR "\fIshmget\fR\^(\|)"
  175. .P
  176. The Base Definitions volume of POSIX.1\(hy2017,
  177. .IR "\fB<sys_ipc.h>\fP"
  178. .\"
  179. .SH COPYRIGHT
  180. Portions of this text are reprinted and reproduced in electronic form
  181. from IEEE Std 1003.1-2017, Standard for Information Technology
  182. -- Portable Operating System Interface (POSIX), The Open Group Base
  183. Specifications Issue 7, 2018 Edition,
  184. Copyright (C) 2018 by the Institute of
  185. Electrical and Electronics Engineers, Inc and The Open Group.
  186. In the event of any discrepancy between this version and the original IEEE and
  187. The Open Group Standard, the original IEEE and The Open Group Standard
  188. is the referee document. The original Standard can be obtained online at
  189. http://www.opengroup.org/unix/online.html .
  190. .PP
  191. Any typographical or formatting errors that appear
  192. in this page are most likely
  193. to have been introduced during the conversion of the source files to
  194. man page format. To report such errors, see
  195. https://www.kernel.org/doc/man-pages/reporting_bugs.html .