1CTERMID(P)                 POSIX Programmer's Manual                CTERMID(P)
2
3
4

NAME

6       ctermid - generate a pathname for the controlling terminal
7

SYNOPSIS

9       #include <stdio.h>
10
11       char *ctermid(char *s);
12
13

DESCRIPTION

15       The  ctermid()  function  shall  generate a string that, when used as a
16       pathname, refers to the current controlling terminal  for  the  current
17       process.  If  ctermid()  returns  a pathname, access to the file is not
18       guaranteed.
19
20       If the application uses  any  of  the  _POSIX_THREAD_SAFE_FUNCTIONS  or
21       _POSIX_THREADS  functions,  it shall ensure that the ctermid() function
22       is called with a non-NULL parameter.
23

RETURN VALUE

25       If s is a null pointer, the string shall be generated in an  area  that
26       may  be  static  (and  therefore  may be overwritten by each call), the
27       address of which shall be returned. Otherwise, s is assumed to point to
28       a  character array of at least L_ctermid bytes; the string is placed in
29       this array and the value of s shall be returned. The symbolic  constant
30       L_ctermid  is defined in <stdio.h>, and shall have a value greater than
31       0.
32
33       The ctermid() function shall return an empty  string  if  the  pathname
34       that  would  refer to the controlling terminal cannot be determined, or
35       if the function is unsuccessful.
36

ERRORS

38       No errors are defined.
39
40       The following sections are informative.
41

EXAMPLES

43   Determining the Controlling Terminal for the Current Process
44       The following example returns a pointer to a string that identifies the
45       controlling terminal for the current process. The pathname for the ter‐
46       minal is stored in the array pointed to by the ptr argument, which  has
47       a size of L_ctermid bytes, as indicated by the term argument.
48
49
50              #include <stdio.h>
51              ...
52              char term[L_ctermid];
53              char *ptr;
54
55
56              ptr = ctermid(term);
57

APPLICATION USAGE

59       The  difference  between ctermid() and ttyname() is that ttyname() must
60       be handed a file descriptor and return a path of the  terminal  associ‐
61       ated  with that file descriptor, while ctermid() returns a string (such
62       as "/dev/tty" ) that refers to the current controlling terminal if used
63       as a pathname.
64

RATIONALE

66       L_ctermid  must be defined appropriately for a given implementation and
67       must be greater than zero so  that  array  declarations  using  it  are
68       accepted by the compiler. The value includes the terminating null byte.
69
70       Conforming  applications  that  use  threads cannot call ctermid() with
71       NULL  as  the  parameter  if  either  _POSIX_THREAD_SAFE_FUNCTIONS   or
72       _POSIX_THREADS  is  defined.  If  s is not NULL, the ctermid() function
73       generates a string that, when used as a pathname, refers to the current
74       controlling  terminal for the current process. If s is NULL, the return
75       value of ctermid() is undefined.
76
77       There is no additional burden on the programmer-changing to use a hypo‐
78       thetical  thread-safe version of ctermid() along with allocating a buf‐
79       fer is more of a burden than merely allocating  a  buffer.  Application
80       code  should  not  assume  that  the  returned string is short, as some
81       implementations have more than two pathname components before  reaching
82       a logical device name.
83

FUTURE DIRECTIONS

85       None.
86

SEE ALSO

88       ttyname()  ,  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
89       <stdio.h>
90
92       Portions of this text are reprinted and reproduced in  electronic  form
93       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
94       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
95       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
96       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
97       event of any discrepancy between this version and the original IEEE and
98       The Open Group Standard, the original IEEE and The Open Group  Standard
99       is  the  referee document. The original Standard can be obtained online
100       at http://www.opengroup.org/unix/online.html .
101
102
103
104IEEE/The Open Group                  2003                           CTERMID(P)
Impressum