lib/libc/stdlib/ptsname.3

   1 .\" $NetBSD: ptsname.3,v 1.9 2014/01/10 09:43:15 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2004 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd January 7, 2014
  31 .Dt PTSNAME 3
  32 .Os
  33 .Sh NAME
  34 .Nm ptsname ,
  35 .Nm ptsname_r
  36 .Nd get the pathname of the slave pseudo-terminal device
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In stdlib.h
  41 .Ft char *
  42 .Fn ptsname "int masterfd"
  43 .Ft char *
  44 .Fn ptsname_r "int masterfd" "char *buf" "size_t buflen"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn ptsname
  48 function returns the pathname of the slave pseudo-terminal device
  49 that corresponds to the master pseudo-terminal device associated with
  50 .Fa masterfd .
  51 The
  52 .Fn ptsname
  53 function is not reentrant or thread-safe.
  54 .Pp
  55 The
  56 .Fn ptsname_r
  57 function
  58 places the pathname of the slave pseudo-terminal device that corresponds
  59 to the master pseudo-terminal device associated with
  60 .Fa masterfd
  61 int the
  62 .Fa buf
  63 argument copying up to
  64 .Fa buflen
  65 characters.
  66 The
  67 .Fa buf
  68 is always
  69 .Dv NUL
  70 terminated.
  71 .Sh RETURN VALUES
  72 If successful,
  73 .Fn ptsname
  74 returns a pointer to a nul-terminated string containing the pathname
  75 of the slave pseudo-terminal device.
  76 If an error occurs
  77 .Fn ptsname
  78 will return
  79 .Dv NULL
  80 and
  81 .Va errno
  82 is set to indicate the error.
  83 .Pp
  84 If successful,
  85 .Fn ptsname_r
  86 places a nul-terminated string containing the pathname
  87 of the slave pseudo-terminal device
  88 in
  89 .Fa buf
  90 and returns
  91 .Dv 0 .
  92 If an error occurs
  93 .Fn ptsname_r
  94 will return
  95 an error number number indicating what went wrong.
  96 .Sh ERRORS
  97 The
  98 .Fn ptsname
  99 and
 100 .Fn ptsname_r
 101 functions will fail if:
 102 .Bl -tag -width Er
 103 .It Bq Er EACCESS
 104 the corresponding pseudo-terminal device could not be accessed.
 105 .It Bq Er EBADF
 106 .Fa masterfd
 107 is not a valid descriptor.
 108 .It Bq Er EINVAL
 109 .Fa masterfd
 110 is not associated with a master pseudo-terminal device.
 111 .El
 112 .Pp
 113 In addition the
 114 .Fn ptsname_r
 115 function
 116 will return:
 117 .Bl -tag -width Er
 118 .It Bq Er EINVAL
 119 the
 120 .Fa buf
 121 argument is
 122 .Dv NULL .
 123 .It Bq Er ERANGE
 124 the name of the pseudo-terminal is longer than
 125 .Fa bufsiz
 126 characters plus the terminating
 127 .Dv NUL .
 128 .El
 129 .Sh NOTES
 130 The error returns of
 131 .Fn ptsname
 132 are a
 133 .Nx
 134 extension.
 135 The
 136 .Fn ptsname
 137 function is equivalent to:
 138 .Bd -literal
 139         struct ptmget pm;
 140         return ioctl(masterfd, TIOCPTSNAME, \*[Am]pm) == -1 ? NULL : pm.sn;
 141 .Ed
 142 .Pp
 143 Both the
 144 .Fn ptsname
 145 and
 146 .Fn ptsname_r
 147 functions will also return the name of the slave pseudo-terminal if a file
 148 descriptor to the slave pseudo-terminal is passed to
 149 .Fa masterfd .
 150 .Pp
 151 This is a convenient extension because it allows one to use the file descriptor
 152 obtained by
 153 .Xr open 2
 154 .Pa /dev/tty
 155 to obtain the name of the pseudo-terminal for the current process.
 156 .Sh SEE ALSO
 157 .Xr ioctl 2 ,
 158 .Xr open 2 ,
 159 .Xr grantpt 3 ,
 160 .Xr posix_openpt 3 ,
 161 .Xr unlockpt 3
 162 .Sh STANDARDS
 163 The
 164 .Fn ptsname
 165 function conforms to
 166 .St -p1003.1-2001 .
 167 Its first release was in
 168 .St -xpg4.2 .