# IO ## **Overview** Provides data structures and functions for performing input/output \(I/O\) operations, such as printf and scanf. **Since:** 1.0 **Version:** 1.0 ## **Summary** ## Files

File Name

Description

aio.h

Declares functions related to asynchronous I/O (AIO) operations.

err.h

Provides common functions for error messages.

iconv.h

Declares functions related to the I/O character set conversion.

locale.h

Provides functions to set and obtain the locale language environment.

nl_types.h

Defines I/O multiplexing functions related to message catalog operations.

poll.h

Declares I/O multiplexing functions.

stdio.h

Declares common functions used for performing input and output (I/O) operations.

select.h

Provides functions and structures related to I/O multiplexing.

uio.h

Provides functions and structures related to input/output (I/O) to a file or buffer.

wordexp.h

Declares functions related to word expansion.

## Data Structures

Data Structure Name

Description

lconv

Indicates format information about a number.

pollfd

Defines I/O multiplexing.

fd_set

Defines a file descriptor set.

wordexp_t

Describes information about word expansion.

## Macros

Macro Name and Value

Description

LIO_WAIT    0

Waiting to be notified of the completion of all asynchronous I/O operations.

LIO_NOWAIT    1

Not waiting to be notified of the completion of all asynchronous I/O operations.

LC_CTYPE    0

Language symbol type, which affects character classification and case conversion.

LC_NUMERIC    1

Number type, which affects the number format.

LC_TIME    2

Time type, which affects date and time formats.

LC_COLLATE    3

Character sorting type, which affects string comparison and sorting habits.

LC_MONETARY    4

Monetary type, which affects monetary information.

LC_MESSAGES    5

Message type, which affects prompt information, error information, status information, titles, labels, buttons, and menus.

LC_ALL    6

All types, which affect all content of locale settings. If LC_ALL is set, the locale information of all types is set to be consistent with LC_ALL.

POLLIN    0x001

POLLIN event.

POLLPRI    0x002

POLLPRI event.

POLLOUT    0x004

POLLOUT event.

POLLERR    0x008

POLLERR event.

POLLHUP    0x010

POLLHUP event.

POLLNVAL    0x020

POLLNVAL event.

FD_SETSIZE    1024

Defines the size of fd_set, that is, the maximum number of monitored files.

FD_ZERO(s)   do { int __i; unsigned long *__b=(s)->fds_bits; for(__i=sizeof (fd_set)/sizeof (long); __i; __i--) *__b++=0; } while(0)

Clears all elements in the file descriptor set.

FD_SET(d, s)   ((s)->fds_bits[(d)/(8*sizeof(long))] |= (1UL<<((d)%(8*sizeof(long)))))

Adds a file descriptor to a set.

FD_CLR(d, s)   ((s)->fds_bits[(d)/(8*sizeof(long))] &= ~(1UL<<((d)%(8*sizeof(long)))))

Removes a file descriptor from a set.

FD_ISSET(d, s)   !!((s)->fds_bits[(d)/(8*sizeof(long))] & (1UL<<((d)%(8*sizeof(long)))))

Checks whether a file descriptor is in a set.

## Typedefs

Typedef Name

Description

iconv_t

typedef void * 

Type of the character set conversion descriptor.

nl_catd

typedef void * 

Type of message catalog descriptor.

nfds_t

typedef unsigned long 

Number of poll types.

FILE

typedef struct _IO_FILE 

Struct of file stream.

fd_mask

typedef unsigned long 

Defines fd_set as the alias of the element type.

## Functions

Function Name

Description

lio_listio (int mode, struct aiocb *restrict const *restrict cbs, int cnt, struct sigevent *restrict sev)

int 

Initiates AIO requests.

warn (const char *fmt,...)

void 

Displays a formatted error message on the standard error (stderr) output.

vwarn (const char *fmt, va_list args)

void 

Displays a formatted error message on the stderr output.

warnx (const char *fmt,...)

void 

Displays a formatted error message on the stderr output.

vwarnx (const char *fmt, va_list args)

void 

Displays a formatted error message on the stderr output.

err (int eval, const char *fmt, va_list args)

void 

Displays error information.

errx (int eval, const char *fmt,...)

void 

Displays error information.

verr (int eval, const char *fmt, va_list args)

void 

Displays error information.

verrx (int eval, const char *fmt, va_list args)

void 

Displays a formatted error message.

iconv_open (const char *to, const char *from)

iconv_t 

Obtain a character set conversion descriptor.

iconv (iconv_t cd, char **restrict in, size_t *restrict inb, char **restrict out, size_t *restrict outb)

size_t 

Converts a character set.

iconv_close (iconv_t cd)

int 

Closes a character set conversion descriptor.

setlocale (int category, const char *locale)

char * 

Sets the current locale information based on input parameters.

localeconv (void)

struct lconv * 

Obtains the locale information about a region and stores them in lconv.

catopen (const char *name, int oflag)

nl_catd 

Opens a message catalog and returns its descriptor.

catgets (nl_catd catd, int set_id, int msg_id, const char *s)

char * 

Obtains information from a message catalog.

catclose (nl_catd catd)

int 

Closes a catalog descriptor.

poll (struct pollfd fds[], nfds_t nfds, int timeout)

int 

Defines the I/O multiplexing system.

fopen (const char *__restrict path, const char *__restrict mode)

FILE * 

Opens the file stored in the specified path based on the given mode.

fclose (FILE *fd)

int 

Closes a file based on the specified file descriptor.

remove (const char *pathname)

int 

Deletes a specified file or directory from the file system.

rename (const char *oldpath, const char *newpath)

int 

Renames a specified file.

feof (FILE *fp)

int 

Tests the end-of-file indicator for a specified stream.

ferror (FILE *stream)

int 

Tests for the error identifier of a specified file stream.

fflush (FILE *fp)

int 

Flushes the output buffer of a specified stream.

clearerr (FILE *fp)

void 

Resets the error indicators.

fseek (FILE *fp, long offset, int whence)

int 

Changes the position of a specified stream to a new position.

ftell (FILE *fp)

long 

Obtains the current value of the file position indicator for a specified file stream.

rewind (FILE *stream)

void 

Sets the position indicator of a specified stream to the beginning of the file.

fgetpos (FILE *stream, fpos_t *pos)

int 

Obtains the current file position of a specified stream and writes it to the pos parameter.

fsetpos (FILE *fp, const fpos_t *pos)

int 

Sets the file position indicator for a specified file stream.

fread (void *__restrict ptr, size_t size, size_t nmemb, FILE *__restrict stream)

size_t 

Reads data from a specified stream.

fwrite (const void *__restrict ptr, size_t size, size_t nmemb, FILE *__restrict stream)

size_t 

Writes data to a specified stream.

getc (FILE *stream)

int 

Reads a character from a specified file stream.

getchar (void)

int 

Obtains the next character from the standard input (stdin).

ungetc (int c, FILE *stream)

int 

Pushes a character back into a specified file stream.

fputc (int c, FILE *stream)

int 

Writes a character into the position pointed to by a specified stream.

putc (int c, FILE *stream)

int 

Writes a character to a specified file stream.

putchar (int c)

int 

Writes a character into the standard output (stdout).

fgets (char *s, int size, FILE *stream)

char * 

Reads a line of characters from a specified file stream and stores it into the string pointed to by s.

gets (char *s)

char * 

Reads a line of characters from the stdin and stores it in the buffer.

fputs (const char *s, FILE *stream)

int 

Writes a character string (excluding the terminating null character) to a specified file stream.

puts (const char *s)

int 

Writes a character string and appends a new-line character to the stdout.

printf (const char *format,...)

int 

Formats arguments based on format and prints formatted data to the stdout.

fprintf (FILE *stream, const char *format,...)

int 

Formats arguments based on format and prints formatted data to a specified file stream.

sprintf (char *str, const char *format,...)

int 

Prints formatted data from a variable argument list to a specified string.

snprintf (char *str, size_t size, const char *format,...)

int 

Prints formatted data of a maximum of size bytes from a variable argument list to a specified string.

vprintf (const char *format, va_list ap)

int 

Prints formatted data from a variable argument list to the stdout.

vfprintf (FILE *stream, const char *format, va_list ap)

int 

Prints formatted data from a variable argument list to a specified file stream.

vsprintf (char *str, const char *format, va_list ap)

int 

Prints formatted data from a variable argument list to a specified string.

vsnprintf (char *str, size_t size, const char *format, va_list ap)

int 

Prints formatted data of a maximum of size bytes from a variable argument list to a specified string.

scanf (const char *format,...)

int 

Reads formatted data from the stdin and stores the data to the additional arguments based on format.

fscanf (FILE *stream, const char *format,...)

int 

Reads formatted data from a specified file stream and stores it based on format into the locations pointed to by the variable arguments.

sscanf (const char *str, const char *format,...)

int 

Reads data from a character string pointed to by str and stores it based on format into the locations pointed to by the variable arguments.

vscanf (const char *format, va_list ap)

int 

Reads data from the stdin and stores it based on format into the locations pointed to by the elements in the variable argument list identified by ap.

vfscanf (FILE *stream, const char *format, va_list ap)

int 

Reads data from a specified file stream and stores it based on format into the locations pointed to by the elements in the variable argument list identified by ap.

vsscanf (const char *str, const char *format, va_list ap)

int 

Reads data from a specified string and stores it based on format into the locations pointed to by the elements in the variable argument list identified by ap.

perror (const char *msg)

void 

Prints the last error occurred during a call to a system or library function to the standard error output stream (stderr).

setvbuf (FILE *stream, char *buf, int mode, size_t size)

int 

Sets the mode and size of the buffer for a specified stream.

setbuf (FILE *stream, char *buf)

void 

Sets a buffer to be used by a specified stream.

fmemopen (void *buf, size_t size, const char *mode)

FILE * 

Opens a memory stream that allows the access mode specified by mode.

open_memstream (char **ptr, size_t *size)

FILE * 

Opens a stream for writing to a specified buffer.

pclose (FILE *f)

int 

Closes a specified pipe.

fileno (FILE *fp)

int 

Obtains the file descriptor of a specified file stream.

fseeko (FILE *fp, off_t offset, int whence)

int 

Sets the position of the next input or output operation on a specified file stream.

ftello (FILE *fp)

off_t 

Obtains the current value of the file position indicator for a specified file stream.

dprintf (int fd, const char *format,...)

int 

Prints formatted data to a specified file.

vdprintf (int fd, const char *format, va_list ap)

int 

Prints formatted data from a variable argument list to a specified file.

ftrylockfile (FILE *filehandle)

int 

Locks a specified file.

funlockfile (FILE *filehandle)

void 

Unlocks a specified file.

getc_unlocked (FILE *stream)

int 

Obtains a character from a specified file stream without locking the file stream or checking whether it is locked.

getchar_unlocked (void)

int 

Obtains the next character from stdin.

putc_unlocked (int c, FILE *stream)

int 

Writes a character to a specified file stream with the thread remains unlocked.

putchar_unlocked (int c)

int 

Writes a character to the stdout with the thread remains unlocked.

getdelim (char **lineptr, size_t *n, int delim, FILE *stream)

ssize_t 

Reads an entire line from a specified file stream.

getline (char **lineptr, size_t *n, FILE *stream)

ssize_t 

Reads an entire line from a specified file stream.

tempnam (const char *dir, const char *prefix)

char * 

Creates a temporary file with a unique file name.

setbuffer (FILE *f, char *buf, size_t size)

void 

Sets the buffer for a specified file stream.

setlinebuf (FILE *f)

void 

Sets the linear buffer for a specified file stream.

fgetc (FILE *stream)

int 

Reads a character from the file pointed to by stream.

fgetc_unlocked (FILE *stream)

int 

Reads a character from the file pointed to by stream with the thread remains unlocked.

fputc_unlocked (int c, FILE *stream)

int 

Writes a character to the file stream pointed to by stream at the current position.

ferror_unlocked (FILE *stream)

int 

Tests for the error identifier of a specified file stream.

getw (FILE *stream)

int 

Reads a word (an int value) from a specified file stream.

putw (int w, FILE *stream)

int 

Writes a word (an int value) to a specified file stream.

fgetln (FILE *stream, size_t *len)

char * 

Reads a line of data from the current position of a specified file stream.

asprintf (char **strp, const char *fmt,...)

int 

Prints formatted data to a specified character string.

vasprintf (char **strp, const char *fmt, va_list ap)

int 

Prints formatted data from a variable argument list to a specified character string.

select (int nfds, fd_set *__restrict readfds, fd_set *__restrict writefds, fd_set *__restrict exceptfds, struct timeval *__restrict timeout)

int 

Monitors the I/O events of multiple file descriptors.

readv (int fd, const struct iovec *iov, int iovcnt)

ssize_t 

Reads the data of fd to iov.

writev (int fd, const struct iovec *iov, int iovcnt)

ssize_t 

Writes a given length of data into a file.

preadv (int fd, const struct iovec *iov, int iovcnt, off_t offset)

ssize_t 

Reads the data in a file whose fd offset is offset to the multi-group buffer space pointed to by iov.

pwritev (int fd, const struct iovec *iov, int iovcnt, off_t offset)

ssize_t 

Writes the data of a multi-group buffer space pointed to by iov to the offset of fd.

wordfree (wordexp_t *we)

void 

Frees a word expansion buffer.

## **Details** ## **Macro Definition Documentation** ## FD\_CLR ``` #define FD_CLR( d,  s )   ((s)->fds_bits[(d)/(8*sizeof(long))] &= ~(1UL<<((d)%(8*sizeof(long))))) ``` **Description:** Removes a file descriptor from a set. **Parameters:**

Name

Description
d Indicates the file descriptor of the int type.
s Indicates the descriptor set of the fd_set type.
## FD\_ISSET ``` #define FD_ISSET( d,  s )   !!((s)->fds_bits[(d)/(8*sizeof(long))] & (1UL<<((d)%(8*sizeof(long))))) ``` **Description:** Checks whether a file descriptor is in a set. **Parameters:**

Name

Description
d Indicates the file descriptor of the int type.
s Indicates the descriptor set of the fd_set type.
**Returns:** Returns **0** if the file descriptor is not in the set; returns **1** if the file descriptor is in the set. ## FD\_SET ``` #define FD_SET( d,  s )   ((s)->fds_bits[(d)/(8*sizeof(long))] |= (1UL<<((d)%(8*sizeof(long))))) ``` **Description:** Adds a file descriptor to a set. **Parameters:**

Name

Description
d Indicates the file descriptor of the int type.
s Indicates the descriptor set of the fd_set type.
## FD\_ZERO ``` #define FD_ZERO( s)   do { int __i; unsigned long *__b=(s)->fds_bits; for(__i=sizeof ([fd_set](fd_set.md))/sizeof (long); __i; __i--) *__b++=0; } while(0) ``` **Description:** Clears all elements in the file descriptor set. **Parameters:**

Name

Description
s Indicates the descriptor set of the fd_set type.
## **Function Documentation** ## asprintf\(\) ``` int asprintf (char ** strp, const char * fmt,  ... ) ``` **Description:** Prints formatted data to a specified character string. If the length of the string is uncertain, this function applies for sufficient memory space based on the length of the formatted character string. **Parameters:**

Name

Description
strp Indicates the double pointer to the start address of the target string.
fmt Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Attention:** If **strp** is no longer used, the applied space must be released. **Returns:** Returns the number of output characters if the operation is successful; returns **-1** otherwise. ## catclose\(\) ``` int catclose ([nl_catd](IO.md#ga3f305b6699c89f91aecfc0b5f8604a5f) catd) ``` **Description:** Closes a catalog descriptor. **Parameters:**

Name

Description
catd Indicates the catalog descriptor to close.
**Returns:** 0 ## catgets\(\) ``` char* catgets ([nl_catd](IO.md#ga3f305b6699c89f91aecfc0b5f8604a5f) catd, int set_id, int msg_id, const char * s ) ``` **Description:** Obtains information from a message catalog. **Parameters:**

Name

Description
catd Indicates the descriptor of the message catalog.
set_id Indicates the setting ID of the message catalog.
msg_id Indicates the ID of the message catalog.
s Indicates the pointer to a string to be returned if the operation fails.
**Returns:** Returns the information obtained from the message catalog if the operation is successful; returns **s** otherwise. ## catopen\(\) ``` [nl_catd](IO.md#ga3f305b6699c89f91aecfc0b5f8604a5f) catopen (const char * name, int oflag ) ``` **Description:** Opens a message catalog and returns its descriptor. **Parameters:**

Name

Description
name Indicates the pointer to the path name of the message catalog to open.
oflag Indicates the source of the language to use.
**Returns:** Returns the catalog descriptor if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EIO

A hardware error occurs at the low-level disk I/O layer.

EINVAL

The path name format is invalid.

ENOTDIR

A part of the path prefix is the name of an existing file and is not a catalog.

EBUSY

The operation is rejected as it does not conform to the file sharing policy.

ENODEV

The corresponding device does not exist.

ENFILE

The number of opened files in the system has reached the maximum.

ELOOP

Too many symbolic links are encountered.

EFAULT

The memory address is invalid.

ENOENT

Any input parameter is incorrect.

## clearerr\(\) ``` void clearerr ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp) ``` **Description:** Resets the error indicators. This function is used to set both the file error indicator and end-of-file indicator to **0**. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream to set.
## dprintf\(\) ``` int dprintf (int fd, const char * format,  ... ) ``` **Description:** Prints formatted data to a specified file. **Parameters:**

Name

Description
fd Indicates the file descriptor that identifies a file.
format Indicates the pointer to the format string.
**Returns:** Returns the total number of written characters if the operation is successful; returns a negative value otherwise. ## err\(\) ``` void err (int eval, const char * fmt, va_list args ) ``` **Description:** Displays error information. If the **fmt** parameter is not **NULL**, stderr displays the error code description obtained from strerror\(errno\), followed by a space and a colon \(:\), and the error message to print. **Parameters:**

Name

Description
eval This function does not return, but exits with the value of eval.
fmt Indicates the pointer to the string to format.
args Indicates the parameters initialized by using va_start.
## errx\(\) ``` void errx (int eval, const char * fmt,  ... ) ``` **Description:** Displays error information. This function outputs the executable file name **argv\[0\]** and the accepted second formal parameter to stderr. **Parameters:**

Name

Description
eval This function does not return, but exits with the value of eval.
fmt Indicates the pointer to the string to format.
## fclose\(\) ``` int fclose ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fd) ``` **Description:** Closes a file based on the specified file descriptor. **Parameters:**

Name

Description
fd Indicates the pointer to the file descriptor of the file to close.
**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EINVAL

fd is NULL.

## feof\(\) ``` int feof ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp) ``` **Description:** Tests the end-of-file indicator for a specified stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream to test.
**Returns:** Returns a non-zero value if the end-of-file indicator is set; returns **0** otherwise. ## ferror\(\) ``` int ferror ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Tests for the error identifier of a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Returns:** Returns a non-zero value to indicate an error for the stream if the operation is successful; returns **0** otherwise. ## ferror\_unlocked\(\) ``` int ferror_unlocked ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Tests for the error identifier of a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Returns:** Returns a non-zero value to indicate an error for the stream if the operation is successful; returns **0** otherwise. ## fflush\(\) ``` int fflush ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp) ``` **Description:** Flushes the output buffer of a specified stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream to flush.
**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

fp points to an invalid stream.

## fgetc\(\) ``` int fgetc ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Reads a character from the file pointed to by **stream**. This function reads the next character from the current position of the file stream and returns the character, then advances the file position indicator. You can read each character of the file by continuously calling this function. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Returns:** Returns the character read as an int value if the operation is successful; returns **EOF** if the end-of-file is reached or a reading error occurs. ## fgetc\_unlocked\(\) ``` int fgetc_unlocked ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Reads a character from the file pointed to by **stream** with the thread remains unlocked. This function reads the next character from the current position of the file stream and returns the character, then advances the file position indicator. You can read each character of the file by continuously calling this function. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** This function cannot be used in a multi-thread process because it does not use locking during the call. \(It does not set locks itself, and does not test for the presence of locks set by others.\) An error occurs upon a multi-thread operation. **Returns:** Returns the character read as an int value if the operation is successful; returns **EOF** if the end-of-file is reached or a reading error occurs. ## fgetln\(\) ``` char* fgetln ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, size_t * len ) ``` **Description:** Reads a line of data from the current position of a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
len Indicates the pointer to the length of the string that is read.
**Returns:** Returns the string read. ## fgetpos\(\) ``` int fgetpos ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, fpos_t * pos ) ``` **Description:** Obtains the current file position of a specified stream and writes it to the **pos** parameter. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
pos Indicates the pointer to the fpos_t object.
**Returns:** Returns **0** if the operation is successful; returns a non-zero value otherwise. ## fgets\(\) ``` char* fgets (char * s, int size, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Reads a line of characters from a specified file stream and stores it into the string pointed to by **s**. **Parameters:**

Name

Description
s Indicates the pointer to the character array for storing the obtained string.
size Indicates the maximum number of characters to read (including the terminating null character). The value of this parameter is usually the length of the array pointed to by s.
stream Indicates the pointer to the file object that identifies a stream.
**Returns:** Returns the pointer to the read string if the operation is successful; returns a null pointer if the end-of-file is reached, no characters have been read, or if an error occurs. ## fileno\(\) ``` int fileno ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp) ``` **Description:** Obtains the file descriptor of a specified file stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream for which the file descriptor is obtained.
**Returns:** Returns the file descriptor if the operation is successful; returns **-1** and sets **errno** to a value in the following table otherwise.

errno

Description

EBADF

fp points to an invalid stream.

## fmemopen\(\) ``` [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1)* fmemopen (void * buf, size_t size, const char * mode ) ``` **Description:** Opens a memory stream that allows the access mode specified by **mode**. This function is used for applications that do not support memory operations but support file operations. After the function call, you can directly operate the returned file stream, which is equivalent to operating the memory stream. **Parameters:**

Name

Description
buf Indicates the pointer to the buffer.
size Indicates the size of the buffer.
mode Indicates the pointer to the file operation mode.
**Returns:** Returns the opened memory stream as a file stream. ## fopen\(\) ``` [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1)* fopen (const char *__restrict path, const char *__restrict mode ) ``` **Description:** Opens the file stored in the specified path based on the given mode. **Parameters:**

Name

Description
path Indicates the pointer to the path of the file to open.
mode Indicates the pointer to the file access mode. The following table describes the available values.

mode

Description

"r"

Open a file in read-only mode. The file must exist.

"w"

Open a file in write-only mode. The file is created if it does not exist. If the file already exists, its existing contents will be cleared.

"a"

Open a write-only file in append mode. The file is created if it does not exist. If the file already exists, new contents will be written at the end of the file.

"r+"

Open a file in read and write mode. The file must exist.

"w+"

Open a file for both reading and writing. The file is created if it does not exist. If the file already exists, its contents are cleared.

"a+"

Open a file in append mode for both reading and writing. The file is created if it does not exist. If the file already exists, new contents will be written at the end of the file.

"rb"

Open a binary file in read-only mode.

"wb"

Open or create a binary file in write-only mode.

"ab"

Open a binary file in append mode and write data at the end of the file.

"rb+"

Open a binary file in read and write mode. The file must exist.

"wb+"

Open or create a binary file in read and write mode.

"ab+"

Open a binary file in append mode for wring data at the end of the file. The file is also readable.

"rt"

Open a text file in read-only mode.

"wt"

Open or create a text file in write-only mode.

"at"

Open a text file in append mode and write data at the end of the file.

"rt+"

Open a text file in read and write mode.

"wt+"

Open or create a text file in read and write mode.

"at+"

Open a text file in append mode for writing data at the end of the file. The file is also readable.

**Attention:** This function can NOT be used in the PROC file system to create a file. **Returns:** Returns the pointer to the file if the operation is successful; returns **NULL** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EINVAL

Invalid mode.

EMFILE

The number of opened files exceeds the maximum number.

## fprintf\(\) ``` int fprintf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, const char * format,  ... ) ``` **Description:** Formats arguments based on **format** and prints formatted data to a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Returns:** Returns the total number of characters \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. ## fputc\(\) ``` int fputc (int c, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Writes a character into the position pointed to by a specified stream. **Parameters:**

Name

Description
c Indicates the int promotion of the character to write.
stream Indicates the pointer to the file object that identifies a stream.
**Returns:** Returns the ASCII code of the character written if the operation is successful; returns **EOF** otherwise. ## fputc\_unlocked\(\) ``` int fputc_unlocked (int c, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Writes a character to the file stream pointed to by **stream** at the current position. **Parameters:**

Name

Description
c Indicates the int promotion of the character to write.
stream Indicates the pointer to the file stream.
**Attention:** This function cannot be used in a multi-thread process because it does not use locking during the call. \(It does not set locks itself, and does not test for the presence of locks set by others.\) An error occurs upon a multi-thread operation. **Returns:** Returns the ASCII code of the character written if the operation is successful; returns **EOF** otherwise. ## fputs\(\) ``` int fputs (const char * s, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Writes a character string \(excluding the terminating null character\) to a specified file stream. **Parameters:**

Name

Description
s Indicates the pointer to the character string to write.
stream Indicates the pointer to the file object that identifies a stream.
**Returns:** Returns a non-negative value if the operation is successful; returns **EOF** otherwise. ## fread\(\) ``` size_t fread (void *__restrict ptr, size_t size, size_t nmemb, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) *__restrict stream ) ``` **Description:** Reads data from a specified stream. **Parameters:**

Name

Description
ptr Indicates the pointer to the array for storing the read data.
size Indicates the size of each element to read, in bytes.
nmemb Indicates the number of elements to read.
stream Indicates the pointer to the file object that identifies a stream to read.
**Returns:** Returns **0** if **size** or **nmemb** is **0**; returns the number of elements successfully read otherwise. This function sets **errno** to a value in the following table if a reading error occurs or the end-of-file is reached \(**fread** does not distinguish the two error reporting situations, and you can call **feof** and **ferror** to determine the specific situation\).

errno

Description

EBADF

stream points to an invalid stream.

EEOF

The end-of-file is reached.

## fscanf\(\) ``` int fscanf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, const char * format,  ... ) ``` **Description:** Reads formatted data from a specified file stream and stores it based on **format** into the locations pointed to by the variable arguments. The operation ends when a space or line feed character is encountered. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Returns:** Returns the number of variables that are successfully read. If the matching fails quickly, the return value may be less than the number of members in the argument list or even zero. If no complete conversion format is available or the input format fails to be matched, **EOF** is returned. The return value is also **EOF** if a reading error occurs. ## fseek\(\) ``` int fseek ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp, long offset, int whence ) ``` **Description:** Changes the position of a specified stream to a new position. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream for which the position is to set.
offset Indicates the offset that determines the position.
whence Indicates the start position of the offset. The following table describes the available values.

value

Description

SEEK_SET

Beginning of the file

SEEK_CUR

Current position

SEEK_END

End of the file

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

fp points to an invalid stream.

EINVAL

The value of whence is not SEEK_SET, SEEK_END, or SEEK_CUR.

ESPIPE

Invalid seek.

## fseeko\(\) ``` int fseeko ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp, off_t offset, int whence ) ``` **Description:** Sets the position of the next input or output operation on a specified file stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream for which the position is to set.
offset Indicates the offset that determines the next operation.
whence Indicates the start position of the offset. The following table describes the available values.

value

Description

SEEK_SET

Beginning of the file

SEEK_CUR

Current position

SEEK_END

End of the file

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

fp points to an invalid stream.

EINVAL

The value of whence is not SEEK_SET, SEEK_END, or SEEK_CUR.

ESPIPE

Invalid seek.

## fsetpos\(\) ``` int fsetpos ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp, const fpos_t * pos ) ``` **Description:** Sets the file position indicator for a specified file stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream for which the position is to set.
pos Indicates the pointer to the position to set.
**Returns:** Returns **0** if the operation is successful; returns a non-zero value and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

fp points to an invalid stream.

ESPIPE

Invalid seek.

## ftell\(\) ``` long ftell ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp) ``` **Description:** Obtains the current value of the file position indicator for a specified file stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream for which the position is to obtain.
**Returns:** Returns the current offset if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

fp points to an invalid stream.

## ftello\(\) ``` off_t ftello ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * fp) ``` **Description:** Obtains the current value of the file position indicator for a specified file stream. **Parameters:**

Name

Description
fp Indicates the pointer to the file object that identifies a stream for which the position is to obtain.
**Returns:** Returns the current offset if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

fp points to an invalid stream.

## ftrylockfile\(\) ``` int ftrylockfile ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * filehandle) ``` **Description:** Locks a specified file. This function facilitates I/O operations in multiple threads. If the file has been locked by another thread, this function waits until the file object is no longer locked by any thread and then locks it. **Parameters:**

Name

Description
filehandle Indicates the pointer to the file object.
**Returns:** Returns **0** if the locking is successful; returns a non-zero value otherwise. ## funlockfile\(\) ``` void funlockfile ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * filehandle) ``` **Description:** Unlocks a specified file. This function is used to reduce the lock count. **Parameters:**

Name

Description
filehandle Indicates the pointer to the file whose lock count is to be reduced.
## fwrite\(\) ``` size_t fwrite (const void *__restrict ptr, size_t size, size_t nmemb, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) *__restrict stream ) ``` **Description:** Writes data to a specified stream. **Parameters:**

Name

Description
ptr Indicates the pointer to the data to write.
size Indicates the size of each element to write, in bytes.
nmemb Indicates the number of elements to write.
stream Indicates the pointer to the file object that identifies a stream to which data is to write.
**Returns:** Returns **0** if **size** or **nmemb** is **0**; returns the number of elements successfully written otherwise. If this number is not **nmemb**, this function sets **errno** to a value in the following table if the number is not **nmemb**.

errno

Description

EBADF

stream points to an invalid stream.

## getc\(\) ``` int getc ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Reads a character from a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** The difference between this function and **fgetc** is that this function can be implemented as a macro. **Returns:** Returns the character read as an int value if the operation is successful; returns **EOF** if the end-of-file is reached or a reading error occurs. ## getc\_unlocked\(\) ``` int getc_unlocked ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Obtains a character from a specified file stream without locking the file stream or checking whether it is locked. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** Use this function with caution in multi-thread scenarios. **Returns:** Returns the obtained character. ## getchar\(\) ``` int getchar (void ) ``` **Description:** Obtains the next character from the standard input \(stdin\). This function waits for user input and does not return until any input is available. **Returns:** Returns the character read as an int value if the operation is successful; returns **EOF** if the end-of-file is reached or a reading error occurs. ## getchar\_unlocked\(\) ``` int getchar_unlocked (void ) ``` **Description:** Obtains the next character from stdin. This function waits for user input and does not return until any input is available. **Attention:** Use this function with caution in multi-thread scenarios. **Returns:** Returns the character forcibly converted to an int value if the operation is successful; returns **EOF** if the end-of-file is reached or a reading error occurs. ## getdelim\(\) ``` ssize_t getdelim (char ** lineptr, size_t * n, int delim, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Reads an entire line from a specified file stream. **Parameters:**

Name

Description
lineptr Indicates the double pointer to the buffer for storing the characters in the line.
n Indicates the pointer to the size of the buffer. If the system needs to dynamically allocate memory, set this parameter to 0.
delim Indicates the line delimiter.
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** If the system dynamically allocates memory, the memory needs to be released after being used. **Returns:** Returns the number of bytes read if the operation is successful; returns **-1** otherwise. ## getline\(\) ``` ssize_t getline (char ** lineptr, size_t * n, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Reads an entire line from a specified file stream. **Parameters:**

Name

Description
lineptr Indicates the double pointer to the buffer for storing the characters in the line.
n Indicates the pointer to the size of the buffer. If the system needs to dynamically allocate memory, set this parameter to 0.
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** If the system dynamically allocates memory, the memory needs to be released after being used. **Returns:** Returns the number of bytes read if the operation is successful; returns **-1** otherwise. ## gets\(\) ``` char* gets (char * s) ``` **Description:** Reads a line of characters from the stdin and stores it in the buffer. **Parameters:**

Name

Description
s Indicates the pointer to the memory buffer for storing the obtained string.
**Attention:** The **[gets\(\)](IO.md#gaab85b30d68ce9d9e0475e0f51bf610b1)** function cannot predict the size of the line to be read, which may cause buffer overflow. You are recommended not to use this function. POSIX.1-2008 and ISO C11 have marked this function as obsolete. **Returns:** Returns the value of **s** if the operation is successful; returns **NULL** otherwise. ## getw\(\) ``` int getw ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Reads a word \(an int value\) from a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** This function is provided for compatibility with System V Release 4 \(SVR4\). You are advised to use [fread](IO.md#ga091b3f41bdd6984d63ea48d87a62bfd2) instead. The value returned upon an error is also a valid data value. **Returns:** Returns the integer read if the operation is successful; returns **EOP** otherwise. ## iconv\(\) ``` size_t iconv ([iconv_t](IO.md#ga72517f6ffadddaafa9d51dee9b535c9f) cd, char **restrict in, size_t *restrict inb, char **restrict out, size_t *restrict outb ) ``` **Description:** Converts a character set. **Parameters:**

Name

Description
cd Indicates the conversion descriptor obtained via iconv_open.
in Indicates the double pointer to the buffer for storing the input character.
inb Indicates the pointer to the length of the character input buffer.
out Indicates the double pointer to the buffer for storing the output character.
outb Indicates the pointer to length of the character output buffer.
**Returns:** Returns the number of irreversibly converted characters if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EILSEQ

An invalid multi-byte sequence is encountered in the input.

E2BIG

The output buffer space is insufficient.

EINVAL

An incomplete multi-byte sequence is encountered in the input.

## iconv\_close\(\) ``` int iconv_close ([iconv_t](IO.md#ga72517f6ffadddaafa9d51dee9b535c9f) cd) ``` **Description:** Closes a character set conversion descriptor. **Parameters:**

Name

Description
cd Indicates the conversion descriptor to close.
**Returns:** Returns **0**. ## iconv\_open\(\) ``` [iconv_t](IO.md#ga72517f6ffadddaafa9d51dee9b535c9f) iconv_open (const char * to, const char * from ) ``` **Description:** Obtain a character set conversion descriptor. **Parameters:**

Name

Description
to Indicates the pointer to the source character set for conversion.
from Indicates the pointer to the target character set for conversion.
**Returns:** Returns the character set conversion descriptor if the operation is successful; returns **-1** otherwise. ## lio\_listio\(\) ``` int lio_listio (int mode, struct aiocb *restrict const *restrict cbs, int cnt, struct [sigevent](sigevent.md) *restrict sev ) ``` **Description:** Initiates AIO requests. **Parameters:**

Name

Description
mode Indicates the mode of notification upon the completion of AIO operations.
cbs Indicates the pointer to an array of pointers to the aiocb structure.
cnt Indicates the array size.
sev Indicates the asynchronous notification mode. The value NULL indicates that a notification is not required.
**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EAGAIN

Insufficient resources

## localeconv\(\) ``` struct [lconv](lconv.md)* localeconv (void ) ``` **Description:** Obtains the locale information about a region and stores them in [lconv](lconv.md). **Returns:** Returns a pointer to **lconv** that stores region information. ## open\_memstream\(\) ``` [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1)* open_memstream (char ** ptr, size_t * size ) ``` **Description:** Opens a stream for writing to a specified buffer. The buffer is dynamically allocated and grown. After the stream is closed, call [free\(\)](MEM.md#gafbedc913aa4651b3c3b4b3aecd9b4711) to release the buffer. When [fclose\(\)](IO.md#gac41a0ad4b31be2ad59d8222a0de30bda) or [fflush\(\)](IO.md#gae4459e830d3e2abcf428337a661d9456) is called to close or flush the stream, the pointers to the allocated buffer address and buffer size are updated to **ptr** and **size**, respectively. @attentions This function is defined in POSIX.1-2008. It is not defined in POSIX.1-2001 and is not widely used in other systems. **Parameters:**

Name

Description
ptr Indicates the pointer to the buffer address.
size Indicates the pointer to the buffer size.
**Returns:** Returns the pointer to the stream if the operation is successful; returns **NULL** and sets **errno** to indicate an error otherwise. ## pclose\(\) ``` int pclose ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * f) ``` **Description:** Closes a specified pipe. **Parameters:**

Name

Description
f Indicates the pointer to the file object that identifies a pipe to close.
**Returns:** Returns the thread termination status code if the operation is successful; returns **-1** and sets **errno** to a value in the following table otherwise.

errno

Description

ECHILD

The child process does not exist, or the specified process group does not exist.

ESRCH

The child process ends abnormally.

## perror\(\) ``` void perror (const char * msg) ``` **Description:** Prints the last error occurred during a call to a system or library function to the standard error output stream \(stderr\). **Parameters:**

Name

Description
msg Indicates the pointer to the prompt message printed to stderr before the error message itself.
**Attention:** To make the output message more useful, **msg** should convey obvious information describing what happened. When a system call fails, it usually returns **-1** and sets **errno** to a value that describes what went wrong. The error codes can be found in **[errno.h](errno-h.md)**. ## poll\(\) ``` int poll (struct [pollfd](pollfd.md) fds[], [nfds_t](IO.md#ga0af7a8bdafcd5532e620a11f0d373d52) nfds, int timeout ) ``` **Description:** Defines the I/O multiplexing system. This function is used to mount the pointer to the **pollfd** file to the waiting queue and then monitor the file. **Parameters:**

Name

Description
fds[] Indicates the pollfd array used to store the socket descriptor to be checked.
nfds Indicates the nfds_t parameter used to mark the total number of structure elements in fds.
timeout Indicates the blocking time, in milliseconds.
**Returns:** Returns a value greater than 0 if the total number of socket descriptors in **fds** is ready for read or write, or on which errors occur; returns **0** otherwise, in which case **poll** timed out. Returns **-1** and sets **errno** to a value if this function fails to be called. ## preadv\(\) ``` ssize_t preadv (int fd, const struct iovec * iov, int iovcnt, off_t offset ) ``` **Description:** Reads the data in a file whose **fd** offset is **offset** to the multi-group buffer space pointed to by **iov**. **Parameters:**

Name

Description
fd Indicates the file descriptor.
iov Indicates the pointer to the multi-group buffer.
iovcnt Indicates the number of buffers. For details, see IOV_MAX.
offset Indicates the offset of the file descriptor to read.
**Returns:** Returns the number of bytes read if the operation is successful; returns **-1** and sets **errno** to a value if the operation fails. If **errno** is set to **EINVAL**, the sum of the **iov\_len** values overflows an **ssize\_t** value, or the vector count **iovcnt** is less than 0 or greater than the permitted maximum. ## printf\(\) ``` int printf (const char * format,  ... ) ``` **Description:** Formats arguments based on **format** and prints formatted data to the stdout. **Parameters:**

Name

Description
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Attention:** **format** must correspond to the arguments specified in **...**. Otherwise, an error is returned. **Returns:** Returns the total number of characters \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. ## putc\(\) ``` int putc (int c, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Writes a character to a specified file stream. **Parameters:**

Name

Description
c Indicates the int promotion of the character to write.
stream Indicates the pointer to the file stream.
**Attention:** **Returns:** Returns the ASCII code of the character written if the operation is successful; returns **EOF** otherwise. ## putc\_unlocked\(\) ``` int putc_unlocked (int c, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Writes a character to a specified file stream with the thread remains unlocked. **Parameters:**

Name

Description
c Indicates the int promotion of the character to write.
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** This function cannot be used in a multi-thread process because it does not use locking during the call. **Returns:** Returns the ASCII code of the character written if the operation is successful; returns **EOF** otherwise. ## putchar\(\) ``` int putchar (int c) ``` **Description:** Writes a character into the standard output \(stdout\). **Parameters:**

Name

Description
c Indicates the int promotion of the character to write.
**Returns:** Returns the ASCII code of the character written if the operation is successful; returns **EOF** otherwise. ## putchar\_unlocked\(\) ``` int putchar_unlocked (int c) ``` **Description:** Writes a character to the stdout with the thread remains unlocked. **Parameters:**

Name

Description
c Indicates the int promotion of the character to write.
**Attention:** This function cannot be used in a multi-thread process because it does not use locking during the call. **Returns:** Returns the ASCII code of the character written if the operation is successful; returns **EOF** otherwise. ## puts\(\) ``` int puts (const char * s) ``` **Description:** Writes a character string and appends a new-line character to the stdout. **Parameters:**

Name

Description
s Indicates the pointer to the start address of the output buffer.
**Returns:** Returns a non-negative value if the operation is successful; returns **EOF** otherwise. ## putw\(\) ``` int putw (int w, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Writes a word \(an int value\) to a specified file stream. **Parameters:**

Name

Description
w Indicates the word to write.
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** This function is provided for compatibility with SVR4. You are advised to use [fwrite](IO.md#gaf86a4505e5de39a100f7ea828377b585) instead. **Returns:** Returns **0** if the operation is successful; returns **EOP** otherwise. ## pwritev\(\) ``` ssize_t pwritev (int fd, const struct iovec * iov, int iovcnt, off_t offset ) ``` **Description:** Writes the data of a multi-group buffer space pointed to by **iov** to the offset of **fd**. **Parameters:**

Name

Description
fd Indicates the file descriptor.
iov Indicates the pointer to the multi-group buffer.
iovcnt Indicates the number of buffers. For details, see IOV_MAX.
offset Indicates the offset of the file descriptor to write.
**Returns:** Returns the number of bytes written if the operation is successful; returns **-1** and sets **errno** to a value if the operation fails. If **errno** is set to **EINVAL**, the sum of the **iov\_len** values overflows an **ssize\_t** value, or the vector count **iovcnt** is less than 0 or greater than the permitted maximum. ## readv\(\) ``` ssize_t readv (int fd, const struct iovec * iov, int iovcnt ) ``` **Description:** Reads the data of **fd** to **iov**. **Parameters:**

Name

Description
fd Indicates the file descriptor.
iov Indicates the pointer to the multi-group buffer.
iovcnt Indicates the number of buffers. For details, see IOV_MAX.
**Returns:** Returns the number of bytes read if the operation is successful; returns **-1** and sets **errno** to a value if the operation fails. If **errno** is set to **EINVAL**, the sum of the **iov\_len** values overflows an **ssize\_t** value, or the vector count **iovcnt** is less than 0 or greater than the permitted maximum. ## remove\(\) ``` int remove (const char * pathname) ``` **Description:** Deletes a specified file or directory from the file system. **Parameters:**

Name

Description
pathname Indicates the pointer to the file or directory to delete.
**Attention:** This function can NOT be used in the PROC file system. **Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EINVAL

pathname is a null pointer or an empty string.

ENAMETOOLONG

The length of pathname is greater than NAME_MAX.

ENOMEM

Insufficient memory.

ENOENT

The file or directory pointed to by pathname does not exist.

ENOSYS

The file system does not support this operation.

EPERM

The path is a mount point or is neither a directory nor a file.

ENOTEMPTY

When pathname points to a directory, the directory is not empty.

ENXIO

No such device or address.

EACCES

The search permission on the path prefix component is denied, or the write permission of the directory in the path is denied.

## rename\(\) ``` int rename (const char * oldpath, const char * newpath ) ``` **Description:** Renames a specified file. **Parameters:**

Name

Description
oldpath Indicates the pointer to the old path name of the file to rename.
newpath Indicates the pointer to the new path name of the file.
**Attention:** This function can NOT be used in the PROC file system. **Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EINVAL

Invalid input parameter.

ENOENT

The file or directory does not exist.

EXDEV

oldpath and newpath are not on the same file system.

ENOSYS

The function is unavailable.

EBUSY

The device or resource is in use by the system or another process.

EEXIST

The file path pointed to by newpath already exists.

ENXIO

The device or address does not exist.

## rewind\(\) ``` void rewind ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream) ``` **Description:** Sets the position indicator of a specified stream to the beginning of the file. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
## scanf\(\) ``` int scanf (const char * format,  ... ) ``` **Description:** Reads formatted data from the stdin and stores the data to the additional arguments based on **format**. **Parameters:**

Name

Description
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Attention:** The type of each argument must match a format specifier in **format**. **Returns:** Returns the number of variables that are successfully read. If the matching fails quickly, the return value may be less than the number of members in the argument list or even zero. If no complete conversion format is available or the input format fails to be matched, **EOF** is returned. The return value is also **EOF** if a reading error occurs. If the number of arguments exceeds the number of the format specifiers, the excess arguments are ignored. ## select\(\) ``` int select (int nfds, [fd_set](fd_set.md) *__restrict readfds, [fd_set](fd_set.md) *__restrict writefds, [fd_set](fd_set.md) *__restrict exceptfds, struct [timeval](timeval.md) *__restrict timeout ) ``` **Description:** Monitors the I/O events of multiple file descriptors. **Parameters:**

Name

Description
nfds Indicates the maximum value of the file descriptor of the int type.
readfds Indicates the descriptor set of the readable event to observe, which is the fd_set * type.
writefds Indicates the descriptor set of the writable event to observe, which is the fd_set * type.
exceptfds Indicates the descriptor set of exception event to observe, which is the fd_set * type.
timeout Indicates the timeout interval, which is the struct timeval * type.
**Returns:** Returns the total number of file descriptors of the observed events \(that is, the sum of all file descriptors in **readfds**, **writefds**, and **exceptfds**\) if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno

Description

EBADF

An invalid file descriptor is given in one of the sets.

EINVAL

nfds is less than 0.

ENOMEM

Failed to apply for memory.

## setbuf\(\) ``` void setbuf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, char * buf ) ``` **Description:** Sets a buffer to be used by a specified stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
buf Indicates the pointer to the start address of the buffer.
**Attention:** When the input parameter **buf** is not null, the buffer mode is **\_IOFBF**. The default buffer size is determined by the value of **BUFSIZ** defined in this file. When **buf** is null, the buffer mode is **\_IONBF** \(unbuffered\). ## setbuffer\(\) ``` void setbuffer ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * f, char * buf, size_t size ) ``` **Description:** Sets the buffer for a specified file stream. **Parameters:**

Name

Description
f Indicates the pointer to the file object that identifies a stream to set.
buf Indicates the pointer to the buffer to set.
size Indicates the buffer size.
## setlinebuf\(\) ``` void setlinebuf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * f) ``` **Description:** Sets the linear buffer for a specified file stream. **Parameters:**

Name

Description
f Indicates the pointer to the file object that identifies a stream to set.
## setlocale\(\) ``` char* setlocale (int category, const char * locale ) ``` **Description:** Sets the current locale information based on input parameters. If **locale** is **NULL**, it can be used to obtain the current region settings. **Parameters:**

Name

Description
category Indicates the type of locale information used to set the impact scope of region settings. The value can be LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, or LC_ALL. The region settings include the date format, numeric format, currency format, character processing, and character comparison. The current region settings can affect only one aspect of the content or all the content.
locale Indicates the string containing region names. These names are system-specific, but at least the following three language environments must exist:

Language Name

Description

C

Indicates the C language execution environment.

""

Uses the default region settings of the current system.

NULL

No name needs to be specified.

**Returns:** Returns a pointer to the string representation of the language environment set for the type if the operation is successful; returns a null pointer and the locale is not changed if the operation fails. ## setvbuf\(\) ``` int setvbuf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, char * buf, int mode, size_t size ) ``` **Description:** Sets the mode and size of the buffer for a specified stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
buf Indicates the pointer to the start address of the buffer.
mode Indicates the buffer mode to set. There are three modes: _IONBF (unbuffered), _IOLBF (line buffered), and _IOFBF (fully buffered).
size Indicates the buffer block size when the buffer mode is _IOFBF.
**Returns:** Returns **0** if the operation is successful; returns a non-zero value otherwise. ## snprintf\(\) ``` int snprintf (char * str, size_t size, const char * format,  ... ) ``` **Description:** Prints formatted data of a maximum of **size** bytes from a variable argument list to a specified string. **Parameters:**

Name

Description
str Indicates the pointer to the string to which the data is to be written.
size Indicates the maximum length of the destination string.
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Attention:** This function can write a maximum of size-1 valid characters to the destination string. **Returns:** Returns the number of formatted characters written \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. If the return value is a non-negative value smaller than the value of **size**, the string has been completely written. ## sprintf\(\) ``` int sprintf (char * str, const char * format,  ... ) ``` **Description:** Prints formatted data from a variable argument list to a specified string. **Parameters:**

Name

Description
str Indicates the pointer to the string to which the data is to be written.
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Returns:** Returns the total number of characters \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. ## sscanf\(\) ``` int sscanf (const char * str, const char * format,  ... ) ``` **Description:** Reads data from a character string pointed to by **str** and stores it based on **format** into the locations pointed to by the variable arguments. **Parameters:**

Name

Description
str Indicates the pointer to the character string to read.
format Indicates the pointer to the format string.
... Indicates the list of arguments corresponding to the format specifiers.
**Attention:** An asterisk \(\*\) right after the percent symbol \(such as **%\*d** and **%\*s**\) in the format denotes that the value for the format will be read but will not be stored into a variable. **Returns:** Returns the number of fields successfully assigned to the argument list if the operation is successful; returns **0** if no fields are assigned; returns **EOF** if a reading error occurs or the end-of-file is reached during data reading. If an encoding error occurs when characters are parsed, this function sets **errno** to [EILSEQ](UTILS.md#gac6c071293826a4e66a717bb38db7794d). ## tempnam\(\) ``` char* tempnam (const char * dir, const char * prefix ) ``` **Description:** Creates a temporary file with a unique file name. **Parameters:**

Name

Description
dir Indicates the pointer to directory for creating the temporary file.
prefix Indicates the pointer to the prefix of the file name.
**Attention:** Do not use this function. Use **[mkstemp\(\)](UTILS.md#ga6abe6c5eb77aeaf05ad81a7425547d9e)** or **tmpfile\(\)** instead. **Returns:** Returns the pointer to the unique name of the created temporary file if the operation is successful; returns **NULL** and sets **errno** to indicate an error otherwise. **See also:** [mkstemp\(\)](UTILS.md#ga6abe6c5eb77aeaf05ad81a7425547d9e) | tmpfile\(\) ## ungetc\(\) ``` int ungetc (int c, [FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream ) ``` **Description:** Pushes a character back into a specified file stream. This function is usually used together with **getc**. **Parameters:**

Name

Description
c Indicates the int promotion of the character to be pushed back.
stream Indicates the pointer to the file object that identifies a stream.
**Attention:** The pushed characters are returned in reverse order if multiple characters are pushed back. Only one pushback is guaranteed. **Returns:** Returns the character specified in **c** if the operation is successful; returns **EOF** otherwise. ## vasprintf\(\) ``` int vasprintf (char ** strp, const char * fmt, va_list ap ) ``` **Description:** Prints formatted data from a variable argument list to a specified character string. If the length of the string is uncertain, this function applies for sufficient memory space based on the length of the formatted character string. **Parameters:**

Name

Description
strp Indicates the double pointer to the start address of the target string.
fmt Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** If **strp** is no longer used, the applied space must be released. **Returns:** Returns the number of output characters if the operation is successful; returns **-1** otherwise. ## vdprintf\(\) ``` int vdprintf (int fd, const char * format, va_list ap ) ``` **Description:** Prints formatted data from a variable argument list to a specified file. **Parameters:**

Name

Description
fd Indicates the file descriptor that identifies a file.
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Returns:** Returns the total number of written characters if the operation is successful; returns a negative value otherwise. ## verr\(\) ``` void verr (int eval, const char * fmt, va_list args ) ``` **Description:** Displays error information. This function outputs the executable file name **argv\[0\]** and the accepted second formal parameter to stderr. **Parameters:**

Name

Description
eval This function does not return, but exits with the value of eval.
fmt Indicates the pointer to the string to format.
args Indicates the parameters initialized by using va_start.
## verrx\(\) ``` void verrx (int eval, const char * fmt, va_list args ) ``` **Description:** Displays a formatted error message. **Parameters:**

Name

Description
eval This function does not return, but exits with the value of eval.
fmt Indicates the pointer to the string to format.
args Indicates the parameters initialized by using va_start.
## vfprintf\(\) ``` int vfprintf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, const char * format, va_list ap ) ``` **Description:** Prints formatted data from a variable argument list to a specified file stream. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** This function is generally used together with **va\_start** and **va\_end**. **Returns:** Returns the total number of characters \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. ## vfscanf\(\) ``` int vfscanf ([FILE](IO.md#ga912af5ab9f8a52ddd387b7defc0b49f1) * stream, const char * format, va_list ap ) ``` **Description:** Reads data from a specified file stream and stores it based on **format** into the locations pointed to by the elements in the variable argument list identified by **ap**. **Parameters:**

Name

Description
stream Indicates the pointer to the file object that identifies a stream.
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** This function is generally used together with **va\_start** and **va\_end**. **Returns:** Returns the number of fields successfully assigned to the argument list if the operation is successful; returns **0** if no fields are assigned; returns **EOF** if a reading error occurs or the end-of-file is reached during data reading. If an encoding error occurs when characters are parsed, this function sets **errno** to [EILSEQ](UTILS.md#gac6c071293826a4e66a717bb38db7794d). ## vprintf\(\) ``` int vprintf (const char * format, va_list ap ) ``` **Description:** Prints formatted data from a variable argument list to the stdout. **Parameters:**

Name

Description
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** This function is generally used together with **va\_start** and **va\_end**. **Returns:** Returns the total number of characters \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. ## vscanf\(\) ``` int vscanf (const char * format, va_list ap ) ``` **Description:** Reads data from the stdin and stores it based on **format** into the locations pointed to by the elements in the variable argument list identified by **ap**. **Parameters:**

Name

Description
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** This function is generally used together with **va\_start** and **va\_end**. **Returns:** Returns the number of fields successfully assigned to the argument list if the operation is successful; returns **0** if no fields are assigned; returns **EOF** if a reading error occurs or the end-of-file is reached during data reading. If an encoding error occurs when characters are parsed, this function sets **errno** to [EILSEQ](UTILS.md#gac6c071293826a4e66a717bb38db7794d). ## vsnprintf\(\) ``` int vsnprintf (char * str, size_t size, const char * format, va_list ap ) ``` **Description:** Prints formatted data of a maximum of **size** bytes from a variable argument list to a specified string. **Parameters:**

Name

Description
str Indicates the pointer to the destination character string.
size Indicates the maximum length of the destination string.
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** This function can write a maximum of size-1 characters to the destination string. **Returns:** Returns the number of formatted characters written \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. If the return value is a non-negative value smaller than the value of **size**, the string has been completely written. ## vsprintf\(\) ``` int vsprintf (char * str, const char * format, va_list ap ) ``` **Description:** Prints formatted data from a variable argument list to a specified string. **Parameters:**

Name

Description
str Indicates the pointer to the destination character string.
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Returns:** Returns the total number of characters written \(excluding the terminating null character **'\\0'**\) if the operation is successful; returns a negative value otherwise. ## vsscanf\(\) ``` int vsscanf (const char * str, const char * format, va_list ap ) ``` **Description:** Reads data from a specified string and stores it based on **format** into the locations pointed to by the elements in the variable argument list identified by **ap**. **Parameters:**

Name

Description
str Indicates the pointer to the character string to read.
format Indicates the pointer to the format string.
ap Indicates a value identifying a variable argument list initialized by using va_start.
**Attention:** This function is generally used together with **va\_start** and **va\_end**. **Returns:** Returns the number of fields successfully assigned to the argument list if the operation is successful; returns **0** if no fields are assigned; returns **EOF** if a reading error occurs or the end-of-file is reached during data reading. If an encoding error occurs when characters are parsed, this function sets **errno** to [EILSEQ](UTILS.md#gac6c071293826a4e66a717bb38db7794d). ## vwarn\(\) ``` void vwarn (const char * fmt, va_list args ) ``` **Description:** Displays a formatted error message on the stderr output. If the **fmt** parameter is not **NULL**, stderr displays the error code description obtained from strerror\(errno\), followed by a space and a colon \(:\), and the error message to print. **Parameters:**

Name

Description
fmt Indicates the pointer to the string to format.
args Indicates the parameters initialized by using va_start.
## vwarnx\(\) ``` void vwarnx (const char * fmt, va_list args ) ``` **Description:** Displays a formatted error message on the stderr output. If the **fmt** parameter is not **NULL**, stderr displays the error code description obtained from strerror\(errno\), followed by a space and a colon \(:\), and the error message to print. **Parameters:**

Name

Description
fmt Indicates the pointer to the string to format.
args Indicates the parameters initialized by using va_start.
## warn\(\) ``` void warn (const char * fmt,  ... ) ``` **Description:** Displays a formatted error message on the standard error \(stderr\) output. If the **fmt** parameter is not **NULL**, stderr displays the error code description obtained from strerror\(errno\), followed by a space and a colon \(:\), and the error message to print. **Parameters:**

Name

Description
fmt Indicates the pointer to the string to format.
... Indicates the parameters corresponding to the format declaration.
## warnx\(\) ``` void warnx (const char * fmt,  ... ) ``` **Description:** Displays a formatted error message on the stderr output. If the **fmt** parameter is not **NULL**, stderr displays the error code description obtained from strerror\(errno\), followed by a space and a colon \(:\), and the error message to print. **Parameters:**

Name

Description
fmt Indicates the pointer to the string to format.
... Indicates the parameters corresponding to the format declaration.
## wordfree\(\) ``` void wordfree ([wordexp_t](wordexp_t.md) * we) ``` **Description:** Frees a word expansion buffer. **Parameters:**

Name

Description
we Indicates the pointer to the word expansion buffer to free.
## writev\(\) ``` ssize_t writev (int fd, const struct iovec * iov, int iovcnt ) ``` **Description:** Writes a given length of data into a file. This function is used to write the **iovcnt** length of **iov** to **fd**. **Parameters:**

Name

Description
fd Indicates the file descriptor.
iov Indicates the pointer to the multi-group buffer.
iovcnt Indicates the number of buffers. For details, see IOV_MAX.
**Returns:** Returns the number of bytes written if the operation is successful; returns **-1** and sets **errno** to a value if the operation fails. If **errno** is set to **EINVAL**, the sum of the **iov\_len** values overflows an **ssize\_t** value, or the vector count **iovcnt** is less than 0 or greater than the permitted maximum.