Kernel API Subset

IN THIS APPENDIX

• Files and So On 465

This appendix lists all the manual pages of the kernel library and system calls that are not directly related to sockets but are typically used in conjunction with sockets.

Tasks

Tasks include both processes and threads. Threads (pThreads) are defined in the next section; this section covers processes and low-level tasks (clones).

fork()

Create a new process (independent task) at this call. This call creates a child process to run with the parent. You must be careful that you capture the child and direct it to its assigned task; otherwise, the child runs each statement the parent does (they run together).

int PID; if ( (PID = fork()) == 0 )

} else if ( PID > 0 )

wait(status); /* may be done in SIGCHLD signal handler */

} else /*--- ERROR ---*/ perror(“fork() failed”);

__clone()

This is a low-level system call for creating tasks. You can directly control what is shared between the parent and the child. This is not for amateur programmers; you can create very unpredictable programs. (See Chapter 7, “Dividing the Load: Multitasking,” for a complete description of this call.)

Prototype

#include <sched.h> int __clone(int (*fn)(void* arg), void* stacktop, int flags, void* arg);

Return Value

process ID

Parameters

fn

stacktop

If negative, errno has the exact error code.

The home for the child task. Create a function (or procedure) that accepts a void* parameter argument. When the routine attempts to return, the operating system terminates the task for you. You must create a stack for the child task. This parameter points to the top of that stack (the highest address of the data block). Because you provide the stack, the stack is fixed in size and cannot grow like a normal task’s stacks.

Two types of information arithmetically ORed together; the VM spaces to share and the termination signal. This flag supports all signal types and, when the task terminates, the operating system raises the signal you define.

The available VM spaces are as follows:

• CLONE_VM Share the data space between tasks. Use this flag to share all static data, preinitialized data, and the allocation heap. Otherwise, copy data space.

• CLONE_FS Share the file system information: current working directory, root file system, and default file creation permissions. Otherwise, copy settings.

• CLONE_FILES Share open files. When one task changes the file pointer, the other tasks see the change. Likewise, if the task closes the file, the other tasks are not able to access the file any longer. Otherwise, create new references to open inodes.

flags

• CLONE_SIGHAND Share signal tables. Individual tasks may choose to ignore open signals (using sigprocmask()) without affecting peers. Otherwise, copy tables.

• CLONE_PID Share Process ID. Use this flag carefully; not all the existing tools support this feature. The PThreads library does not use this option. Otherwise, allocate new PID.

You can pass a pointer reference to any data value using this parameter. When the operating system finishes creating the child task, it calls the routine fn with the arg parameter. If you use this feature, be sure to place the value arg points to in the shared data region (CLONE_VM).

arg

void Child(void* arg) {

     /*---child’s responsibility---*/ exit(0); }

... int main(void)

if ( (cchild = __clone(&Child, stack+STACKSIZE-1, SIGCHLD, 0) == 0 )

exec()

Run an external program (either a binary or an executable script with #! <interpreter> [arg] in the first line). This call replaces the currently running task with the external program’s context. The new program keeps the caller’s PID and open files.

The calls execl(), execlp(), execle(), execv(), and execvp() are all front ends to

execve().

Prototype

#include <unistd.h> int execve(const char* path, char* const argv[], char* const envp[]); int execl(const char* path, const char* arg, ...); int execlp(const char* file, const char* arg, ); int execle(const char* path, const char* arg, , char* const envp[]); int execv(const char* path, char* const argv[]); int execvp(const char* file, char* const argv[]);

Return Value

This call does not return if successful. If it fails, the return value is -1.

Example

execl(“/bin/ls”, “/bin/ls”, “-al”, “/home”, “/boot”, 0); perror(“execl() failed”); /* No IF needed here: if successful, no return */ char *args[]={“ls”, “-al”, “/home”, “/boot”, 0}; execvp(args[0], args); perror(“execvp() failed”);

sched_yield()

Relinquish control of the CPU without blocking. This routine tells the scheduler that the currently running task wants to give up the remains of its current timeslice. The call returns on the next timeslice.

Prototype

#include <sched.h> int sched_yield(void);

Return Value

Zero if all goes okay and control is transferred; otherwise, -1.

Parameters

(none)

Possible Errors

(none defined)

Example

#include <sched.h> sched_yield();

wait(), waitPID()

Wait for and acknowledge the termination of a child process. This is important to keep zombie processes from lingering in the process table and to free up valuable resources. The wait() call waits for any process to terminate, and the waitPID() call permits you to specify a specific process or group. You can use the following macros to get the meaning from the status:

• WIFEXITED(status) is non-zero if the child exited normally.
  
• WEXITSTATUS(status) evaluates to the least significant eight bits of the return code of the child that terminated, which may have been set as the argument to a call to exit() or as the argument for a return statement in the main program. This macro can only be evaluated if WIFEXITED returned non-zero.
  
• WIFSIGNALED(status) returns true if the child process exited because of a signal that was not caught.
  
• WTERMSIG(status) returns the number of the signal that caused the child process to terminate. This macro can only be evaluated if WIFSIGNALED returned non-zero.
  
• WIFSTOPPED(status) returns true if the child process that caused the return is currently stopped; this is only possible if the call was done using WUNTRACED.
  
• WSTOPSIG(status) returns the number of the signal that caused the child to stop. This macro can only be evaluated if WIFSTOPPED returned non-zero.
  

Prototype

• include <sys/types.h>
  
• include <sys/wait.h>
  

PID_t wait(int *status);

PID_t waitpid(PID_t PID, int *status, int options);

Return Value

Both calls return the PID of the child that terminated.

Parameters

status

PID

Returns the ending status of the child. If not zero or NULL, this parameter picks up the child’s termination code and exit() value.

Indicates which process to wait for:

< -1 Wait for any child process whose process group ID is equal to the absolute value of PID.

== -1 Wait for any child process; this is the same behavior that wait() exhibits.

== 0 Wait for any child process whose process group ID is equal to that of the calling process.

> 0 Wait for the child whose process ID is equal to the value of PID.

WNOHANG Return immediately if no child has exited.

WUNTRACED Return for children who are stopped and whose status has not been reported.

options

void sig_child(int signum) /* This handler only gets one waiting zombie */

} void sig_child(int signum) /* This handler removes all waiting zombies */ { while ( waitpid(-1, 0, WNOHANG) > 0 ); }

Threads

Threads are another kind of task. This section defines a few library calls from the pThreads library.

pthread_create()

This call creates a lightweight kernel process (thread). The thread starts in the function that start_fn points to using arg as the function’s parameter. When the function returns, the thread

terminates. The function should return a void* value, but if it doesn’t, the thread still terminates and the result is set to NULL.

Prototype

#include <pthread.h> int pthread_create(pthread_t *tchild, pthread_attr_t *attr, void (*start_fn)(void *), void *arg);

Return Value

This is a positive value if successful. If the thread-create call encountered any errors, the call returns a negative value and sets errno to the error.

void* child(void *arg) { /**** Do something! ****/ pthread_exit(arg); /* terminate and return arg */ }

int main()

}

pthread_join()

Similar to the wait() system call, this call waits for and accepts the return value of the child thread.

Prototype

#include <pthread.h> int pthread_join(pthread_t tchild, void **retval);

Return Value

A positive value if successful. If the thread-create call encountered any errors, the call returns a negative value and sets errno to the error.

Parameters

thread retval

Possible Errors

ESRCH

EINVAL EINVAL EDEADLK

Example

(see pthread_create())

pthread_exit()

The thread handle to wait on

The pointer to the value passed back (passed by reference)

No thread could be found corresponding to that specified by

tchild.

The tchild thread has been detached.

Another thread is already waiting on termination of tchild. The tchild argument refers to the calling thread.

Explicitly terminates the current thread, returning retval. You can use a simple return statement as well.

Prototype

#include <pthread.h> void pthread_exit(void *retval);

Return Value

(none)

Parameter

retval

The void* value to return. Make sure that this value is non-stack memory.

Possible Errors

(none)

Example

(see pthread_create())

pthread_detach()

Detaches tchild thread from the parent. Normally, you need to join or wait for every process and thread. This call lets you create several threads and ignore them. This is the same as setting the thread’s attribute upon creation.

Prototype

#include <pthread.h> int pthread_detach(thread_t tchild);

Return Value

A zero if successful. If the thread-create call encountered any errors, the call returns a negative value and sets errno to the error.

Parameter

tchild

Possible Errors

ESRCH

EINVAL EINVAL EDEADLK

Example

void* child(void *arg) {

The child thread to detach

No thread could be found corresponding to that specified by

tchild.

The tchild thread has been detached.

Another thread is already waiting on termination of tchild. The tchild argument refers to the calling thread.

/**** Do something! ****/ pthread_exit(arg); /* terminate and return arg */

}

int main()

else pthread_detach(tchild); /**** Do something! ****/

}

Locking

The primary advantage of using threads is sharing data memory. Because the threads may try to revise the memory at the same time, you need to lock the memory for exclusive access. This section describes pThread calls that you can use (even with clones) to lock memory.

pthread_mutex_init(), pthread_mutex_destroy()

These calls create and destroy mutex semaphore variables. You may not need the initializer because the defined variables are easier and faster to use. The destroy call normally frees up any resources. However, the Linux implementation uses no allocated resources, so the call does nothing more than check whether the resource is unlocked.

Prototype

#include <pthread.h>

/*---Predefined mutex settings---*/ pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER; pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP; pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;

int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr); int pthread_mutex_destroy(pthread_mutex_t *mutex);

Lock or try to lock a semaphore for entering a critical section. The parameter is simply a variable that acts like a reservation ticket. If another thread tries to lock a reserved spot, it blocks until the reserving thread releases the semaphore.

Prototype

#include <pthread.h> int pthread_mutex_lock(pthread_mutex_t *mutex); int pthread_mutex_trylock(pthread_mutex_t *mutex);

pthread_mutex_t mutex = fastmutex;

if ( pthread_mutex_lock(&mutex) == 0 ) { /**** work on critical data ****/ pthread_mutex_unlock(&mutex); } pthread_mutex_t mutex = fastmutex;

/*---Do other processing while waiting for semaphore---*/ while ( pthread_mutex_trylock(&mutex) != 0 && errno == EBUSY ) { /**** Work on something else while waiting ****/ } /*---Got the semaphore! Now work on the critical section---*/ if ( errno != ENOERROR ) { /**** work on critical data ****/ pthread_mutex_unlock(&mutex); }

pthread_mutex_unlock()

Unlock a mutex semaphore.

Prototype

#include <pthread.h> int pthread_mutex_unlock(pthread_mutex_t *mutex);

Return Value

The call returns zero on success and nonzero on error. You can find the exact code in errno.

When working with tasks, your program may get signals (or asynchronous notifications). This section describes system calls that let you capture and process them.

signal()

Register the sig_fn routine to answer the signum signal. The default behavior is a single shot; the signal handler reverts to the default after getting the first signal. Use sigaction() instead if you want to control the behavior more.

Prototype

#include <signal.h> void (*signal(int signum, void (*sig_fn)(int signum)))(int signum); -or-typedef void (*TSigFn)(int signum); TSigFn signal(int signum, TSigFn sig_fn);

Return Value

A positive value if successful. If the thread-create call encountered any errors, the call returns a negative value and sets errno to the error.

Example

void sig_handler(int signum) { switch ( signum ) { case SIGFPE:

     } }

if ( signal(SIGFPE, sig_handler) == 0 ) perror(“signal() failed”);

sigaction()

Similar to signal(), sigaction() establishes the receiver of certain signals. Unlike signal(), however, this call gives you a lot more control over how the signaling notification behaves. It is also a little more complicated to use.

Prototype

#include <signal.h> int sigaction(int signum, const struct sigaction *sigact, struct sigaction *oldsigact);

Return Value

Zero upon success; otherwise, nonzero.

Parameters

void sig_handler(int signum) { switch ( signum ) { case SIGCHLD:

     } }

struct sigaction sigact; bzero(&sigact, sizeof(sigact)); sigact.sa_handler = sig_handler; /* set the handler */ sigact.sa_flags = SA_NOCLDSTOP | SA_RESTART; /* set options */ if ( sigaction(SIGCHLD, &sigact, 0) == 0 ) perror(“sigaction() failed”);

sigprocmask()

Sets which signals are permitted to interrupt while servicing a signal.

#include <string.h> void bzero(void *mem, int bytes); void* memset(void *mem, int val, size_t bytes);

F_DUPFD The new descriptor F_GETFD Value of flag F_GETFL Value of flags

F_GETOWN Value of descriptor owner

F_GETSIG Value of signal sent when read or write becomes possible, or zero for traditional SIGIO behavior

All other commands return zero.

Example

• include <unistd.h>
  
• include <fnctl.h>
  

... printf(“PID which owns SIGIO: %d”, fnctl(fd, F_GETOWN));

• include <unistd.h>
  
• include <fnctl.h>
  

... if ( fnctl(fd, F_SETSIG, SIGKILL) != 0 ) perror(“Can’t set signal”);

• include <unistd.h>
  
• include <fnctl.h>
  

... if ( (fd_copy = fcntl(fd, F_DUPFD)) < 0 ) perror(“Can’t dup fd”);

pipe()

Creates a pipe that points to itself. Each file descriptor in fd[] coincides with input (fd[0]) and output (fd[1]). If you write to fd[1], you can read the data on fd[0]. Used mostly with

fork().

Prototype

#include <unistd.h> int pipe(fd[2]);

Return Value

Zero if okay; -1 on error.

Similar to select(), this call waits on any one of several I/O channels for changes. Instead of using macros for managing and controlling the descriptor list, the programmer uses structure entries.

Prototype

#include <sys/poll.h> int poll(struct pollfd *ufds, unsigned int nfds, int timeout);

Return Value

If less than zero, an error occurred; a zero returned means that the call timed out. Otherwise, the call returns the number of descriptor records that changed.

Parameters

ufds

The following is an array of pollfd structures. Each record tracks a different file descriptor.

struct pollfd {

int fd;

/* file descriptor */

short events; /* requested events */ short revents; /* returned events */

};

The fd field is the file descriptor to check. The events and revents fields indicate the events to check and the events that occurred, respectively. The bit-values available are as follows: POLLIN There is data to read.

POLLPRI There is urgent data to read. POLLOUT Writing now will not block.

POLLERR Error condition. POLLHUP Hung up.

POLLNVAL Invalid request; fd not open. POLLRDNORM Normal read (Linux only). POLLRDBAND Read out-of-band (Linux only). POLLWRNORM Normal write (Linux only). POLLWRBAND Write out-of-band (Linux only).

int fd_count=0; struct pollfd fds[MAXFDs]; fds[fd_count].fd = socket(PF_INET, SOCK_STREAM, 0); /*** bind() and listen() socket ***/ fds[fd_count++].events = POLLIN; for (;;) { if ( poll(fds, fd_count, TIMEOUT_MS) > 0 )

fds[fd_count].events = POLLIN | POLLHUP; fds[fd_count++].fd = accept(fds[0].fd, 0, 0);

} for ( i = 1; i < fd_count; i++ ) { if ( (fds[i].revents & POLLHUP) != 0 ) { close(fds[i].fd); /*** Move up FDs to fill empty slot ***/ fd_count--; } else if ( (fds[i].revents & POLLIN) != 0 )

/*** Read and process data ***/

}

}

}

read()

Read buf_len bytes from the fd file descriptor into the buffer. You can use this system call for sockets as well as files, but this call does not provide as much control as the recv() system call.

int sockfd; int bytes_read; char buffer[1024];

/*---create socket & connect to server---*/ if ( (bytes_read = read(sockfd, buffer, sizeof(buffer))) < 0 ) perror(“read”);

select()

Wait for any I/O status changes from the file descriptor sets. When any of the specified sets changes, the call returns. You have four macros to help construct and manage the file descriptor sets:

• include <sys/time.h>
  
• include <sys/types.h>
  
• include <unistd.h>
  

int select(int hi_fd, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); FD_CLR(int fd, fd_set *set); FD_ISSET(int fd, fd_set *set); FD_SET(int fd, fd_set *set); FD_ZERO(fd_set *set);

Return Value

The number of descriptors that have changed states. If an error occurred, the return value is negative. If the timeout expired, the return value is zero.

Parameters

fd set

The file descriptor to add, remove, or test. The file descriptor set.

int i, ports[]={9001, 9002, 9004, -1}; int sockfd, max=0; fd_set set; struct sockaddr_in addr; struct timeval timeout={2,500000}; /* 2.5 sec. */

FD_ZERO(&set); bzero(&addr, sizeof(addr)); addr.sin_family = AF_INET; addr.sin_addr.s_addr = INADDR_ANY; for ( i = 0; ports[i] > 0; i++ ) { sockfd = socket(PF_INET, SOCK_STREAM, 0); addr.sin_port = htons(ports[i]); if ( bind(sockfd, &addr, sizeof(addr)) != 0) perror(“bind() failed”); else { FD_SET(sockfd, &set); if ( max < sockfd ) max = sockfd; } } if ( select(max+1, &set, 0, &set, &timeout) > 0 ) { for ( i = 0; i <= max; i++ ) if ( FD_ISSET(i, &set) )

}

}

write()

Write msg_len bytes to fd field descriptor from buffer. You can use a socket descriptor as well, but it does not provide you with as much control as the send() system call.

Prototype

#include <unistd.h> int write(int fd, const void *buffer, size_t msg_len);

Return Value

Number of bytes written. The byte count can be less than msg_len. If the call does not succeed in writing all required bytes, you can use a loop for successive writes. If negative, the call stores the error detail in errno.

Parameters

/*** Write a message (TCP, UDP or Raw) ***/ int sockfd; int bytes, bytes_wrote=0; /*--- Create socket, connect to server ---*/ while ( (bytes = write(sockfd, buffer, msg_len)) > 0 ) if ( (bytes_wrote += bytes) >= msg_len ) break; if ( bytes < 0 ) perror(“write”);

close()

Closes all descriptors (file or socket). If the socket is connected to a server or client, it requests a close(). The channel actually remains active after the close until the channel empties or times out. Every process has a limit to the number of open descriptors it can have.

getdtablesize() returns 1024 in Linux 2.2.14, and the /usr/include/linux/limits.h file

defines this limit with NR_OPEN. Also, the first three descriptors default to stdin (0), stdout (1), and stderr (2).

Prototype

#include <unistd.h> int close(int fd);

Return Value

Zero if everything goes well. If an error occurs, you can find the cause in errno.

Parameter

fd

Possible Error

EBADF

Example

The file or socket descriptor

fd isn’t a valid open file descriptor.

int sockfd; sockfd = socket(PF_INET, SOCK_RAW, htons(99)); if ( sockfd < 0 ) PANIC(“Raw socket create failed”); ... if ( close(sockfd) != 0 ) PANIC(“Raw socket close failed”);