SYSTEM CALLS

Linux Programmer's Manual

NAME
read - read from a file descriptor
SYNOPSIS
#include <unistd.h>
ssize_t read(int fd, void *buf, size_t count);
DESCRIPTION
read() attempts to read up to count bytes from file descriptor fd into the buffer starting at
buf. If count is zero, read() returns zero and has no other results. If count is greater than
SSIZE_MAX, the result is unspecified.
RETURN VALUE
On success, the number of bytes read is returned (zero indicates end of file), and the file
position is advanced by this number. It is not an error if this number is smaller than the number of
bytes requested;
NAME
close - close a file descriptor
SYNOPSIS
#include <unistd.h>
int close(int fd);
DESCRIPTION
close() closes a file descriptor, so that it no longer refers to any file and may be reused.
NAME
perror - print a system error message
SYNOPSIS
#include <stdio.h>
void perror(const char *s);
#include <errno.h>
const char *sys_errlist[];
int sys_nerr;
int errno;
DESCRIPTION
The routine perror() produces a message on the standard error output, describing the last
error encountered during a call to a system or library function.
NAME
exit - cause normal process termination
SYNOPSIS
#include <stdlib.h>
void exit(int status);
DESCRIPTION
The exit() function causes normal process termination and the value of status & 0377 is returned to
the parent.
RETURN VALUE
The exit() function does not return.
NAME
strstr, strcasestr - locate a substring
SYNOPSIS
#include <string.h>
char *strstr(const char *haystack, const char *needle);
#define _GNU_SOURCE /* See feature_test_macros(7) */
#include <string.h>
char *strcasestr(const char *haystack, const char *needle);
DESCRIPTION
The strstr() function finds the first occurrence of the substring needle in the string haystack. The
terminating null bytes ('\0') are not compared.
The strcasestr() function is like strstr(), but ignores the case of both arguments.
RETURN VALUE
These functions return a pointer to the beginning of the substring, or NULL if the substring is not
found.
NAME
strcmp, strncmp - compare two strings
SYNOPSIS
#include <string.h>
 int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
DESCRIPTION
The strcmp() function compares the two strings s1 and s2. It returns an integer less than, equal to,
or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.
The strncmp() function is similar, except it only compares the first (at most) n characters of s1 and
s2.
RETURN VALUE
The strcmp() and strncmp() functions return an integer less than, equal to, or greater than zero if s1
(or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2.
NAME
opendir, fdopendir - open a directory
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR *opendir(const char *name);
DIR *fdopendir(int fd);
DESCRIPTION
The opendir() function opens a directory stream corresponding to the directory name, and returns
a pointer to the directory stream. The stream is positioned at the first entry in the directory. The
fdopendir() function is like opendir(), but returns a directory stream for the directory referred to by
the open file descriptor fd. After a successful call to fdopendir(), fd is used internally by the
implementation, and should not otherwise be used by the application.

RETURN VALUE
The opendir() and fdopendir() functions return a pointer to the directory stream. On error, NULL
is returned, and errno is set appropriately.
NAME
readdir, readdir_r - read a directory
SYNOPSIS
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
 int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);
DESCRIPTION
The readdir() function returns a pointer to a dirent structure representing the next directory entry
in the directory stream pointed to by dirp. It returns NULL on reaching the end of the directory stream
or if an error occurred.
On Linux, the dirent structure is defined as follows:
struct dirent {
ino_t d_ino; /* inode number */
off_t d_off; /* offset to the next dirent */
unsigned short d_reclen; /* length of this record */
unsigned char d_type; /* type of file; not supported
by all file system types */
char d_name[256]; /* filename */
};
A pointer to the returned itemis placed in *result; if the end of the directory stream was encoun‐
tered, then NULL is instead returned in *result.
RETURN VALUE
On success, readdir() returns a pointer to a dirent structure. (This structure may be statically
allocated; do not attempt to free(3) it.)
If the end of the directory stream is reached, NULL is returned and errno is not changed. If an
error occurs, NULL is returned and errno is set appropriately.
The readdir_r() function returns 0 on success. On error, it returns a positive error number (listed
under ERRORS). If the end of the directory stream is reached, readdir_r() returns 0, and returns NULL
in *result.
NAME
man - an interface to the on-line reference manuals
example
man ls
NAME
strcmp, strncmp - compare two strings
SYNOPSIS
#include <string.h>
 int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
DESCRIPTION
The strcmp() function compares the two strings s1 and s2. It returns an integer less than, equal
to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.
The strncmp() function is similar, except it only compares the first (at most) n characters of s1 and
s2.
RETURN VALUE
The strcmp() and strncmp() functions return an integer less than, equal to, or greater than zero if s1
(or the first n bytes thereof) is found, respectively, to be less than, to match, or be greater than s2.
NAME
stat - display file or file system status
SYNOPSIS
stat [OPTION]... FILE...
DESCRIPTION
Display file or file system status.
NAME
getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file entry
SYNOPSIS
#include <sys/types.h>
#include <pwd.h>
struct passwd *getpwnam(const char *name);
struct passwd *getpwuid(uid_t uid);

int getpwnam_r(const char *name, struct passwd *pwd,

char *buf, size_t buflen, struct passwd **result);
int getpwuid_r(uid_t uid, struct passwd *pwd,
char *buf, size_t buflen, struct passwd **result);
DESCRIPTION
The getpwnam() function returns a pointer to a structure containing the broken-out fields of the
record in the password database (e.g., the local password file /etc/passwd, NIS, and LDAP) that
matches the user name name.
 The getpwuid() function returns a pointer to a structure containing the broken-out fields of the
record in the password database that matches the user ID uid.
The passwd structure is defined in <pwd.h> as follows:
struct passwd {
char *pw_name; /* username */
char *pw_passwd; /* user password */
uid_t pw_uid; /* user ID */
gid_t pw_gid; /* group ID */
char *pw_gecos; /* user information */
char *pw_dir; /* home directory */
char *pw_shell; /* shell program */
};

RETURN VALUE
The getpwnam() and getpwuid() functions return a pointer to a passwd structure, or NULL if the
matching entry is not found or an error occurs. If an error occurs, errno is set appropriately. If one
wants
to check errno after the call, it should be set to zero before the call.
NAME
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r,
gmtime_r, localtime_r - transform date and time to broken-down time or
ASCII
SYNOPSIS
#include <time.h>
char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *tm, char *buf);
char *ctime(const time_t *timep);
char *ctime_r(const time_t *timep, char *buf);
struct tm *gmtime(const time_t *timep);
struct tm *gmtime_r(const time_t *timep, struct tm *result);
struct tm *localtime(const time_t *timep);
struct tm *localtime_r(const time_t *timep, struct tm *result);
 time_t mktime(struct tm *tm);
DESCRIPTION
The ctime(), gmtime() and localtime() functions all take an argument of data type time_t which
represents calendar time. When interpreted as an absolute time value, it represents the number of
seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
The asctime() and mktime() functions both take an argument representing broken-down time which
is a representation separated into year, month, day, etc.
Broken-down time is stored in the structure tm which is defined in
<time.h> as follows:
struct tm {
int tm_sec; /* seconds */
int tm_min; /* minutes */
int tm_hour; /* hours */
int tm_mday; /* day of the month */
int tm_mon; /* month */
int tm_year; /* year */
int tm_wday; /* day of the week */
int tm_yday; /* day in the year */
int tm_isdst; /* daylight saving time */
};
The members of the tm structure are:
tm_sec The number of seconds after the minute, normally in the range
0 to 59, but can be up to 60 to allow for leap seconds.
tm_min The number of minutes after the hour, in the range 0 to 59.
tm_hour The number of hours past midnight, in the range 0 to 23.
tm_mday The day of the month, in the range 1 to 31.
tm_mon The number of months since January, in the range 0 to 11.
tm_year The number of years since 1900.
tm_wday The number of days since Sunday, in the range 0 to 6.
tm_yday The number of days since January 1, in the range 0 to 365.
 tm_isdst A flag that indicates whether daylight saving time is in effect at the time described. The
value is positive if day light saving time is in effect, zero if it is not, and negative if the information is
not available. The call ctime(t) is equivalent to asctime(localtime(t)). It converts the calendar
time t into a null-terminated string of the form
"Wed Jun 30 21:49:08 1993\n"
RETURN VALUE
Each of these functions returns the value described, or NULL (-1 in
case of mktime()) in case an error was detected.
NAME
fork - create a child process
SYNOPSIS
#include <unistd.h>
pid_t fork(void);
DESCRIPTION
fork() creates a new process by duplicating the calling process.
RETURN VALUE
On success, the PID of the child process is returned in the parent, and
0 is returned in the child. On failure, -1 is returned in the parent,
no child process is created, and errno is set appropriately.
NAME
getpid, getppid - get process identification
SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
pid_t getpid(void);
pid_t getppid(void);
DESCRIPTION
getpid() returns the process ID of the calling process. (This is often used by routines that generate
unique temporary filenames.)
getppid() returns the process ID of the parent of the calling process.
ERRORS
These functions are always successful.
NAME
open, creat - open and possibly create a file or device
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(const char *pathname, int flags);
int open(const char *pathname, int flags, mode_t mode);
int creat(const char *pathname, mode_t mode);
DESCRIPTION
Given a pathname for a file, open() returns a file descriptor, a small, nonnegative integer for use in
subsequent system calls
The argument flags must include one of the following access modes:
O_RDONLY, O_WRONLY, or O_RDWR. These request opening the file read-
only, write-only, or read/write, respectively.
NAME
write - write to a file descriptor
SYNOPSIS
int write(int fd, const char *buffer, int size)
DESCRIPTION
It writes upto size bytes to the file referenced by the file descriptor fd from the buffer. On
success the number of bytes written are returned.
NAME
shmget - allocates a shared memory segment
SYNOPSIS
#include <sys/ipc.h>
#include <sys/shm.h>
int shmget(key_t key, size_t size, int shmflg);
DESCRIPTION
shmget() returns the identifier of the shared memory segment associated with the value of the
argument key. A new shared memory segment, with size equal to the value of size rounded up to a
multiple of PAGE_SIZE,
 is created if key has the value IPC_PRIVATE or key isn't IPC_PRIVATE, no shared memory segment
corresponding to key exists, and IPC_CREAT is specified in shmflg.
RETURN VALUE
A valid segment identifier, shmid, is returned on success, -1 on error.
NAME
shmat, shmdt - shared memory operations
SYNOPSIS
#include <sys/types.h>
#include <sys/shm.h>
void *shmat(int shmid, const void *shmaddr, int shmflg);
int shmdt(const void *shmaddr);
DESCRIPTION
shmat() attaches the shared memory segment identified by shmid to the address space of the
calling process. The attaching address is specified by shmaddr with one of the following criteria:
If shmaddr is NULL, the system chooses a suitable (unused) address at which to attach the segment.
RETURN VALUE
On success shmat() returns the address of the attached shared memory segment; on error (void *)
-1 is returned, and errno is set to indicate the cause of the error.
On success shmdt() returns 0; on error -1 is returned, and errno is set to indicate the cause of the
error.
NAME
shmat, shmdt - shared memory operations
SYNOPSIS
#include <sys/types.h>
#include <sys/shm.h>
void *shmat(int shmid, const void *shmaddr, int shmflg);
int shmdt(const void *shmaddr);
DESCRIPTION
shmdt() detaches the shared memory segment located at the address specified by shmaddr from
the address space of the calling process. The to-be-detached segment must be currently attached with
shmaddr equal to the value returned by the attaching shmat() call.
RETURN VALUE
 On success shmdt() returns 0; on error -1 is returned, and errno is set to indicate the cause of the
error.
NAME
shmctl - shared memory control
SYNOPSIS
#include <sys/ipc.h>
#include <sys/shm.h>
int shmctl(int shmid, int cmd, struct shmid_ds *buf);

DESCRIPTION
shmctl() performs the control operation specified by cmd on the shared memory segment whose
identifier is given in shmid.
The buf argument is a pointer to a shmid_ds structure, defined in <sys/shm.h> as follows:
struct shmid_ds {
struct ipc_perm shm_perm; /* Ownership and permissions */
size_t shm_segsz; /* Size of segment (bytes) */
time_t shm_atime; /* Last attach time */
time_t shm_dtime; /* Last detach time */
time_t shm_ctime; /* Last change time */
pid_t shm_cpid; /* PID of creator */
pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
shmatt_t shm_nattch; /* No. of current attaches */
...
};

The ipc_perm structure is defined in <sys/ipc.h> as follows (the high‐

lighted fields are settable using IPC_SET):
struct ipc_perm {
key_t __key; /* Key supplied to shmget(2) */
uid_t uid; /* Effective UID of owner */
gid_t gid; /* Effective GID of owner */
uid_t cuid; /* Effective UID of creator */
 gid_t cgid; /* Effective GID of creator */
unsigned short mode; /* Permissions + SHM_DEST and
SHM_LOCKED flags */
unsigned short __seq; /* Sequence number */
};
On error, -1 is returned, and errno is set appropriately.
NAME
semget - get a semaphore set identifier
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semget(key_t key, int nsems, int semflg);
DESCRIPTION
The semget() system call returns the semaphore set identifier assocated with the argument key. A
new set of nsems semaphores is created if key has the value IPC_PRIVATE or if no existing
semaphore set is associated with key and IPC_CREAT is specified in semflg.
RETURN VALUE
If successful, the return value will be the semaphore set identifier (a nonnegative integer),
otherwise -1 is returned, with errno indicating the error.
NAME
semop, semtimedop - semaphore operations
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semop(int semid, struct sembuf *sops, unsigned nsops);
int semtimedop(int semid, struct sembuf *sops, unsigned nsops,
struct timespec *timeout);
semtimedop(): _GNU_SOURCE

DESCRIPTION
 Each semaphore in a semaphore set has the following associated values:
unsigned short semval; /* semaphore value */
unsigned short semzcnt; /* # waiting for zero */
unsigned short semncnt; /* # waiting for increase */
pid_t sempid; /* process that did last op */

semop() performs operations on selected semaphores in the set indicated by semid. Each of the
nsops elements in the array pointed to by sops specifies an operation to be performed on a single
semaphore. The elements of this structure are of type struct sembuf, containing the following
members:
unsigned short sem_num; /* semaphore number */
short sem_op; /* semaphore operation */
short sem_flg; /* operation flags */
Flags recognized in sem_flg are IPC_NOWAIT and SEM_UNDO. If an operation specifies
SEM_UNDO, it will be automatically undone when the process terminates.
RETURN VALUE
If successful semop() and semtimedop() return 0; otherwise they return
-1 with errno indicating the error.
NAME
semctl - semaphore control operations
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl(int semid, int semnum, int cmd, ...);
DESCRIPTION
semctl() performs the control operation specified by cmd on the semaphore set identified by
semid, or on the semnum-th semaphore of that set. (The semaphores in a set are numbered
starting at 0.)
NAME
signal - ANSI C signal handling
SYNOPSIS
 #include <signal.h>
typedef void (*sighandler_t)(int);
sighandler_t signal(int signum, sighandler_t handler);
DESCRIPTION
The behavior of signal() varies across UNIX versions
RETURN VALUE
signal() returns the previous value of the signal handler, or SIG_ERR on error.
NAME
link - call the link function to create a link to a file
SYNOPSIS
link FILE1 FILE2
link OPTION
DESCRIPTION
Call the link function to create a link named FILE2 to an existing FILE1.
NAME
unlink - call the unlink function to remove the specified file
SYNOPSIS
unlink FILE
unlink OPTION
DESCRIPTION
Call the unlink function to remove the specified FILE.
NAME
execl, execlp, execle, execv, execvp, execvpe - execute a file
SYNOPSIS
#include <unistd.h>
extern char **environ;
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[]);
 int execvpe(const char *file, char *const argv[],
char *const envp[]);
RETURN VALUE
The exec() functions only return if an error has have occurred. The return value is -1, and errno is
set to indicate the error.
NAME
wait, waitpid, waitid - wait for process to change state
SYNOPSIS
#include <sys/types.h>
#include <sys/wait.h>
pid_t wait(int *status);
pid_t waitpid(pid_t pid, int *status, int options);
int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);
DESCRIPTION
All of these system calls are used to wait for state changes in a child of the calling process, and
obtain information about the child whose state has changed.
RETURN VALUE
wait(): on success, returns the process ID of the terminated child; on
error, -1 is returned.