original/man3/ptsname.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\" This page is in the public domain. - aeb
   3 .\"
   4 .\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS
   5 .\"
   6 .TH PTSNAME 3 2008-09-03 "" "Linux Programmer's Manual"
   7 .SH NAME
   8 ptsname, ptsname_r \- get the name of the slave pseudo-terminal
   9 .SH SYNOPSIS
  10 .nf
  11 .B #define _XOPEN_SOURCE
  12 .br
  13 .B #include <stdlib.h>
  14 .sp
  15 .BI "char *ptsname(int " fd ");"
  16 .sp
  17 .B #define _GNU_SOURCE
  18 .br
  19 .B #include <stdlib.h>
  20 .sp
  21 .BI "int ptsname_r(int " fd ", char *" buf ", size_t " buflen ");"
  22 .fi
  23 .SH DESCRIPTION
  24 The
  25 .BR ptsname ()
  26 function returns the name of the slave pseudo-terminal (pty) device
  27 corresponding to the master referred to by
  28 .IR fd .
  29
  30 The
  31 .BR ptsname_r ()
  32 function is the reentrant equivalent of
  33 .BR ptsname ().
  34 It returns the name of the slave pseudo-terminal device as a
  35 null-terminated string in the buffer pointed to by
  36 .IR buf .
  37 The
  38 .I buflen
  39 argument specifies the number of bytes available in
  40 .IR buf .
  41 .SH "RETURN VALUE"
  42 On success,
  43 .BR ptsname ()
  44 returns a pointer to a string in static storage which will be
  45 overwritten by subsequent calls.
  46 This pointer must not be freed.
  47 On failure, a NULL pointer is returned.
  48
  49 On success,
  50 .BR ptsname_r ()
  51 returns 0.
  52 On failure, a nonzero value is returned
  53 and
  54 .I errno
  55 is set to indicate the error.
  56 .\" In fact the errno value is also returned as the function
  57 .\" result -- MTK, Dec 04
  58 .SH ERRORS
  59 .TP
  60 .B EINVAL
  61 .RB ( ptsname_r ()
  62 only)
  63 .I buf
  64 is NULL.
  65 .TP
  66 .B ENOTTY
  67 .I fd
  68 does not refer to a pseudo-terminal master device.
  69 .TP
  70 .B ERANGE
  71 .RB ( ptsname_r ()
  72 only)
  73 .I buf
  74 is too small.
  75 .SH VERSIONS
  76 .BR ptsname ()
  77 is provided in glibc since version 2.1.
  78 .SH "CONFORMING TO"
  79 .BR ptsname ()
  80 is part of the Unix98 pseudo-terminal support (see
  81 .BR pts (4)).
  82 This function is specified in POSIX.1-2001.
  83
  84 .BR ptsname_r ()
  85 is a Linux extension.
  86 A version of this function is documented on Tru64 and HP-UX, but
  87 on those implementations, \-1 is returned on error, with
  88 .I errno
  89 set to indicate the error.
  90 Avoid using this function in portable programs.
  91 .SH "SEE ALSO"
  92 .BR grantpt (3),
  93 .BR posix_openpt (3),
  94 .BR ttyname (3),
  95 .BR unlockpt (3),
  96 .BR pts (4),
  97 .BR feature_test_macros (7),
  98 .BR pty (7)