IO.md

# 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.