POSIX threads are referenced by an ID of type pthread_t. A thread can find out its ID by calling pthread_self.

SYNOPSIS

  #include <pthread.h>

  pthread_t pthread_self(void);
                                          POSIX:THR

The pthread_self function returns the thread ID of the calling thread. No errors are defined for pthread_self.

Since pthread_t may be a structure, use pthread_equal to compare thread IDs for equality. The parameters of pthread_equal are the thread IDs to be compared.

SYNOPSIS

   #include <pthread.h>

   pthread_t pthread_equal(thread_t t1, pthread_t t2);
                                                              POSIX:THR

If t1 equals t2, pthread_equal returns a nonzero value. If the thread IDs are not equal, pthread_equal returns 0. No errors are defined for pthread_equal.

pthread_t mytid;

if (pthread_equal(pthread_self(), mytid))
   printf("My thread ID matches mytid
");

The pthread_create function creates a thread. Unlike some thread facilities, such as those provided by the Java programming language, the POSIX pthread_create automatically makes the thread runnable without requiring a separate start operation. The thread parameter of pthread_create points to the ID of the newly created thread. The attr parameter represents an attribute object that encapsulates the attributes of a thread. If attr is NULL, the new thread has the default attributes. Section 12.6 discusses the setting of thread attributes. The third parameter, start_routine, is the name of a function that the thread calls when it begins execution. The start_routine takes a single parameter specified by arg, a pointer to void. The start_routine returns a pointer to void, which is treated as an exit status by pthread_join.

SYNOPSIS

  #include <pthread.h>

  int pthread_create(pthread_t *restrict thread,
                     const pthread_attr_t *restrict attr,
                     void *(*start_routine)(void *), void *restrict arg);
                                                                             POSIX:THR

If successful, pthread_create returns 0. If unsuccessful, pthread_create returns a nonzero error code. The following table lists the mandatory errors for pthread_create.

Do not let the prototype of pthread_create intimidate you—threads are easy to create and use.

void *processfd(void *arg);

int error;
int fd;
pthread_t tid;

if ((fd = open("my.dat", O_RDONLY)) == -1)
   perror("Failed to open my.dat");
else if (error = pthread_create(&tid, NULL, processfd, &fd))
   fprintf(stderr, "Failed to create thread: %s
", strerror(error));
else
   printf("Thread created
");

When a thread exits, it does not release its resources unless it is a detached thread. The pthread_detach function sets a thread’s internal options to specify that storage for the thread can be reclaimed when the thread exits. Detached threads do not report their status when they exit. Threads that are not detached are joinable and do not release all their resources until another thread calls pthread_join for them or the entire process exits. The pthread_join function causes the caller to wait for the specified thread to exit, similar to waitpid at the process level. To prevent memory leaks, long-running programs should eventually call either pthread_detach or pthread_join for every thread.

The pthread_detach function has a single parameter, thread, the thread ID of the thread to be detached.

SYNOPSIS

   #include <pthread.h>

   int pthread_detach(pthread_t thread);
                                                     POSIX:THR

If successful, pthread_detach returns 0. If unsuccessful, pthread_detach returns a nonzero error code. The following table lists the mandatory errors for pthread_detach.

void *processfd(void *arg);

int error;
int fd
pthread_t tid;

if (error = pthread_create(&tid, NULL, processfd, &fd))
   fprintf(stderr, "Failed to create thread: %s
", strerror(error));
else if (error = pthread_detach(tid))
   fprintf(stderr, "Failed to detach thread: %s
", strerror(error));

#include <pthread.h>
#include <stdio.h>

void *detachfun(void *arg) {
    int i = *((int *)(arg));
    if (!pthread_detach(pthread_self()))
        return NULL;
    fprintf(stderr, "My argument is %d
", i);
    return NULL;
}

A nondetached thread’s resources are not released until another thread calls pthread_join with the ID of the terminating thread as the first parameter. The pthread_join function suspends the calling thread until the target thread, specified by the first parameter, terminates. The value_ptr parameter provides a location for a pointer to the return status that the target thread passes to pthread_exit or return. If value_ptr is NULL, the caller does not retrieve the target thread return status.

SYNOPSIS

   #include <pthread.h>

   int pthread_join(pthread_t thread, void **value_ptr);
                                                          POSIX:THR

If successful, pthread_join returns 0. If unsuccessful, pthread_join returns a nonzero error code. The following table lists the mandatory errors for pthread_join.

int error;
int *exitcodep;
pthread_t tid;

if (error = pthread_join(tid, &exitcodep))
   fprintf(stderr, "Failed to join thread: %s
", strerror(error));
else
   fprintf(stderr, "The exit code was %d
", *exitcodep);

pthread_join(pthread_self());

Calling pthread_join is not the only way for the main thread to block until the other threads have completed. The main thread can use a semaphore or one of the methods discussed in Section 16.6 to wait for all threads to finish.

The process can terminate by calling exit directly, by executing return from main, or by having one of the other process threads call exit. In any of these cases, all threads terminate. If the main thread has no work to do after creating other threads, it should either block until all threads have completed or call pthread_exit(NULL).

A call to exit causes the entire process to terminate; a call to pthread_exit causes only the calling thread to terminate. A thread that executes return from its top level implicitly calls pthread_exit with the return value (a pointer) serving as the parameter to pthread_exit. A process will exit with a return status of 0 if its last thread calls pthread_exit.

The value_ptr value is available to a successful pthread_join. However, the value_ptr in pthread_exit must point to data that exists after the thread exits, so the thread should not use a pointer to automatic local data for value_ptr.

SYNOPSIS

   #include <pthread.h>

   void pthread_exit(void *value_ptr);
                                                         POSIX:THR

POSIX does not define any errors for pthread_exit.

Threads can force other threads to return through the cancellation mechanism. A thread calls pthread_cancel to request that another thread be canceled. The target thread’s type and cancellability state determine the result. The single parameter of pthread_cancel is the thread ID of the target thread to be canceled. The pthread_cancel function does not cause the caller to block while the cancellation completes. Rather, pthread_cancel returns after making the cancellation request.

SYNOPSIS

   #include <pthread.h>

   int pthread_cancel(pthread_t thread);
                                                        POSIX:THR

If successful, pthread_cancel returns 0. If unsuccessful, pthread_cancel returns a nonzero error code. No mandatory errors are defined for pthread_cancel.

What happens when a thread receives a cancellation request depends on its state and type. If a thread has the PTHREAD_CANCEL_ENABLE state, it receives cancellation requests. On the other hand, if the thread has the PTHREAD_CANCEL_DISABLE state, the cancellation requests are held pending. By default, threads have the PTHREAD_CANCEL_ENABLE state.

The pthread_setcancelstate function changes the cancellability state of the calling thread. The pthread_setcancelstate takes two parameters: state, specifying the new state to set; and oldstate, a pointer to an integer for holding the previous state.

SYNOPSIS

   #include <pthread.h>

   int pthread_setcancelstate(int state, int *oldstate);
                                                            POSIX:THR

If successful, pthread_setcancelstate returns 0. If unsuccessful, it returns a nonzero error code. No mandatory errors are defined for pthread_setcancelstate.

Program 12.3 shows a modification of the processfd function of Program 12.1 that explicitly disables cancellation before it calls docommand, to ensure that the command won’t be canceled midstream. The original processfd always returns NULL. The processfdcancel function returns a pointer other than NULL if it cannot change the cancellation state. This function should not return a pointer to an automatic local variable, since local variables are deallocated when the function returns or the thread exits. Program 12.3 uses a parameter passed by the calling thread to return the pointer.

#include <pthread.h>
#include "restart.h"
#define BUFSIZE 1024

void docommand(char *cmd, int cmdsize);

void *processfdcancel(void *arg) { /* process commands with cancellation */
   char buf[BUFSIZE];
   int fd;
   ssize_t nbytes;
   int newstate, oldstate;

   fd = *((int *)(arg));
   for ( ; ; )  {
      if ((nbytes = r_read(fd, buf, BUFSIZE)) <= 0)
         break;
      if (pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &oldstate))
         return arg;
      docommand(buf, nbytes);
      if (pthread_setcancelstate(oldstate, &newstate))
         return arg;
   }
   return NULL;
}

As a general rule, a function that changes its cancellation state or its type should restore the value before returning. A caller cannot make reliable assumptions about the program behavior unless this rule is observed. The processfdcancel function saves the old state and restores it rather than just enabling cancellation after calling docommand.

Cancellation can cause difficulties if a thread holds resources such as a lock or an open file descriptor that must be released before exiting. A thread maintains a stack of cleanup routines using pthread_cleanup_push and pthread_cleanup_pop. (We do not discuss these here.) Although a canceled thread can execute a cleanup function before exiting (not discussed here), it is not always feasible to release resources in an exit handler. Also, there may be points in the execution at which an exit would leave the program in an unacceptable state. The cancellation type allows a thread to control the point when it exits in response to a cancellation request. When its cancellation type is PTHREAD_CANCEL_ASYNCHRONOUS, the thread can act on the cancellation request at any time. In contrast, a cancellation type of PTHREAD_CANCEL_DEFERRED causes the thread to act on cancellation requests only at specified cancellation points. By default, threads have the PTHREAD_CANCEL_DEFERRED type.

The pthread_setcanceltype function changes the cancellability type of a thread as specified by its type parameter. The oldtype parameter is a pointer to a location for saving the previous type. A thread can set a cancellation point at a particular place in the code by calling pthread_testcancel. Certain blocking functions, such as read, are automatically treated as cancellation points. A thread with the PTHREAD_CANCEL_DEFERRED type accepts pending cancellation requests when it reaches such a cancellation point.

SYNOPSIS

   #include <pthread.h>

   int pthread_setcanceltype(int type, int *oldtype);
   void pthread_testcancel(void);
                                                       POSIX:THR

If successful, pthread_setcanceltype returns 0. If unsuccessful, it returns a nonzero error code. No mandatory errors are defined for pthread_setcanceltype. The pthread_testcancel has no return value.

The creator of a thread may pass a single parameter to a thread at creation time, using a pointer to void. To communicate multiple values, the creator must use a pointer to an array or a structure. Program 12.4 illustrates how to pass a pointer to an array. The main program passes an array containing two open file descriptors to a thread that runs copyfilemalloc.

#include <errno.h>
#include <fcntl.h>
#include <pthread.h>
#include <stdio.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#define PERMS (S_IRUSR | S_IWUSR)
#define READ_FLAGS O_RDONLY
#define WRITE_FLAGS (O_WRONLY | O_CREAT | O_TRUNC)

void *copyfilemalloc(void *arg);

int main (int argc, char *argv[]) {        /* copy fromfile to tofile */
   int *bytesptr;
   int error;
   int fds[2];
   pthread_t tid;

   if (argc != 3) {
      fprintf(stderr, "Usage: %s fromfile tofile
", argv[0]);
      return 1;
   }
   if (((fds[0] = open(argv[1], READ_FLAGS)) == -1) ||
       ((fds[1] = open(argv[2], WRITE_FLAGS, PERMS)) == -1)) {
      perror("Failed to open the files");
      return 1;
   }
   if (error = pthread_create(&tid, NULL, copyfilemalloc, fds)) {
      fprintf(stderr, "Failed to create thread: %s
", strerror(error));
      return 1;
   }
   if (error = pthread_join(tid, (void **)&bytesptr)) {
      fprintf(stderr, "Failed to join thread: %s
", strerror(error));
      return 1;
   }
   printf("Number of bytes copied: %d
", *bytesptr);
   return 0;
}

Program 12.5 shows an implementation of copyfilemalloc, a function that reads from one file and outputs to another file. The arg parameter holds a pointer to a pair of open descriptors representing the source and destination files. The variables bytesp, infd and outfd are allocated on copyfilemalloc’s local stack and are not directly accessible to other threads.

Program 12.5 also illustrates a strategy for returning values from the thread. The thread allocates memory space for returning the total number of bytes copied since it is not allowed to return a pointer to its local variables. POSIX requires that malloc be thread-safe. The copyfilemalloc function returns the bytesp pointer, which is equivalent to calling pthread_exit. It is the responsibility of the calling program (callcopymalloc) to free this space when it has finished using it. In this case, the program terminates, so it is not necessary to call free.

#include <stdlib.h>
#include <unistd.h>
#include "restart.h"

void *copyfilemalloc(void *arg)  { /* copy infd to outfd with return value */
   int *bytesp;
   int infd;
   int outfd;

   infd = *((int *)(arg));
   outfd = *((int *)(arg) + 1);
   if ((bytesp = (int *)malloc(sizeof(int))) == NULL)
      return NULL;
   *bytesp = copyfile(infd, outfd);
   r_close(infd);
   r_close(outfd);
   return bytesp;
}

When a thread allocates space for a return value, some other thread is responsible for freeing that space. Whenever possible, a thread should clean up its own mess rather than requiring another thread to do it. It is also inefficient to dynamically allocate space to hold a single integer. An alternative to having the thread allocate space for the return value is for the creating thread to do it and pass a pointer to this space in the argument parameter of the thread. This approach avoids dynamic allocation completely if the space is on the stack of the creating thread.

Program 12.6 creates a copyfilepass thread to copy a file. The parameter to the thread is now an array of size 3. The first two entries of the array hold the file descriptors as in Program 12.4. The third array element stores the number of bytes copied. Program 12.6 can retrieve this value either through the array or through the second parameter of pthread_join. Alternatively, callcopypass could pass an array of size 2, and the thread could store the return value over one of the incoming file descriptors.

#include <errno.h>
#include <fcntl.h>
#include <pthread.h>
#include <stdio.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#define PERMS (S_IRUSR | S_IWUSR)
#define READ_FLAGS O_RDONLY
#define WRITE_FLAGS (O_WRONLY | O_CREAT | O_TRUNC)
void *copyfilepass(void *arg);

int main (int argc, char *argv[]) {
   int *bytesptr;
   int error;
   int targs[3];
   pthread_t tid;

   if (argc != 3) {
      fprintf(stderr, "Usage: %s fromfile tofile
", argv[0]);
      return 1;
   }

   if (((targs[0] = open(argv[1], READ_FLAGS)) == -1) ||
       ((targs[1] = open(argv[2], WRITE_FLAGS, PERMS)) == -1)) {
      perror("Failed to  open the files");
      return 1;
   }
   if (error = pthread_create(&tid, NULL, copyfilepass, targs)) {
      fprintf(stderr, "Failed to create thread: %s
", strerror(error));
      return 1;
   }
   if (error = pthread_join(tid, (void **)&bytesptr)) {
      fprintf(stderr, "Failed to join thread: %s
", strerror(error));
      return 1;
   }
   printf("Number of bytes copied: %d
", *bytesptr);
   return 0;
}

The copyfilepass function of Program 12.7 uses an alternative way of accessing the pieces of the argument. Compare this with the method used by the copyfilemalloc function of Program 12.5.

#include <unistd.h>
#include "restart.h"

void *copyfilepass(void *arg)  {
   int *argint;

   argint = (int *)arg;
   argint[2] = copyfile(argint[0], argint[1]);
   r_close(argint[0]);
   r_close(argint[1]);
   return argint + 2;
}

When creating multiple threads, do not reuse the variable holding a thread’s parameter until you are sure that the thread has finished accessing the parameter. Because the variable is passed by reference, it is a good practice to use a separate variable for each thread.

#include <errno.h>
#include <fcntl.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#define MAXNAME 80
#define R_FLAGS O_RDONLY
#define W_FLAGS (O_WRONLY | O_CREAT)
#define W_PERMS (S_IRUSR | S_IWUSR)

typedef struct {
   int args[3];
   pthread_t tid;
} copy_t;

void *copyfilepass(void *arg);

int main(int argc, char *argv[]) {
   int *bytesp;
   copy_t *copies;
   int error;
   char filename[MAXNAME];
   int i;
   int numcopiers;
   int totalbytes = 0;

   if (argc != 4) {
      fprintf(stderr, "Usage: %s infile outfile copies
", argv[0]);
      return 1;
   }
   numcopiers = atoi(argv[3]);
   if ((copies = (copy_t *)calloc(numcopiers, sizeof(copy_t))) == NULL) {
      perror("Failed to allocate copier space");
      return 1;
   }
              /* open the source and destination files and create the threads */
   for (i = 0; i < numcopiers; i++) {
      copies[i].tid = pthread_self();       /* cannot be value for new thread */
      if (snprintf(filename, MAXNAME, "%s.%d", argv[1], i+1) == MAXNAME) {
         fprintf(stderr, "Input filename %s.%d too long", argv[1], i + 1);
         continue;
      }
      if ((copies[i].args[0] = open(filename, R_FLAGS)) == -1) {
         fprintf(stderr, "Failed to open source file %s: %s
",
                         filename, strerror(errno));
         continue;
      }
     if (snprintf(filename, MAXNAME, "%s.%d", argv[2], i+1) == MAXNAME) {
         fprintf(stderr, "Output filename %s.%d too long", argv[2], i + 1);
         continue;
      }
      if ((copies[i].args[1] = open(filename, W_FLAGS, W_PERMS)) == -1) {
         fprintf(stderr, "Failed to open destination file %s: %s
",
                         filename, strerror(errno));
         continue;
      }
      if (error = pthread_create((&copies[i].tid), NULL,
                                  copyfilepass, copies[i].args)) {
         fprintf(stderr, "Failed to create thread %d: %s
", i + 1,
                 strerror(error));
         copies[i].tid = pthread_self();    /* cannot be value for new thread */
      }

   }
                     /* wait for the threads to finish and report total bytes */
   for (i = 0; i < numcopiers; i++) {
      if (pthread_equal(copies[i].tid, pthread_self()))        /* not created */
         continue;
      if (error = pthread_join(copies[i].tid, (void**)&bytesp)) {
         fprintf(stderr, "Failed to join thread %d
", i);
         continue;
      }
      if (bytesp == NULL) {
         fprintf(stderr, "Thread %d failed to return status
", i);
         continue;
      }
      printf("Thread %d copied %d bytes from %s.%d to %s.%d
",
             i, *bytesp, argv[1], i + 1, argv[2], i + 1);
      totalbytes += *bytesp;
   }
   printf("Total bytes copied = %d
", totalbytes);
   return 0;
}

Program 12.9 shows a simple example of what can go wrong. The program creates 10 threads that each output the value of their parameter. The main program uses the thread creation loop index i as the parameter it passes to the threads. Each thread prints the value of the parameter it received. A thread can get an incorrect value if the main program changes i before the thread has a chance to print it.

#include <pthread.h>
#include <stdio.h>
#include <string.h>
#define NUMTHREADS 10

static void *printarg(void *arg) {
   fprintf(stderr, "Thread received %d
", *(int *)arg);
   return NULL;
}

int main (void) {        /* program incorrectly passes parameters to threads */
   int error;
   int i;
   int j;
   pthread_t tid[NUMTHREADS];

   for (i = 0; i < NUMTHREADS; i++)
      if (error = pthread_create(tid + i, NULL, printarg, (void *)&i)) {
         fprintf(stderr, "Failed to create thread: %s
", strerror(error));
         tid[i] = pthread_self();
      }
   for (j = 0; j < NUMTHREADS; j++)
      if (pthread_equal(pthread_self(), tid[j]))
         continue;
      if (error = pthread_join(tid[j], NULL))
         fprintf(stderr, "Failed to join thread: %s
", strerror(error));
   printf("All threads done
");
   return 0;
}

#include <errno.h>
#include <pthread.h>
#include <stdlib.h>
#include <string.h>

void *whichexit(void *arg) {
   int n;
   int np1[1];
   int *np2;
   char s1[10];
   char s2[] = "I am done";
   n = 3;
   np1[0] = n;
   np2 = (int *)malloc(sizeof(int *));
   *np2 = n;
   strcpy(s1, "Done");
   return(NULL);
}

The pthread_attr_getdetachstate function examines the state of an attribute object, and the pthread_attr_setdetachstate function sets the state of an attribute object. The possible values of the thread state are PTHREAD_CREATE_JOINABLE and PTHREAD_CREATE_DETACHED. The attr parameter is a pointer to the attribute object. The detachstate parameter corresponds to the value to be set for pthread_attr_setdetachstate and to a pointer to the value to be retrieved for pthread_attr_getdetachstate.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getdetachstate(const pthread_attr_t *attr,
                                  int *detachstate);
  int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);
                                                                   POSIX:THR

If successful, these functions return 0. If unsuccessful, they return a nonzero error code. The pthread_attr_setdetachstate function sets errno to EINVAL if detachstate is invalid.

Detached threads release their resources when they terminate, whereas joinable threads should be waited for with a pthread_join. A thread that is detached cannot be waited for with a pthread_join. By default, threads are joinable. You can detach a thread by calling the pthread_detach function after creating the thread. Alternatively, you can create a thread in the detached state by using an attribute object with thread state PTHREAD_CREATE_DETACHED.

int error, fd;
pthread_attr_t tattr;
pthread_t tid;

if (error = pthread_attr_init(&tattr))
   fprintf(stderr, "Failed to create attribute object: %s
",
                    strerror(error));
else if (error = pthread_attr_setdetachstate(&tattr,
                 PTHREAD_CREATE_DETACHED))
   fprintf(stderr, "Failed to set attribute state to detached: %s
",
           strerror(error));
else if (error = pthread_create(&tid, &tattr, processfd, &fd))
   fprintf(stderr, "Failed to create thread: %s
", strerror(error));

A thread has a stack whose location and size are user-settable, a useful property if the thread stack must be placed in a particular region of memory. To define the placement and size of the stack for a thread, you must first create an attribute object with the specified stack attributes. Then, call pthread_create with this attribute object.

The pthread_attr_getstack function examines the stack parameters, and the pthread_attr_setstack function sets the stack parameters of an attribute object. The attr parameter of each function is a pointer to the attribute object. The pthread_attr_setstack function takes the stack address and stack size as additional parameters. The pthread_attr_getstack takes pointers to these items.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getstack(const pthread_attr_t *restrict attr,
           void **restrict stackaddr, size_t *restrict stacksize);
  int pthread_attr_setstack(pthread_attr_t *attr,
           void *stackaddr, size_t stacksize);
                                                            POSIX:THR,TSA,TSS

If successful, the pthread_attr_getstack and pthread_attr_setstack functions return 0. If unsuccessful, these functions return a nonzero error code. The pthread_attr_setstack function sets errno to EINVAL if stacksize is out of range.

POSIX also provides functions for examining or setting a guard for stack overflows if the stackaddr has not been set by the user. The pthread_attr_getguardsize function examines the guard parameters, and the pthread_attr_setguardsize function sets the guard parameters for controlling stack overflows in an attribute object. If the guardsize parameter is 0, the stack is unguarded. For a nonzero guardsize, the implementation allocates additional memory of at least guardsize. An overflow into this extra memory causes an error and may generate a SIGSEGV signal for the thread.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getguardsize(const pthread_attr_t *restrict attr,
                            size_t *restrict guardsize);
  int pthread_attr_setguardsize(pthread_attr_t *attr,
                            size_t guardsize);
                                                                 POSIX:THR,XSI

If successful, pthread_attr_getguardsize and pthread_attr_setguardsize return 0. If unsuccessful, these functions return a nonzero error code. They return EINVAL if the attr or guardsize parameter is invalid. Guards require the POSIX:THR Extension and the POSIX:XSI Extension.

The contention scope of an object controls whether the thread competes within the process or at the system level for scheduling resources. The pthread_attr_getscope examines the contention scope, and the pthread_attr_setscope sets the contention scope of an attribute object. The attr parameter is a pointer to the attribute object. The contentionscope parameter corresponds to the value to be set for pthread_attr_setscope and to a pointer to the value to be retrieved for pthread_attr_getscope. The possible values of the contentionscope parameter are PTHREAD_SCOPE_PROCESS and PTHREAD_SCOPE_SYSTEM.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getscope(const pthread_attr_t *restrict attr,
                            int *restrict contentionscope);
  int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope);
                                                                POSIX:THR,TPS

If successful, pthread_attr_getscope and pthread_attr_setscope return 0. If unsuccessful, these functions return a nonzero error code. No mandatory errors are defined for these functions.

int error;
int fd;
pthread_attr_t tattr;
pthread_t tid;

if (error = pthread_attr_init(&tattr))
   fprintf(stderr, "Failed to create an attribute object:%s
",
           strerror(error));
else if (error = pthread_attr_setscope(&tattr, PTHREAD_SCOPE_SYSTEM))
   fprintf(stderr, "Failed to set scope to system:%s
",
           strerror(error));
else if (error = pthread_create(&tid, &tattr, processfd, &fd))
   fprintf(stderr, "Failed to create a thread:%s
", strerror(error));

POSIX allows a thread to inherit a scheduling policy in different ways. The pthread_attr_getinheritsched function examines the scheduling inheritance policy, and the pthread_attr_setinheritsched function sets the scheduling inheritance policy of an attribute object.

The attr parameter is a pointer to the attribute object. The inheritsched parameter corresponds to the value to be set for pthread_attr_setinheritsched and to a pointer to the value to be retrieved for pthread_attr_getinheritsched. The two possible values of inheritsched are PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED. The value of inheritsched determines how the other scheduling attributes of a created thread are to be set. With PTHREAD_INHERIT_SCHED, the scheduling attributes are inherited from the creating thread and the other scheduling attributes are ignored. With PTHREAD_EXPLICIT_SCHED, the scheduling attributes of this attribute object are used.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getinheritsched(const pthread_attr_t *restrict attr,
                            int *restrict inheritsched);
  int pthread_attr_setinheritsched(pthread_attr_t *attr,
                            int inheritsched);
                                                                POSIX:THR,TPS

If successful, these functions return 0. If unsuccessful, they return a nonzero error code. No mandatory errors are defined for these functions.

The pthread_attr_getschedparam function examines the scheduling parameters, and the pthread_attr_setschedparam sets the scheduling parameters of an attribute object. The attr parameter is a pointer to the attribute object. The param parameter is a pointer to the value to be set for pthread_attr_setschedparam and a pointer to the value to be retrieved for pthread_attr_getschedparam. Notice that unlike the other pthread_attr_set functions, the second parameter is a pointer because it corresponds to a structure rather than an integer. Passing a structure by value is inefficient.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getschedparam(const pthread_attr_t *restrict attr,
                            struct sched_param *restrict param);
  int pthread_attr_setschedparam(pthread_attr_t *restrict attr,
                            const struct sched_param *restrict param);
                                                                   POSIX:THR

If successful, these functions return 0. If unsuccessful, they return a nonzero error code. No mandatory errors are defined for these functions.

The scheduling parameters depend on the scheduling policy. They are encapsulated in a struct sched_param structure defined in sched.h. The SCHED_FIFO and SCHED_RR scheduling policies require only the sched_priority member of struct sched_param. The sched_priority field holds an int priority value, with larger priority values corresponding to higher priorities. Implementations must support at least 32 priorities.

Program 12.10 shows a function that creates a thread attribute object with a specified priority. All the other attributes have their default values. Program 12.10 returns a pointer to the created attribute object or NULL if the function failed, in which case it sets errno. Program 12.10 illustrates the general strategy for changing parameters—read the existing values first and change only the ones that you need to change.

#define HIGHPRIORITY 10

int fd;
pthread_attr_t *tattr;
pthread_t tid;
struct sched_param tparam;

if ((tattr = makepriority(HIGHPRIORITY))) {
   perror("Failed to create the attribute object");
else if (error = pthread_create(&tid, tattr, dothis, &fd))
   fprintf(stderr, "Failed to create dothis thread:%s
", strerror(error));

Threads of the same priority compete for processor resources as specified by their scheduling policy. The sched.h header file defines SCHED_FIFO for first-in-first-out scheduling, SCHED_RR for round-robin scheduling and SCHED_OTHER for some other policy. One additional scheduling policy, SCHED_SPORADIC, is defined for implementations supporting the POSIX:SS Process Sporadic Server Extension and the POSIX:TSP Thread Sporadic Server Extension. Implementations may also define their own policies.

#include <errno.h>
#include <pthread.h>
#include <stdlib.h>

pthread_attr_t *makepriority(int priority) {    /* create attribute object */
   pthread_attr_t *attr;
   int error;
   struct sched_param param;

   if ((attr = (pthread_attr_t *)malloc(sizeof(pthread_attr_t))) == NULL)
      return NULL;
   if (!(error = pthread_attr_init(attr)) &&
       !(error = pthread_attr_getschedparam(attr, &param))) {
       param.sched_priority = priority;
       error = pthread_attr_setschedparam(attr, &param);
   }
   if (error) {                      /* if failure, be sure to free memory */
      free(attr);
      errno = error;
      return NULL;
   }
   return attr;
}

First-in-first-out scheduling policies (e.g., SCHED_FIFO) use a queue for threads in the runnable state at a specified priority. Blocked threads that become runnable are put at the end of the queue corresponding to their priority, whereas running threads that have been preempted are put at the front of their queue.

Round-robin scheduling (e.g., SCHED_RR) behaves similarly to first-in-first-out except that when a running thread has been running for its quantum, it is put at the end of the queue for its priority. The sched_rr_get_interval function returns the quantum.

Sporadic scheduling, which is similar to first-in-first-out, uses two parameters (the replenishment period and the execution capacity) to control the number of threads running at a given priority level. The rules are reasonably complex, but the policy allows a program to more easily regulate the number of threads competing for the processor as a function of available resources.

Preemptive priority policy is the most common implementation of SCHED_OTHER. A POSIX-compliant implementation can support any of these scheduling policies. The actual behavior of the policy in the implementation depends on the scheduling scope and other factors.

The pthread_attr_getschedpolicy function gets the scheduling policy, and the pthread_attr_setschedpolicy function sets the scheduling policy of an attribute object. The attr parameter is a pointer to the attribute object. For the function pthread_attr_setschedpolicy, the policy parameter is a pointer to the value to be set; for pthread_attr_getschedpolicy, it is a pointer to the value to be retrieved. The scheduling policy values are described above.

SYNOPSIS

  #include <pthread.h>

  int pthread_attr_getschedpolicy(const pthread_attr_t *restrict attr,
                                 int *restrict policy);
  int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
                                                                   POSIX:THR

If successful, these functions return 0. If unsuccessful, they return a nonzero error code. No mandatory errors are defined for these functions.