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

ctermid.3p (4584B)

    

  1. '\" et
  2. .TH CTERMID "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. ctermid
  12. \(em generate a pathname for the controlling terminal
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. char *ctermid(char *\fIs\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIctermid\fR()
  23. function shall generate a string that, when used as a pathname,
  24. refers to the current controlling terminal for the current process. If
  25. \fIctermid\fR()
  26. returns a pathname, access to the file is not guaranteed.
  27. .P
  28. The
  29. \fIctermid\fR()
  30. function need not be thread-safe if called with a NULL parameter.
  31. .SH "RETURN VALUE"
  32. If
  33. .IR s
  34. is a null pointer, the string shall be generated in an area that may be
  35. static, the address of which shall be returned. The application shall
  36. not modify the string returned. The returned pointer might be invalidated
  37. or the string content might be overwritten by a subsequent call to
  38. \fIctermid\fR().
  39. The returned pointer might also be invalidated if the calling thread
  40. is terminated.
  41. If
  42. .IR s
  43. is not a null pointer,
  44. .IR s
  45. is assumed to point to a character array of at least L_ctermid bytes;
  46. the string is placed in this array and the value of
  47. .IR s
  48. shall be returned. The symbolic constant L_ctermid is defined in
  49. .IR <stdio.h> ,
  50. and shall have a value greater than 0.
  51. .P
  52. The
  53. \fIctermid\fR()
  54. function shall return an empty string if the pathname that would refer
  55. to the controlling terminal cannot be determined, or if the function is
  56. unsuccessful.
  57. .SH ERRORS
  58. No errors are defined.
  59. .LP
  60. .IR "The following sections are informative."
  61. .SH EXAMPLES
  62. .SS "Determining the Controlling Terminal for the Current Process"
  63. .P
  64. The following example returns a pointer to a string that identifies the
  65. controlling terminal for the current process. The pathname for the
  66. terminal is stored in the array pointed to by the
  67. .IR ptr
  68. argument, which has a size of L_ctermid bytes, as indicated by the
  69. .IR term
  70. argument.
  71. .sp
  72. .RS 4
  73. .nf
  75. #include <stdio.h>
  76. \&...
  77. char term[L_ctermid];
  78. char *ptr;
  79. .P
  80. ptr = ctermid(term);
  81. .fi
  82. .P
  83. .RE
  84. .SH "APPLICATION USAGE"
  85. The difference between
  86. \fIctermid\fR()
  87. and
  88. \fIttyname\fR()
  89. is that
  90. \fIttyname\fR()
  91. must be handed a file descriptor and return a path of the terminal
  92. associated with that file descriptor, while
  93. \fIctermid\fR()
  94. returns a string (such as
  95. .BR \(dq/dev/tty\(dq )
  96. that refers to the current controlling terminal if used as a
  97. pathname.
  98. .SH RATIONALE
  99. L_ctermid
  100. must be defined appropriately for a given implementation and must be
  101. greater than zero so that array declarations using it are accepted by
  102. the compiler. The value includes the terminating null byte.
  103. .P
  104. Conforming applications that use multiple threads cannot call
  105. \fIctermid\fR()
  106. with NULL as the parameter. If
  107. .IR s
  108. is not NULL, the
  109. \fIctermid\fR()
  110. function generates a string that, when used as a pathname, refers to
  111. the current controlling terminal for the current process. If
  112. .IR s
  113. is NULL, the return value of
  114. \fIctermid\fR()
  115. is undefined.
  116. .P
  117. There is no additional burden on the programmer\(emchanging to use a
  118. hypothetical thread-safe version of
  119. \fIctermid\fR()
  120. along with allocating a buffer is more of a burden than merely
  121. allocating a buffer. Application code should not assume that the
  122. returned string is short, as some implementations have more than two
  123. pathname components before reaching a logical device name.
  124. .SH "FUTURE DIRECTIONS"
  125. None.
  126. .SH "SEE ALSO"
  127. .IR "\fIttyname\fR\^(\|)"
  128. .P
  129. The Base Definitions volume of POSIX.1\(hy2017,
  130. .IR "\fB<stdio.h>\fP"
  131. .\"
  132. .SH COPYRIGHT
  133. Portions of this text are reprinted and reproduced in electronic form
  134. from IEEE Std 1003.1-2017, Standard for Information Technology
  135. -- Portable Operating System Interface (POSIX), The Open Group Base
  136. Specifications Issue 7, 2018 Edition,
  137. Copyright (C) 2018 by the Institute of
  138. Electrical and Electronics Engineers, Inc and The Open Group.
  139. In the event of any discrepancy between this version and the original IEEE and
  140. The Open Group Standard, the original IEEE and The Open Group Standard
  141. is the referee document. The original Standard can be obtained online at
  142. http://www.opengroup.org/unix/online.html .
  143. .PP
  144. Any typographical or formatting errors that appear
  145. in this page are most likely
  146. to have been introduced during the conversion of the source files to
  147. man page format. To report such errors, see
  148. https://www.kernel.org/doc/man-pages/reporting_bugs.html .