When a PTY master is opened, the kernel creates the slave device file but its ownership and permissions may not be correct for the calling user. grantpt() fixes this.

Function Signature

#define _XOPEN_SOURCE 500
#include <stdlib.h>

int grantpt(int mfd);
/* Returns 0 on success, or -1 on error */

What grantpt() Changes on the Slave Device

How grantpt() Works Internally (non-Linux)

On systems where grantpt() is actually required to do work (not Linux), it forks a child process that executes a special set-user-ID-root helper program called pt_chown. This helper has root privilege and can change the device file’s ownership.

Why group=tty and group write permission?

The wall(1) and write(1) programs (which broadcast messages to all terminals) are set-group-ID programs owned by the tty group. To write a message to any terminal or PTY slave, they need write permission — the crw--w---- mode (group write allowed) gives them exactly that.

When a PTY master is first opened, the corresponding slave device has an internal kernel lock on it. unlockpt() removes that lock so that the slave can be opened by another process.

Function Signature

#define _XOPEN_SOURCE 500
#include <stdlib.h>

int unlockpt(int mfd);
/* Returns 0 on success, or -1 on error */

Why Is the Slave Locked in the First Place?

The locking mechanism ensures that the calling process can complete all initialization of the slave (such as calling grantpt() to fix permissions) before any other process is allowed to open it. Without this lock, a race condition could allow another process to open the slave before it is properly set up.

ptsname() returns the filesystem path of the slave device corresponding to the open master. You need this path to open() the slave.

Function Signature

#define _XOPEN_SOURCE 500
#include <stdlib.h>

char *ptsname(int mfd);
/* Returns pointer to slave device name string on success,
   or NULL on error */

What Name Does It Return?

On Linux (and most UNIX systems), ptsname() returns a string of the form:

/dev/pts/N

where N is the PTY number. For example /dev/pts/0, /dev/pts/7, etc. Each number uniquely identifies one PTY slave on the system at a given time.

Safe Usage Pattern

#define _XOPEN_SOURCE 500
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>

int open_pty_slave(int mfd)
{
    char *name;
    char slaveName[64];  /* our own buffer */

    name = ptsname(mfd);
    if (name == NULL) {
        perror("ptsname");
        return -1;
    }

    /* Copy immediately — the static buffer may be overwritten
       if ptsname() is called again elsewhere */
    strncpy(slaveName, name, sizeof(slaveName) - 1);
    slaveName[sizeof(slaveName) - 1] = '\0';

    printf("Slave device: %s\n", slaveName);

    return open(slaveName, O_RDWR | O_NOCTTY);
}

Thread-Safe Version: ptsname_r()

On Linux you can use the GNU extension ptsname_r() to write into a caller-supplied buffer, avoiding the static-buffer problem entirely:

#define _GNU_SOURCE
#include <stdlib.h>

/* ptsname_r() writes into buf instead of a static internal buffer */
int ptsname_r(int mfd, char *buf, size_t buflen);
/* Returns 0 on success, or a positive error number on error */

/* Usage: */
char slaveName[64];
if (ptsname_r(mfd, slaveName, sizeof(slaveName)) != 0) {
    perror("ptsname_r");
}

This program opens a full PTY pair using the standard four-step sequence, then writes a message from the master and reads it on the slave to prove the pair works.

#define _XOPEN_SOURCE 600
#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <errno.h>

static int open_master(void)
{
    int mfd = posix_openpt(O_RDWR | O_NOCTTY);
    if (mfd == -1) { perror("posix_openpt"); exit(1); }
    return mfd;
}

static int prepare_slave(int mfd, char *slaveBuf, size_t bufLen)
{
    /* Step 2: fix slave permissions */
    if (grantpt(mfd) == -1)  { perror("grantpt");  return -1; }

    /* Step 3: unlock the slave */
    if (unlockpt(mfd) == -1) { perror("unlockpt"); return -1; }

    /* Step 4a: get slave name — copy immediately out of static buffer */
    if (ptsname_r(mfd, slaveBuf, bufLen) != 0) {
        perror("ptsname_r"); return -1;
    }
    return 0;
}

int main(void)
{
    char slaveName[64];
    int  mfd, sfd;
    char writeBuf[] = "Hello from master!\n";
    char readBuf[64];
    ssize_t n;

    /* Step 1 */
    mfd = open_master();
    printf("Master fd: %d\n", mfd);

    /* Steps 2, 3, 4a */
    if (prepare_slave(mfd, slaveName, sizeof(slaveName)) == -1)
        exit(1);
    printf("Slave device: %s\n", slaveName);

    /* Step 4b: open the slave */
    sfd = open(slaveName, O_RDWR | O_NOCTTY);
    if (sfd == -1) { perror("open slave"); close(mfd); exit(1); }
    printf("Slave fd: %d\n", sfd);

    /* Write from master -> read on slave */
    if (write(mfd, writeBuf, strlen(writeBuf)) == -1) {
        perror("write master"); goto cleanup;
    }

    memset(readBuf, 0, sizeof(readBuf));
    n = read(sfd, readBuf, sizeof(readBuf) - 1);
    if (n == -1) { perror("read slave"); goto cleanup; }
    printf("Slave read: %s", readBuf);

    /* Write from slave -> read on master */
    if (write(sfd, "Hello from slave!\n", 18) == -1) {
        perror("write slave"); goto cleanup;
    }
    memset(readBuf, 0, sizeof(readBuf));
    n = read(mfd, readBuf, sizeof(readBuf) - 1);
    if (n == -1) { perror("read master"); goto cleanup; }
    printf("Master read: %s", readBuf);

cleanup:
    close(sfd);
    close(mfd);
    return 0;
}

gcc -o pty_full pty_full.c
./pty_full
# Master fd: 3
# Slave device: /dev/pts/8
# Slave fd: 4
# Slave read: Hello from master!
# Master read: Hello from slave!

What the Slave Device Looks Like After grantpt()

$ ls -l /dev/pts/7
crw--w---- 1 ravi tty 136, 7 Jun 18 10:30 /dev/pts/7
#  ^           ^    ^
#  |           |    +-- Group: tty
#  |           +------- Owner: ravi (the user who called posix_openpt)
#  +------------------- Character device, owner=rw, group=w, other=none