Programming with POSIX® Threads

flockfile

void flockfile (

FILE *file);

Increase the lock count for a stdio file stream to gain exclusive access to the file stream. If the file stream is currently locked by another thread, the calling thread is blocked until the lock count for the file stream becomes zero. If the calling thread already owns the file stream lock, the lock count is incremented — an identical number of calls to funlockfile is required to release the file stream lock.

Although most stdio functions, such as printf and fgets, are thread-safe, you may sometimes find that it is important that a sequence of printf calls, for example, from one thread cannot be separated by calls made from another thread. Also, a few stdio functions are not thread-safe and can only be used while the file stream is locked by the caller.

References: 6.4.1 Headers: <stdio.h>

Hint: Use to protect a sequence of stdio operations.

ftrylockfile

int ftrylockfile (

FILE *file);

If the file stream is currently locked by another thread, return a nonzero value. Otherwise, increase the lock count for the file stream, and return the value zero.

References: 6.4.1 Headers: <stdio.h>

Hint: Use to protect a sequence of stdio operations.

funlockfile

void funlockfile (

FILE *file);

Decrease the lock count for a stdio file stream that was previously locked by a corresponding call to funlockfile. If the lock count becomes 0, release the lock so that another thread can lock it.

References: 6.4.1 Headers: <stdio.h>

Hint: Use to protect a sequence of stdio operations.

getc_unlocked

int getc_unlocked (

FILE *file);

Return a single character from the stdio stream file, without locking the file stream. This operation must only be used while the file stream has been locked by calling flockfile, or when you know that no other thread may access the file stream concurrently. Returns EOF for read errors or end- of-file condition.

References: 6.4.2 Headers: <stdio.h>

Hint: Replace old calls to getc to retain fastest access.

getchar_unlocked

int getc_unlocked (void);

Return a single character from the stdio stream stdin without locking the file stream. This operation must only be used while the file stream has been locked by calling flockfile, or when you know that no other thread may access the file stream concurrently. Returns EOF for read errors or end-of-file condition.

References: 6.4.2 Headers: <stdio.h>

Hint: Replace old calls to getchar to retain fastest access.

putc_unlocked

int putc_unlocked (

int c,

FILE *file);

Write a single character c (interpreted as an unsigned char) to the stdio stream file without locking the file stream. This operation must only be used while the file stream has been locked by calling flockfile, or when you know that no other thread may access the file stream concurrently. Returns the character or the value EOF if an error occurred.

References: 6.4.2 Headers: <stdio.h>

Hint: Replace old calls to putc to retain fastest access.

putchar_unlocked

int putchar_unlocked (

int c);

Write a single character c (interpreted as an unsigned char) to the stdio stream stdout without locking the file stream. This operation must only be used while the file stream has been locked by calling flockfile, or when you know that no other thread may access the file stream concurrently. Returns the character or the value EOF if an error occurred.

References: 6.4.2 Headers: <stdio.h>

Hint: Replace old calls to putchar to retain fastest access.

9.3.11 Thread-safe functions

Thread-safe functions provide improved access to traditional features of ANSI C and POSIX that cannot be effectively made thread-safe without interface changes. These routines are designated by the '_r' suffix added to the traditional function name they replace, for example, getlogin_r for getlogin.

getlogin_r

int getlogin_r (

char *name,

size_t namesize);

Write the user name associated with the current process into the buffer pointed to by name. The buffer is namesize bytes long, and should have space for the name and a terminating null character. The maximum size of the login name is LOGIN_

NAME_MAX.

References: 6.5.1 Headers: <unistd.h>

readdir_r

int readdir_r (

DIR *dirp,

struct dirent *entry, struct dirent **result);

Return a pointer (result) to the directory entry at the current position in the directory stream to which dirp refers. Whereas readdir retains the current position using a static variable, readdir_r uses the entry parameter, supplied by the caller.

References: 6.5.2

Headers: <sys/types.h>, <dirent.h>

Errors: [EBADF] dirp is not an open directory stream.

strtok_r

char *strtok_r (

char *s,

const char *sep,

char **lasts);

Return a pointer to the next token in the strings. Whereas strtok retains the current position within a string using a static variable, strtok_r uses the lasts parameter, supplied by the caller.

References: 6.5.3 Headers: <string.h>