man3/grantpt.3

   1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
   2 .\" This page is in the public domain. - aeb
   3 .\" %%%LICENSE_END
   4 .\"
   5 .TH GRANTPT 3 2021-03-22 "GNU" "Linux Programmer's Manual"
   6 .SH NAME
   7 grantpt \- grant access to the slave pseudoterminal
   8 .SH SYNOPSIS
   9 .nf
  10 .B #include <stdlib.h>
  11 .PP
  12 .BI "int grantpt(int " fd ");"
  13 .fi
  14 .PP
  15 .RS -4
  16 Feature Test Macro Requirements for glibc (see
  17 .BR feature_test_macros (7)):
  18 .RE
  19 .PP
  20 .BR grantpt ():
  21 .nf
  22     Since glibc 2.24:
  23         _XOPEN_SOURCE >= 500
  24 .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
  25     Glibc 2.23 and earlier:
  26         _XOPEN_SOURCE
  27 .fi
  28 .SH DESCRIPTION
  29 The
  30 .BR grantpt ()
  31 function changes the mode and owner of the slave pseudoterminal device
  32 corresponding to the master pseudoterminal referred to by the file descriptor
  33 .IR fd .
  34 The user ID of the slave is set to the real UID of the calling process.
  35 The group ID is set to an unspecified value (e.g.,
  36 .IR tty ).
  37 The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-).
  38 .PP
  39 The behavior of
  40 .BR grantpt ()
  41 is unspecified if a signal handler is installed to catch
  42 .B SIGCHLD
  43 signals.
  44 .SH RETURN VALUE
  45 When successful,
  46 .BR grantpt ()
  47 returns 0.
  48 Otherwise, it returns \-1 and sets
  49 .I errno
  50 to indicate the error.
  51 .SH ERRORS
  52 .TP
  53 .B EACCES
  54 The corresponding slave pseudoterminal could not be accessed.
  55 .TP
  56 .B EBADF
  57 The
  58 .I fd
  59 argument is not a valid open file descriptor.
  60 .TP
  61 .B EINVAL
  62 The
  63 .I fd
  64 argument is valid but not associated with a master pseudoterminal.
  65 .SH VERSIONS
  66 .BR grantpt ()
  67 is provided in glibc since version 2.1.
  68 .SH ATTRIBUTES
  69 For an explanation of the terms used in this section, see
  70 .BR attributes (7).
  71 .ad l
  72 .nh
  73 .TS
  74 allbox;
  75 lbx lb lb
  76 l l l.
  77 Interface       Attribute       Value
  78 T{
  79 .BR grantpt ()
  80 T}      Thread safety   MT-Safe locale
  81 .TE
  82 .hy
  83 .ad
  84 .sp 1
  85 .SH CONFORMING TO
  86 POSIX.1-2001, POSIX.1-2008.
  87 .SH NOTES
  88 This is part of the UNIX 98 pseudoterminal support, see
  89 .BR pts (4).
  90 .PP
  91 Many systems implement this function via a set-user-ID helper binary
  92 called "pt_chown".
  93 On Linux systems with a devpts filesystem (present since Linux 2.2),
  94 the kernel normally sets the correct ownership and permissions
  95 for the pseudoterminal slave when the master is opened
  96 .RB ( posix_openpt (3)),
  97 so that nothing must be done by
  98 .BR grantpt ().
  99 Thus, no such helper binary is required
 100 (and indeed it is configured to be absent during the
 101 glibc build that is typical on many systems).
 102 .SH SEE ALSO
 103 .BR open (2),
 104 .BR posix_openpt (3),
 105 .BR ptsname (3),
 106 .BR unlockpt (3),
 107 .BR pts (4),
 108 .BR pty (7)