1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2015-02-04 23:33+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man3/asprintf.3:27
26 #: build/C/man3/asprintf.3:27 build/C/man3/fcloseall.3:25 build/C/man3/fmtmsg.3:13 build/C/man3/stdio_ext.3:25
32 #: build/C/man3/asprintf.3:27 build/C/man3/ctermid.3:26 build/C/man3/dprintf.3:26 build/C/man3/fclose.3:44 build/C/man3/fcloseall.3:25 build/C/man3/fflush.3:45 build/C/man3/fgetc.3:27 build/C/man3/fgetwc.3:18 build/C/man3/fmemopen.3:10 build/C/man3/fopen.3:44 build/C/man3/fputwc.3:16 build/C/man3/fread.3:45 build/C/man3/fseek.3:42 build/C/man3/getline.3:26 build/C/man3/gets.3:29 build/C/man3/getw.3:25 build/C/man3/popen.3:40 build/C/man3/printf.3:34 build/C/man3/puts.3:26 build/C/man3/remove.3:31 build/C/man3/scanf.3:52 build/C/man3/wprintf.3:16
38 #: build/C/man3/asprintf.3:27 build/C/man3/ctermid.3:26 build/C/man3/dprintf.3:26 build/C/man3/fclose.3:44 build/C/man3/fcloseall.3:25 build/C/man3/ferror.3:44 build/C/man3/fflush.3:45 build/C/man3/fgetc.3:27 build/C/man3/fgetwc.3:18 build/C/man3/flockfile.3:25 build/C/man3/fmemopen.3:10 build/C/man3/fmtmsg.3:13 build/C/man3/fopen.3:44 build/C/man3/fopencookie.3:26 build/C/man3/fpurge.3:25 build/C/man3/fputwc.3:16 build/C/man3/fread.3:45 build/C/man3/fseek.3:42 build/C/man3/fseeko.3:25 build/C/man3/getline.3:26 build/C/man3/gets.3:29 build/C/man3/getw.3:25 build/C/man2/link.2:32 build/C/man2/llseek.2:28 build/C/man2/lseek.2:47 build/C/man3/lseek64.3:25 build/C/man2/open.2:51 build/C/man2/open_by_handle_at.2:25 build/C/man3/perror.3:31 build/C/man2/pipe.2:36 build/C/man3/popen.3:40 build/C/man3/printf.3:34 build/C/man3/puts.3:26 build/C/man2/read.2:35 build/C/man2/readlink.2:44 build/C/man2/readv.2:32 build/C/man3/remove.3:31 build/C/man2/rename.2:33 build/C/man2/rmdir.2:30 build/C/man3/scanf.3:52 build/C/man3/setbuf.3:48 build/C/man3/stdin.3:13 build/C/man3/stdio.3:39 build/C/man3/stdio_ext.3:25 build/C/man2/symlink.2:33 build/C/man7/symlink.7:37 build/C/man3/tempnam.3:25 build/C/man3/tmpfile.3:31 build/C/man3/tmpnam.3:27 build/C/man2/unlink.2:33 build/C/man3/unlocked_stdio.3:25 build/C/man3/wprintf.3:16 build/C/man2/write.2:39
40 msgid "Linux Programmer's Manual"
44 #: build/C/man3/asprintf.3:28 build/C/man3/ctermid.3:27 build/C/man3/dprintf.3:27 build/C/man3/fclose.3:45 build/C/man3/fcloseall.3:26 build/C/man3/ferror.3:45 build/C/man3/fflush.3:46 build/C/man3/fgetc.3:28 build/C/man3/fgetwc.3:19 build/C/man3/flockfile.3:26 build/C/man3/fmemopen.3:11 build/C/man3/fmtmsg.3:14 build/C/man3/fopen.3:45 build/C/man3/fopencookie.3:27 build/C/man3/fpurge.3:26 build/C/man3/fputwc.3:17 build/C/man3/fread.3:46 build/C/man3/fseek.3:43 build/C/man3/fseeko.3:26 build/C/man3/getline.3:27 build/C/man3/gets.3:30 build/C/man3/getw.3:26 build/C/man2/link.2:33 build/C/man2/llseek.2:29 build/C/man2/lseek.2:48 build/C/man3/lseek64.3:26 build/C/man2/open.2:52 build/C/man2/open_by_handle_at.2:26 build/C/man3/perror.3:32 build/C/man2/pipe.2:37 build/C/man3/popen.3:41 build/C/man3/printf.3:35 build/C/man3/puts.3:27 build/C/man2/read.2:36 build/C/man2/readlink.2:45 build/C/man2/readv.2:33 build/C/man3/remove.3:32 build/C/man2/rename.2:34 build/C/man2/rmdir.2:31 build/C/man3/scanf.3:53 build/C/man3/setbuf.3:49 build/C/man3/stdin.3:14 build/C/man3/stdio.3:40 build/C/man3/stdio_ext.3:26 build/C/man2/symlink.2:34 build/C/man7/symlink.7:38 build/C/man3/tempnam.3:26 build/C/man3/tmpfile.3:32 build/C/man3/tmpnam.3:28 build/C/man2/unlink.2:34 build/C/man3/unlocked_stdio.3:26 build/C/man3/wprintf.3:17 build/C/man2/write.2:40
50 #: build/C/man3/asprintf.3:30
51 msgid "asprintf, vasprintf - print to allocated string"
55 #: build/C/man3/asprintf.3:30 build/C/man3/ctermid.3:29 build/C/man3/dprintf.3:29 build/C/man3/fclose.3:47 build/C/man3/fcloseall.3:28 build/C/man3/ferror.3:47 build/C/man3/fflush.3:48 build/C/man3/fgetc.3:30 build/C/man3/fgetwc.3:21 build/C/man3/flockfile.3:28 build/C/man3/fmemopen.3:13 build/C/man3/fmtmsg.3:16 build/C/man3/fopen.3:47 build/C/man3/fopencookie.3:29 build/C/man3/fpurge.3:28 build/C/man3/fputwc.3:19 build/C/man3/fread.3:48 build/C/man3/fseek.3:45 build/C/man3/fseeko.3:28 build/C/man3/getline.3:29 build/C/man3/gets.3:32 build/C/man3/getw.3:28 build/C/man2/link.2:35 build/C/man2/llseek.2:31 build/C/man2/lseek.2:50 build/C/man3/lseek64.3:28 build/C/man2/open.2:54 build/C/man2/open_by_handle_at.2:29 build/C/man3/perror.3:34 build/C/man2/pipe.2:39 build/C/man3/popen.3:43 build/C/man3/printf.3:38 build/C/man3/puts.3:29 build/C/man2/read.2:38 build/C/man2/readlink.2:47 build/C/man2/readv.2:35 build/C/man3/remove.3:34 build/C/man2/rename.2:36 build/C/man2/rmdir.2:33 build/C/man3/scanf.3:55 build/C/man3/setbuf.3:51 build/C/man3/stdin.3:16 build/C/man3/stdio.3:42 build/C/man3/stdio_ext.3:30 build/C/man2/symlink.2:36 build/C/man3/tempnam.3:28 build/C/man3/tmpfile.3:34 build/C/man3/tmpnam.3:30 build/C/man2/unlink.2:36 build/C/man3/unlocked_stdio.3:29 build/C/man3/wprintf.3:20 build/C/man2/write.2:42
61 #: build/C/man3/asprintf.3:32
62 msgid "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */"
66 #: build/C/man3/asprintf.3:34 build/C/man3/dprintf.3:31 build/C/man3/fclose.3:49 build/C/man3/ferror.3:49 build/C/man3/fflush.3:50 build/C/man3/fseek.3:47 build/C/man3/perror.3:36 build/C/man3/printf.3:40 build/C/man3/remove.3:36 build/C/man3/stdio.3:44 build/C/man3/stdio_ext.3:32
67 msgid "B<#include E<lt>stdio.hE<gt>>"
71 #: build/C/man3/asprintf.3:36
72 msgid "B<int asprintf(char **>I<strp>B<, const char *>I<fmt>B<, ...);>"
76 #: build/C/man3/asprintf.3:38
78 "B<int vasprintf(char **>I<strp>B<, const char *>I<fmt>B<, va_list "
83 #: build/C/man3/asprintf.3:38 build/C/man3/ctermid.3:46 build/C/man3/dprintf.3:55 build/C/man3/fclose.3:51 build/C/man3/fcloseall.3:35 build/C/man3/ferror.3:65 build/C/man3/fflush.3:52 build/C/man3/fgetc.3:44 build/C/man3/fgetwc.3:30 build/C/man3/flockfile.3:51 build/C/man3/fmemopen.3:46 build/C/man3/fmtmsg.3:26 build/C/man3/fopen.3:65 build/C/man3/fopencookie.3:37 build/C/man3/fpurge.3:42 build/C/man3/fputwc.3:28 build/C/man3/fread.3:58 build/C/man3/fseek.3:57 build/C/man3/fseeko.3:54 build/C/man3/getline.3:58 build/C/man3/gets.3:38 build/C/man3/getw.3:59 build/C/man2/link.2:66 build/C/man2/llseek.2:43 build/C/man2/lseek.2:56 build/C/man3/lseek64.3:36 build/C/man2/open.2:88 build/C/man2/open_by_handle_at.2:43 build/C/man3/perror.3:55 build/C/man2/pipe.2:51 build/C/man3/popen.3:64 build/C/man3/printf.3:76 build/C/man3/puts.3:43 build/C/man2/read.2:44 build/C/man2/readlink.2:86 build/C/man2/readv.2:58 build/C/man3/remove.3:38 build/C/man2/rename.2:72 build/C/man2/rmdir.2:37 build/C/man3/scanf.3:87 build/C/man3/setbuf.3:73 build/C/man3/stdin.3:24 build/C/man3/stdio.3:50 build/C/man3/stdio_ext.3:54 build/C/man2/symlink.2:74 build/C/man7/symlink.7:40 build/C/man3/tempnam.3:42 build/C/man3/tmpfile.3:40 build/C/man3/tmpnam.3:36 build/C/man2/unlink.2:66 build/C/man3/unlocked_stdio.3:106 build/C/man3/wprintf.3:58 build/C/man2/write.2:46
89 #: build/C/man3/asprintf.3:53
91 "The functions B<asprintf>() and B<vasprintf>() are analogs of "
92 "B<sprintf>(3) and B<vsprintf>(3), except that they allocate a string large "
93 "enough to hold the output including the terminating null byte "
94 "(\\(aq\\e0\\(aq), and return a pointer to it via the first argument. This "
95 "pointer should be passed to B<free>(3) to release the allocated storage "
96 "when it is no longer needed."
100 #: build/C/man3/asprintf.3:53 build/C/man3/ctermid.3:59 build/C/man3/fclose.3:59 build/C/man3/fcloseall.3:50 build/C/man3/fflush.3:79 build/C/man3/fgetc.3:99 build/C/man3/fgetwc.3:55 build/C/man3/flockfile.3:120 build/C/man3/fmemopen.3:180 build/C/man3/fmtmsg.3:152 build/C/man3/fopen.3:189 build/C/man3/fopencookie.3:238 build/C/man3/fpurge.3:58 build/C/man3/fputwc.3:54 build/C/man3/fread.3:83 build/C/man3/fseek.3:121 build/C/man3/fseeko.3:88 build/C/man3/getline.3:112 build/C/man3/gets.3:50 build/C/man3/getw.3:73 build/C/man2/link.2:187 build/C/man2/llseek.2:62 build/C/man2/lseek.2:179 build/C/man2/open.2:774 build/C/man2/open_by_handle_at.2:245 build/C/man2/pipe.2:133 build/C/man3/popen.3:123 build/C/man3/puts.3:84 build/C/man2/read.2:81 build/C/man2/readlink.2:153 build/C/man2/readv.2:177 build/C/man3/remove.3:60 build/C/man2/rename.2:203 build/C/man2/rmdir.2:40 build/C/man3/scanf.3:530 build/C/man3/setbuf.3:152 build/C/man2/symlink.2:140 build/C/man3/tempnam.3:94 build/C/man3/tmpfile.3:47 build/C/man3/tmpnam.3:79 build/C/man2/unlink.2:153 build/C/man3/wprintf.3:203 build/C/man2/write.2:89
106 #: build/C/man3/asprintf.3:61
108 "When successful, these functions return the number of bytes printed, just "
109 "like B<sprintf>(3). If memory allocation wasn't possible, or some other "
110 "error occurs, these functions will return -1, and the contents of I<strp> is "
115 #: build/C/man3/asprintf.3:61 build/C/man3/ctermid.3:67 build/C/man3/dprintf.3:69 build/C/man3/fclose.3:90 build/C/man3/fcloseall.3:60 build/C/man3/ferror.3:115 build/C/man3/fflush.3:103 build/C/man3/fgetc.3:124 build/C/man3/fgetwc.3:70 build/C/man3/flockfile.3:135 build/C/man3/fmemopen.3:199 build/C/man3/fmtmsg.3:237 build/C/man3/fopen.3:246 build/C/man3/fopencookie.3:245 build/C/man3/fpurge.3:70 build/C/man3/fputwc.3:68 build/C/man3/fread.3:103 build/C/man3/fseek.3:169 build/C/man3/fseeko.3:102 build/C/man3/getline.3:137 build/C/man3/gets.3:58 build/C/man3/getw.3:80 build/C/man2/link.2:338 build/C/man2/llseek.2:81 build/C/man2/lseek.2:217 build/C/man2/open.2:1020 build/C/man2/open_by_handle_at.2:352 build/C/man3/perror.3:111 build/C/man2/pipe.2:159 build/C/man3/popen.3:172 build/C/man3/printf.3:825 build/C/man3/puts.3:103 build/C/man2/read.2:173 build/C/man2/readlink.2:216 build/C/man2/readv.2:216 build/C/man3/remove.3:75 build/C/man2/rename.2:405 build/C/man2/rmdir.2:127 build/C/man3/scanf.3:577 build/C/man3/setbuf.3:173 build/C/man3/stdin.3:113 build/C/man3/stdio.3:246 build/C/man2/symlink.2:228 build/C/man3/tempnam.3:105 build/C/man3/tmpfile.3:78 build/C/man3/tmpnam.3:96 build/C/man2/unlink.2:273 build/C/man3/unlocked_stdio.3:113 build/C/man3/wprintf.3:211 build/C/man2/write.2:189
117 msgid "CONFORMING TO"
121 #: build/C/man3/asprintf.3:67
123 "These functions are GNU extensions, not in C or POSIX. They are also "
124 "available under *BSD. The FreeBSD implementation sets I<strp> to NULL on "
129 #: build/C/man3/asprintf.3:67 build/C/man3/ctermid.3:77 build/C/man3/dprintf.3:95 build/C/man3/fclose.3:102 build/C/man3/fcloseall.3:62 build/C/man3/ferror.3:126 build/C/man3/fflush.3:117 build/C/man3/fgetc.3:133 build/C/man3/fgetwc.3:87 build/C/man3/flockfile.3:141 build/C/man3/fmemopen.3:345 build/C/man3/fmtmsg.3:309 build/C/man3/fopen.3:348 build/C/man3/fopencookie.3:437 build/C/man3/fpurge.3:80 build/C/man3/fputwc.3:85 build/C/man3/fread.3:105 build/C/man3/fseek.3:171 build/C/man3/fseeko.3:106 build/C/man3/getline.3:172 build/C/man3/gets.3:90 build/C/man3/getw.3:87 build/C/man2/link.2:411 build/C/man2/llseek.2:87 build/C/man2/lseek.2:267 build/C/man3/lseek64.3:161 build/C/man2/open.2:1503 build/C/man2/open_by_handle_at.2:720 build/C/man3/perror.3:139 build/C/man2/pipe.2:232 build/C/man3/popen.3:201 build/C/man3/printf.3:1106 build/C/man3/puts.3:112 build/C/man2/read.2:226 build/C/man2/readlink.2:328 build/C/man2/readv.2:320 build/C/man3/remove.3:86 build/C/man2/rename.2:443 build/C/man2/rmdir.2:132 build/C/man3/scanf.3:738 build/C/man3/setbuf.3:209 build/C/man3/stdin.3:154 build/C/man3/stdio.3:250 build/C/man3/stdio_ext.3:151 build/C/man2/symlink.2:260 build/C/man7/symlink.7:512 build/C/man3/tempnam.3:168 build/C/man3/tmpfile.3:97 build/C/man3/tmpnam.3:172 build/C/man2/unlink.2:300 build/C/man3/unlocked_stdio.3:136 build/C/man3/wprintf.3:251 build/C/man2/write.2:254
135 #: build/C/man3/asprintf.3:71
136 msgid "B<free>(3), B<malloc>(3), B<printf>(3)"
140 #: build/C/man3/asprintf.3:71 build/C/man3/ctermid.3:79 build/C/man3/dprintf.3:97 build/C/man3/fclose.3:108 build/C/man3/fcloseall.3:68 build/C/man3/ferror.3:131 build/C/man3/fflush.3:125 build/C/man3/fgetc.3:150 build/C/man3/fgetwc.3:92 build/C/man3/flockfile.3:143 build/C/man3/fmemopen.3:348 build/C/man3/fmtmsg.3:312 build/C/man3/fopen.3:354 build/C/man3/fopencookie.3:442 build/C/man3/fpurge.3:85 build/C/man3/fputwc.3:89 build/C/man3/fread.3:111 build/C/man3/fseek.3:174 build/C/man3/fseeko.3:108 build/C/man3/getline.3:178 build/C/man3/gets.3:108 build/C/man3/getw.3:93 build/C/man2/link.2:420 build/C/man2/llseek.2:90 build/C/man2/lseek.2:274 build/C/man3/lseek64.3:164 build/C/man2/open.2:1525 build/C/man2/open_by_handle_at.2:736 build/C/man3/perror.3:144 build/C/man2/pipe.2:239 build/C/man3/popen.3:211 build/C/man3/printf.3:1115 build/C/man3/puts.3:124 build/C/man2/read.2:239 build/C/man2/readlink.2:336 build/C/man2/readv.2:324 build/C/man3/remove.3:97 build/C/man2/rename.2:451 build/C/man2/rmdir.2:141 build/C/man3/scanf.3:745 build/C/man3/setbuf.3:217 build/C/man3/stdin.3:160 build/C/man3/stdio.3:257 build/C/man3/stdio_ext.3:154 build/C/man2/symlink.2:271 build/C/man7/symlink.7:530 build/C/man3/tempnam.3:173 build/C/man3/tmpfile.3:103 build/C/man3/tmpnam.3:177 build/C/man2/unlink.2:312 build/C/man3/unlocked_stdio.3:139 build/C/man3/wprintf.3:258 build/C/man2/write.2:266
146 #: build/C/man3/asprintf.3:79 build/C/man3/ctermid.3:87 build/C/man3/dprintf.3:105 build/C/man3/fclose.3:116 build/C/man3/fcloseall.3:76 build/C/man3/ferror.3:139 build/C/man3/fflush.3:133 build/C/man3/fgetc.3:158 build/C/man3/fgetwc.3:100 build/C/man3/flockfile.3:151 build/C/man3/fmemopen.3:356 build/C/man3/fmtmsg.3:320 build/C/man3/fopen.3:362 build/C/man3/fopencookie.3:450 build/C/man3/fpurge.3:93 build/C/man3/fputwc.3:97 build/C/man3/fread.3:119 build/C/man3/fseek.3:182 build/C/man3/fseeko.3:116 build/C/man3/getline.3:186 build/C/man3/gets.3:116 build/C/man3/getw.3:101 build/C/man2/link.2:428 build/C/man2/llseek.2:98 build/C/man2/lseek.2:282 build/C/man3/lseek64.3:172 build/C/man2/open.2:1533 build/C/man2/open_by_handle_at.2:744 build/C/man3/perror.3:152 build/C/man2/pipe.2:247 build/C/man3/popen.3:219 build/C/man3/printf.3:1123 build/C/man3/puts.3:132 build/C/man2/read.2:247 build/C/man2/readlink.2:344 build/C/man2/readv.2:332 build/C/man3/remove.3:105 build/C/man2/rename.2:459 build/C/man2/rmdir.2:149 build/C/man3/scanf.3:753 build/C/man3/setbuf.3:225 build/C/man3/stdin.3:168 build/C/man3/stdio.3:265 build/C/man3/stdio_ext.3:162 build/C/man2/symlink.2:279 build/C/man7/symlink.7:538 build/C/man3/tempnam.3:181 build/C/man3/tmpfile.3:111 build/C/man3/tmpnam.3:185 build/C/man2/unlink.2:320 build/C/man3/unlocked_stdio.3:147 build/C/man3/wprintf.3:266 build/C/man2/write.2:274
148 "This page is part of release 3.79 of the Linux I<man-pages> project. A "
149 "description of the project, information about reporting bugs, and the latest "
150 "version of this page, can be found at "
151 "\\%http://www.kernel.org/doc/man-pages/."
155 #: build/C/man3/ctermid.3:26
161 #: build/C/man3/ctermid.3:26
167 #: build/C/man3/ctermid.3:29
168 msgid "ctermid - get controlling terminal name"
172 #: build/C/man3/ctermid.3:34 build/C/man3/fgetc.3:33 build/C/man3/fgetwc.3:24 build/C/man3/flockfile.3:31 build/C/man3/fmemopen.3:16 build/C/man3/fopen.3:50 build/C/man3/fputwc.3:22 build/C/man3/fread.3:51 build/C/man3/fseeko.3:31 build/C/man3/getline.3:32 build/C/man3/gets.3:35 build/C/man3/getw.3:31 build/C/man3/popen.3:46 build/C/man3/puts.3:32 build/C/man2/rename.2:39 build/C/man3/scanf.3:58 build/C/man3/setbuf.3:54 build/C/man3/stdin.3:19 build/C/man3/tempnam.3:31 build/C/man3/tmpfile.3:37 build/C/man3/tmpnam.3:33 build/C/man3/unlocked_stdio.3:32
174 msgid "B<#include E<lt>stdio.hE<gt>>\n"
178 #: build/C/man3/ctermid.3:36
180 msgid "B<char *ctermid(char *>I<s>B<);>\n"
184 #: build/C/man3/ctermid.3:41 build/C/man3/dprintf.3:39 build/C/man3/ferror.3:61 build/C/man3/flockfile.3:42 build/C/man3/fmemopen.3:29 build/C/man3/fopen.3:61 build/C/man3/fseeko.3:41 build/C/man3/getline.3:42 build/C/man3/getw.3:40 build/C/man2/link.2:51 build/C/man2/open.2:73 build/C/man3/perror.3:50 build/C/man3/popen.3:55 build/C/man3/printf.3:63 build/C/man2/readlink.2:64 build/C/man2/readv.2:53 build/C/man2/rename.2:56 build/C/man3/scanf.3:73 build/C/man3/setbuf.3:68 build/C/man2/symlink.2:52 build/C/man3/tempnam.3:38 build/C/man2/unlink.2:51 build/C/man3/unlocked_stdio.3:68 build/C/man3/wprintf.3:39
185 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
188 #. From <unistd.h>: _XOPEN_SOURCE
190 #: build/C/man3/ctermid.3:46
191 msgid "B<ctermid>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE"
195 #: build/C/man3/ctermid.3:59
197 "B<ctermid>() returns a string which is the pathname for the current "
198 "controlling terminal for this process. If I<s> is NULL, a static buffer is "
199 "used, otherwise I<s> points to a buffer used to hold the terminal pathname. "
200 "The symbolic constant B<L_ctermid> is the maximum number of characters in "
201 "the returned pathname."
205 #: build/C/man3/ctermid.3:61
206 msgid "The pointer to the pathname."
210 #: build/C/man3/ctermid.3:61 build/C/man3/fcloseall.3:55 build/C/man3/ferror.3:106 build/C/man3/fflush.3:98 build/C/man3/flockfile.3:127 build/C/man3/fmtmsg.3:225 build/C/man3/lseek64.3:156 build/C/man3/remove.3:70 build/C/man3/setbuf.3:164 build/C/man3/stdio_ext.3:132 build/C/man3/tmpnam.3:86
216 #: build/C/man3/ctermid.3:62 build/C/man3/fcloseall.3:56 build/C/man3/ferror.3:107 build/C/man3/fflush.3:99 build/C/man3/flockfile.3:128 build/C/man3/fmtmsg.3:226 build/C/man3/lseek64.3:157 build/C/man3/remove.3:71 build/C/man3/setbuf.3:165 build/C/man3/stdio_ext.3:133 build/C/man3/tmpnam.3:87
218 msgid "Multithreading (see pthreads(7))"
222 #: build/C/man3/ctermid.3:67
224 "The B<ctermid>() function is thread-safe with exceptions. It is not "
225 "thread-safe if called with a NULL parameter."
229 #: build/C/man3/ctermid.3:69
230 msgid "Svr4, POSIX.1-2001."
234 #: build/C/man3/ctermid.3:69 build/C/man3/fmemopen.3:217 build/C/man3/fopen.3:331 build/C/man3/gets.3:72 build/C/man3/getw.3:83 build/C/man2/link.2:405 build/C/man2/open.2:1484 build/C/man3/popen.3:178 build/C/man3/printf.3:951 build/C/man3/puts.3:105 build/C/man2/read.2:187 build/C/man2/readv.2:294 build/C/man3/remove.3:83 build/C/man2/rename.2:432 build/C/man2/rmdir.2:129 build/C/man3/scanf.3:669 build/C/man3/setbuf.3:179 build/C/man3/tempnam.3:165 build/C/man3/tmpnam.3:165 build/C/man2/unlink.2:297 build/C/man2/write.2:215
240 #: build/C/man3/ctermid.3:73
242 "The path returned may not uniquely identify the controlling terminal; it "
243 "may, for example, be I</dev/tty>."
246 #. in glibc 2.3.x, x >= 4, the glibc headers threw an error
247 #. if ctermid() was given an argument; fixed in 2.4.
249 #: build/C/man3/ctermid.3:77
250 msgid "It is not assured that the program can open the terminal."
254 #: build/C/man3/ctermid.3:79
255 msgid "B<ttyname>(3)"
259 #: build/C/man3/dprintf.3:26
265 #: build/C/man3/dprintf.3:26
271 #: build/C/man3/dprintf.3:29
272 msgid "dprintf, vdprintf - print to a file descriptor"
276 #: build/C/man3/dprintf.3:33
277 msgid "B<int dprintf(int >I<fd>B<, const char *>I<format>B<, ...);>"
281 #: build/C/man3/dprintf.3:35
282 msgid "B<int vdprintf(int >I<fd>B<, const char *>I<format>B<, va_list >I<ap>B<);>"
286 #: build/C/man3/dprintf.3:43
287 msgid "B<dprintf>(), B<vdprintf>():"
291 #: build/C/man3/dprintf.3:46 build/C/man3/fmemopen.3:37 build/C/man3/getline.3:49 build/C/man2/link.2:57 build/C/man2/open.2:79 build/C/man2/readlink.2:77 build/C/man2/rename.2:62 build/C/man2/symlink.2:65 build/C/man2/unlink.2:57
293 msgid "Since glibc 2.10:"
297 #: build/C/man3/dprintf.3:49 build/C/man3/fmemopen.3:40 build/C/man2/link.2:60 build/C/man2/open.2:82 build/C/man2/readlink.2:80 build/C/man2/rename.2:65 build/C/man2/symlink.2:68 build/C/man2/unlink.2:60
298 msgid "_XOPEN_SOURCE\\ E<gt>=\\ 700 || _POSIX_C_SOURCE\\ E<gt>=\\ 200809L"
302 #: build/C/man3/dprintf.3:49 build/C/man3/fmemopen.3:40 build/C/man3/getline.3:52 build/C/man2/link.2:60 build/C/man2/open.2:82 build/C/man2/readlink.2:80 build/C/man2/rename.2:65 build/C/man2/symlink.2:68 build/C/man2/unlink.2:60
304 msgid "Before glibc 2.10:"
308 #: build/C/man3/dprintf.3:52 build/C/man3/fmemopen.3:43 build/C/man3/getline.3:55 build/C/man3/unlocked_stdio.3:104
313 #: build/C/man3/dprintf.3:69
315 "The functions B<dprintf>() and B<vdprintf>() (as found in the glibc2 "
316 "library) are exact analogs of B<fprintf>(3) and B<vfprintf>(3), except that "
317 "they output to a file descriptor I<fd> instead of to a I<stdio> stream."
321 #. These functions are GNU extensions, not in C or POSIX.
322 #. Clearly, the names were badly chosen.
323 #. Many systems (like MacOS) have incompatible functions called
325 #. usually some debugging version of
327 #. perhaps with a prototype like
329 #. .BI "void dprintf(int level, const char *" format ", ...);"
331 #. where the first argument is a debugging level (and output is to
337 #. is also a popular macro name for a debugging printf.
338 #. So, probably, it is better to avoid this function in programs
339 #. intended to be portable.
341 #. A better name would have been
344 #: build/C/man3/dprintf.3:95
346 "These functions are GNU extensions that are nowadays specified in "
351 #: build/C/man3/dprintf.3:97
356 #: build/C/man3/fclose.3:44
362 #: build/C/man3/fclose.3:44 build/C/man3/fmemopen.3:10 build/C/man3/fopencookie.3:26 build/C/man3/getline.3:26 build/C/man2/open.2:51 build/C/man2/readv.2:32 build/C/man2/write.2:39
368 #: build/C/man3/fclose.3:47
369 msgid "fclose - close a stream"
373 #: build/C/man3/fclose.3:51
374 msgid "B<int fclose(FILE *>I<stream>B<);>"
378 #: build/C/man3/fclose.3:59
380 "The B<fclose>() function flushes the stream pointed to by I<stream> "
381 "(writing any buffered output data using B<fflush>(3)) and closes the "
382 "underlying file descriptor."
386 #: build/C/man3/fclose.3:70
388 "Upon successful completion 0 is returned. Otherwise, B<EOF> is returned and "
389 "I<errno> is set to indicate the error. In either case any further access "
390 "(including another call to B<fclose>()) to the stream results in undefined "
395 #: build/C/man3/fclose.3:70 build/C/man3/ferror.3:96 build/C/man3/fflush.3:86 build/C/man3/fgetwc.3:64 build/C/man3/flockfile.3:125 build/C/man3/fopen.3:201 build/C/man3/fpurge.3:65 build/C/man3/fputwc.3:63 build/C/man3/fseek.3:136 build/C/man3/fseeko.3:97 build/C/man3/getline.3:127 build/C/man2/link.2:192 build/C/man2/llseek.2:69 build/C/man2/lseek.2:187 build/C/man2/open.2:783 build/C/man2/open_by_handle_at.2:256 build/C/man2/pipe.2:138 build/C/man3/popen.3:146 build/C/man2/read.2:95 build/C/man2/readlink.2:159 build/C/man2/readv.2:188 build/C/man3/remove.3:65 build/C/man2/rename.2:208 build/C/man2/rmdir.2:45 build/C/man3/scanf.3:547 build/C/man2/symlink.2:145 build/C/man3/tempnam.3:101 build/C/man3/tmpfile.3:56 build/C/man3/tmpnam.3:84 build/C/man2/unlink.2:158 build/C/man2/write.2:107
401 #: build/C/man3/fclose.3:71 build/C/man3/fflush.3:87 build/C/man3/fpurge.3:66 build/C/man3/fseek.3:137 build/C/man2/link.2:276 build/C/man2/llseek.2:70 build/C/man2/lseek.2:188 build/C/man2/open.2:1006 build/C/man2/open_by_handle_at.2:317 build/C/man2/read.2:114 build/C/man2/readlink.2:202 build/C/man2/rename.2:349 build/C/man3/scanf.3:553 build/C/man2/symlink.2:208 build/C/man2/unlink.2:248 build/C/man2/write.2:126
406 #. This error cannot occur unless you are mixing ANSI C stdio operations and
407 #. low-level file operations on the same stream. If you do get this error,
408 #. you must have closed the stream's low-level file descriptor using
409 #. something like close(fileno(stream)).
411 #: build/C/man3/fclose.3:80
412 msgid "The file descriptor underlying I<stream> is not valid."
416 #: build/C/man3/fclose.3:90
418 "The B<fclose>() function may also fail and set I<errno> for any of the "
419 "errors specified for the routines B<close>(2), B<write>(2) or B<fflush>(3)."
423 #: build/C/man3/fclose.3:92 build/C/man3/fseek.3:171 build/C/man3/puts.3:105
428 #: build/C/man3/fclose.3:92 build/C/man3/fflush.3:108 build/C/man3/fgetwc.3:72 build/C/man3/fmemopen.3:211 build/C/man3/fmtmsg.3:252 build/C/man3/fopen.3:255 build/C/man3/fpurge.3:78 build/C/man3/fputwc.3:70 build/C/man3/fseeko.3:104 build/C/man2/link.2:347 build/C/man2/llseek.2:84 build/C/man2/lseek.2:227 build/C/man2/open.2:1064 build/C/man2/open_by_handle_at.2:359 build/C/man3/perror.3:124 build/C/man3/printf.3:889 build/C/man2/read.2:175 build/C/man2/readlink.2:225 build/C/man2/readv.2:228 build/C/man2/rename.2:414 build/C/man3/scanf.3:608 build/C/man3/stdin.3:122 build/C/man2/symlink.2:238 build/C/man3/tempnam.3:110 build/C/man3/tmpfile.3:80 build/C/man3/tmpnam.3:101 build/C/man2/unlink.2:281 build/C/man3/wprintf.3:213 build/C/man2/write.2:198
434 #: build/C/man3/fclose.3:102
436 "Note that B<fclose>() flushes only the user-space buffers provided by the C "
437 "library. To ensure that the data is physically stored on disk the kernel "
438 "buffers must be flushed too, for example, with B<sync>(2) or B<fsync>(2)."
442 #: build/C/man3/fclose.3:108
443 msgid "B<close>(2), B<fcloseall>(3), B<fflush>(3), B<fopen>(3), B<setbuf>(3)"
447 #: build/C/man3/fcloseall.3:25
453 #: build/C/man3/fcloseall.3:28
454 msgid "fcloseall - close all open streams"
458 #: build/C/man3/fcloseall.3:32 build/C/man3/fopencookie.3:33
461 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
462 "B<#include E<lt>stdio.hE<gt>>\n"
466 #: build/C/man3/fcloseall.3:34
468 msgid "B<int fcloseall(void);>\n"
472 #: build/C/man3/fcloseall.3:43
474 "The B<fcloseall>() function closes all of the calling process's open "
475 "streams. Buffered output for each stream is written before it is closed (as "
476 "for B<fflush>(3)); buffered input is discarded."
480 #: build/C/man3/fcloseall.3:50
481 msgid "The standard streams, I<stdin>, I<stdout>, and I<stderr> are also closed."
485 #: build/C/man3/fcloseall.3:55
487 "This function returns 0 if all files were successfully closed; on error, "
488 "B<EOF> is returned."
492 #: build/C/man3/fcloseall.3:60
494 "The B<fcloseall>() function does not lock the streams, so it is not "
499 #: build/C/man3/fcloseall.3:62
500 msgid "This function is a GNU extension."
504 #: build/C/man3/fcloseall.3:68
505 msgid "B<close>(2), B<fclose>(3), B<fflush>(3), B<fopen>(3), B<setbuf>(3)"
509 #: build/C/man3/ferror.3:44
515 #: build/C/man3/ferror.3:44
521 #: build/C/man3/ferror.3:47
522 msgid "clearerr, feof, ferror, fileno - check and reset stream status"
526 #: build/C/man3/ferror.3:51
527 msgid "B<void clearerr(FILE *>I<stream>B<);>"
531 #: build/C/man3/ferror.3:53
532 msgid "B<int feof(FILE *>I<stream>B<);>"
536 #: build/C/man3/ferror.3:55
537 msgid "B<int ferror(FILE *>I<stream>B<);>"
541 #: build/C/man3/ferror.3:57
542 msgid "B<int fileno(FILE *>I<stream>B<);>"
546 #: build/C/man3/ferror.3:65
547 msgid "B<fileno>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE"
551 #: build/C/man3/ferror.3:70
553 "The function B<clearerr>() clears the end-of-file and error indicators for "
554 "the stream pointed to by I<stream>."
558 #: build/C/man3/ferror.3:78
560 "The function B<feof>() tests the end-of-file indicator for the stream "
561 "pointed to by I<stream>, returning nonzero if it is set. The end-of-file "
562 "indicator can be cleared only by the function B<clearerr>()."
566 #: build/C/man3/ferror.3:87
568 "The function B<ferror>() tests the error indicator for the stream pointed "
569 "to by I<stream>, returning nonzero if it is set. The error indicator can be "
570 "reset only by the B<clearerr>() function."
574 #: build/C/man3/ferror.3:93
576 "The function B<fileno>() examines the argument I<stream> and returns its "
577 "integer descriptor."
581 #: build/C/man3/ferror.3:96 build/C/man3/fgetc.3:99 build/C/man3/fgetwc.3:55 build/C/man3/fputwc.3:54 build/C/man3/fread.3:83 build/C/man3/puts.3:84
582 msgid "For nonlocking counterparts, see B<unlocked_stdio>(3)."
586 #: build/C/man3/ferror.3:106
588 "These functions should not fail and do not set the external variable "
589 "I<errno>. (However, in case B<fileno>() detects that its argument is not a "
590 "valid stream, it must return -1 and set I<errno> to B<EBADF>.)"
594 #: build/C/man3/ferror.3:115
596 "The B<clearerr>(), B<feof>(), B<ferror>(), and B<fileno>() functions are "
601 #: build/C/man3/ferror.3:122
603 "The functions B<clearerr>(), B<feof>(), and B<ferror>() conform to C89, "
604 "C99, POSIX.1-2001, and POSIX.1-2008."
608 #: build/C/man3/ferror.3:126
609 msgid "The function B<fileno>() conforms to POSIX.1-2001 and POSIX.1-2008."
613 #: build/C/man3/ferror.3:131
614 msgid "B<open>(2), B<fdopen>(3), B<stdio>(3), B<unlocked_stdio>(3)"
618 #: build/C/man3/fflush.3:45
624 #: build/C/man3/fflush.3:45
630 #: build/C/man3/fflush.3:48
631 msgid "fflush - flush a stream"
635 #: build/C/man3/fflush.3:52
636 msgid "B<int fflush(FILE *>I<stream>B<);>"
640 #: build/C/man3/fflush.3:58
642 "For output streams, B<fflush>() forces a write of all user-space buffered "
643 "data for the given output or update I<stream> via the stream's underlying "
648 #: build/C/man3/fflush.3:64
650 "For input streams associated with seekable files (e.g., disk files, but not "
651 "pipes or terminals), B<fflush>() discards any buffered data that has been "
652 "fetched from the underlying file, but has not been consumed by the "
657 #: build/C/man3/fflush.3:66
658 msgid "The open status of the stream is unaffected."
661 #. mtk: POSIX specifies that only output streams are flushed for this case.
662 #. Also verified for glibc by experiment.
664 #: build/C/man3/fflush.3:76
666 "If the I<stream> argument is NULL, B<fflush>() flushes I<all> open output "
671 #: build/C/man3/fflush.3:79
672 msgid "For a nonlocking counterpart, see B<unlocked_stdio>(3)."
676 #: build/C/man3/fflush.3:86
678 "Upon successful completion 0 is returned. Otherwise, B<EOF> is returned and "
679 "I<errno> is set to indicate the error."
683 #: build/C/man3/fflush.3:91
684 msgid "I<stream> is not an open stream, or is not open for writing."
688 #: build/C/man3/fflush.3:98
690 "The function B<fflush>() may also fail and set I<errno> for any of the "
691 "errors specified for B<write>(2)."
695 #: build/C/man3/fflush.3:103
696 msgid "The B<fflush>() function is thread-safe."
700 #: build/C/man3/fflush.3:105
701 msgid "C89, C99, POSIX.1-2001, POSIX.1-2008."
705 #: build/C/man3/fflush.3:108
707 "POSIX.1-2001 did not specify the behavior for flushing of input streams, but "
708 "the behavior is specified in POSIX.1-2008."
712 #: build/C/man3/fflush.3:117
714 "Note that B<fflush>() flushes only the user-space buffers provided by the C "
715 "library. To ensure that the data is physically stored on disk the kernel "
716 "buffers must be flushed too, for example, with B<sync>(2) or B<fsync>(2)."
720 #: build/C/man3/fflush.3:125
722 "B<fsync>(2), B<sync>(2), B<write>(2), B<fclose>(3), B<fopen>(3), "
723 "B<setbuf>(3), B<unlocked_stdio>(3)"
727 #: build/C/man3/fgetc.3:27
733 #: build/C/man3/fgetc.3:27
739 #: build/C/man3/fgetc.3:30
740 msgid "fgetc, fgets, getc, getchar, ungetc - input of characters and strings"
744 #: build/C/man3/fgetc.3:35
746 msgid "B<int fgetc(FILE *>I<stream>B<);>\n"
750 #: build/C/man3/fgetc.3:37
752 msgid "B<char *fgets(char *>I<s>B<, int >I<size>B<, FILE *>I<stream>B<);>\n"
756 #: build/C/man3/fgetc.3:39
758 msgid "B<int getc(FILE *>I<stream>B<);>\n"
762 #: build/C/man3/fgetc.3:41
764 msgid "B<int getchar(void);>\n"
768 #: build/C/man3/fgetc.3:43
770 msgid "B<int ungetc(int >I<c>B<, FILE *>I<stream>B<);>\n"
774 #: build/C/man3/fgetc.3:55
776 "B<fgetc>() reads the next character from I<stream> and returns it as an "
777 "I<unsigned char> cast to an I<int>, or B<EOF> on end of file or error."
781 #: build/C/man3/fgetc.3:62
783 "B<getc>() is equivalent to B<fgetc>() except that it may be implemented as "
784 "a macro which evaluates I<stream> more than once."
788 #: build/C/man3/fgetc.3:66
789 msgid "B<getchar>() is equivalent to B<getc(>I<stdin>B<)>."
793 #: build/C/man3/fgetc.3:80
795 "B<fgets>() reads in at most one less than I<size> characters from I<stream> "
796 "and stores them into the buffer pointed to by I<s>. Reading stops after an "
797 "B<EOF> or a newline. If a newline is read, it is stored into the buffer. A "
798 "terminating null byte (\\(aq\\e0\\(aq) is stored after the last character "
803 #: build/C/man3/fgetc.3:91
805 "B<ungetc>() pushes I<c> back to I<stream>, cast to I<unsigned char>, where "
806 "it is available for subsequent read operations. Pushed-back characters will "
807 "be returned in reverse order; only one pushback is guaranteed."
811 #: build/C/man3/fgetc.3:96
813 "Calls to the functions described here can be mixed with each other and with "
814 "calls to other input functions from the I<stdio> library for the same input "
819 #: build/C/man3/fgetc.3:111
821 "B<fgetc>(), B<getc>() and B<getchar>() return the character read as an "
822 "I<unsigned char> cast to an I<int> or B<EOF> on end of file or error."
826 #: build/C/man3/fgetc.3:117
828 "B<fgets>() returns I<s> on success, and NULL on error or when end of file "
829 "occurs while no characters have been read."
833 #: build/C/man3/fgetc.3:124
834 msgid "B<ungetc>() returns I<c> on success, or B<EOF> on error."
838 #: build/C/man3/fgetc.3:126 build/C/man3/gets.3:60
839 msgid "C89, C99, POSIX.1-2001."
843 #: build/C/man3/fgetc.3:133
845 "It is not advisable to mix calls to input functions from the I<stdio> "
846 "library with low-level calls to B<read>(2) for the file descriptor "
847 "associated with the input stream; the results will be undefined and very "
848 "probably not what you want."
852 #: build/C/man3/fgetc.3:150
854 "B<read>(2), B<write>(2), B<ferror>(3), B<fgetwc>(3), B<fgetws>(3), "
855 "B<fopen>(3), B<fread>(3), B<fseek>(3), B<getline>(3), B<gets>(3), "
856 "B<getwchar>(3), B<puts>(3), B<scanf>(3), B<ungetwc>(3), "
857 "B<unlocked_stdio>(3), B<feature_test_macros>(7)"
861 #: build/C/man3/fgetwc.3:18
867 #: build/C/man3/fgetwc.3:18 build/C/man3/fputwc.3:16 build/C/man3/popen.3:40
873 #: build/C/man3/fgetwc.3:21
874 msgid "fgetwc, getwc - read a wide character from a FILE stream"
878 #: build/C/man3/fgetwc.3:26 build/C/man3/fmemopen.3:22 build/C/man3/fputwc.3:24 build/C/man3/unlocked_stdio.3:54
880 msgid "B<#include E<lt>wchar.hE<gt>>\n"
884 #: build/C/man3/fgetwc.3:29
887 "B<wint_t fgetwc(FILE *>I<stream>B<);>\n"
888 "B<wint_t getwc(FILE *>I<stream>B<);>\n"
892 #: build/C/man3/fgetwc.3:44
894 "The B<fgetwc>() function is the wide-character equivalent of the "
895 "B<fgetc>(3) function. It reads a wide character from I<stream> and returns "
896 "it. If the end of stream is reached, or if I<ferror(stream)> becomes true, "
897 "it returns B<WEOF>. If a wide-character conversion error occurs, it sets "
898 "I<errno> to B<EILSEQ> and returns B<WEOF>."
902 #: build/C/man3/fgetwc.3:52
904 "The B<getwc>() function or macro functions identically to B<fgetwc>(). It "
905 "may be implemented as a macro, and may evaluate its argument more than "
906 "once. There is no reason ever to use it."
910 #: build/C/man3/fgetwc.3:64
912 "The B<fgetwc>() function returns the next wide-character from the stream, "
913 "or B<WEOF>. In the event of an error, I<errno> is set to indicate the "
918 #: build/C/man3/fgetwc.3:66 build/C/man3/fputwc.3:65
919 msgid "Apart from the usual ones, there is"
923 #: build/C/man3/fgetwc.3:66 build/C/man3/fputwc.3:65 build/C/man3/scanf.3:558
929 #: build/C/man3/fgetwc.3:70
930 msgid "The data obtained from the input stream does not form a valid character."
934 #: build/C/man3/fgetwc.3:72 build/C/man3/fputwc.3:70
935 msgid "C99, POSIX.1-2001."
939 #: build/C/man3/fgetwc.3:79
941 "The behavior of B<fgetwc>() depends on the B<LC_CTYPE> category of the "
946 #: build/C/man3/fgetwc.3:87
948 "In the absence of additional information passed to the B<fopen>(3) call, it "
949 "is reasonable to expect that B<fgetwc>() will actually read a multibyte "
950 "sequence from the stream and then convert it to a wide character."
954 #: build/C/man3/fgetwc.3:92
955 msgid "B<fgetws>(3), B<fputwc>(3), B<ungetwc>(3), B<unlocked_stdio>(3)"
959 #: build/C/man3/flockfile.3:25
965 #: build/C/man3/flockfile.3:25 build/C/man2/link.2:32 build/C/man3/lseek64.3:25 build/C/man3/remove.3:31 build/C/man2/rename.2:33 build/C/man3/setbuf.3:48 build/C/man2/symlink.2:33 build/C/man2/unlink.2:33
971 #: build/C/man3/flockfile.3:28
972 msgid "flockfile, ftrylockfile, funlockfile - lock FILE for stdio"
976 #: build/C/man3/flockfile.3:33
978 msgid "B<void flockfile(FILE *>I<filehandle>B<);>\n"
982 #: build/C/man3/flockfile.3:35
984 msgid "B<int ftrylockfile(FILE *>I<filehandle>B<);>\n"
988 #: build/C/man3/flockfile.3:37
990 msgid "B<void funlockfile(FILE *>I<filehandle>B<);>\n"
994 #: build/C/man3/flockfile.3:46 build/C/man3/wprintf.3:43
995 msgid "All functions shown above:"
999 #: build/C/man3/flockfile.3:49
1001 "_POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE "
1006 #: build/C/man3/flockfile.3:63
1008 "The stdio functions are thread-safe. This is achieved by assigning to each "
1009 "I<FILE> object a lockcount and (if the lockcount is nonzero) an owning "
1010 "thread. For each library call, these functions wait until the I<FILE> "
1011 "object is no longer locked by a different thread, then lock it, do the "
1012 "requested I/O, and unlock the object again."
1016 #: build/C/man3/flockfile.3:69
1018 "(Note: this locking has nothing to do with the file locking done by "
1019 "functions like B<flock>(2) and B<lockf>(3).)"
1023 #: build/C/man3/flockfile.3:77
1025 "All this is invisible to the C-programmer, but there may be two reasons to "
1026 "wish for more detailed control. On the one hand, maybe a series of I/O "
1027 "actions by one thread belongs together, and should not be interrupted by the "
1028 "I/O of some other thread. On the other hand, maybe the locking overhead "
1029 "should be avoided for greater efficiency."
1033 #: build/C/man3/flockfile.3:94
1035 "To this end, a thread can explicitly lock the I<FILE> object, then do its "
1036 "series of I/O actions, then unlock. This prevents other threads from coming "
1037 "in between. If the reason for doing this was to achieve greater efficiency, "
1038 "one does the I/O with the nonlocking versions of the stdio functions: with "
1039 "B<getc_unlocked>(3) and B<putc_unlocked>(3) instead of B<getc>(3) and "
1044 #: build/C/man3/flockfile.3:105
1046 "The B<flockfile>() function waits for I<*filehandle> to be no longer locked "
1047 "by a different thread, then makes the current thread owner of "
1048 "I<*filehandle>, and increments the lockcount."
1052 #: build/C/man3/flockfile.3:109
1053 msgid "The B<funlockfile>() function decrements the lock count."
1057 #: build/C/man3/flockfile.3:120
1059 "The B<ftrylockfile>() function is a nonblocking version of B<flockfile>(). "
1060 "It does nothing in case some other thread owns I<*filehandle>, and it "
1061 "obtains ownership and increments the lockcount otherwise."
1065 #: build/C/man3/flockfile.3:125
1067 "The B<ftrylockfile>() function returns zero for success (the lock was "
1068 "obtained), and nonzero for failure."
1072 #: build/C/man3/flockfile.3:127
1077 #: build/C/man3/flockfile.3:135
1079 "The B<flockfile>(), B<ftrylockfile>(), and B<funlockfile>() functions are "
1084 #: build/C/man3/flockfile.3:137 build/C/man3/popen.3:174
1085 msgid "POSIX.1-2001."
1089 #: build/C/man3/flockfile.3:137
1091 msgid "AVAILABILITY"
1095 #: build/C/man3/flockfile.3:141
1097 "These functions are available when B<_POSIX_THREAD_SAFE_FUNCTIONS> is "
1102 #: build/C/man3/flockfile.3:143
1103 msgid "B<unlocked_stdio>(3)"
1107 #: build/C/man3/fmemopen.3:10
1113 #: build/C/man3/fmemopen.3:13
1114 msgid "fmemopen, open_memstream, open_wmemstream - open memory as stream"
1118 #: build/C/man3/fmemopen.3:18
1121 "B<FILE *fmemopen(void *>I<buf>B<, size_t >I<size>B<, const char "
1126 #: build/C/man3/fmemopen.3:20
1128 msgid "B<FILE *open_memstream(char **>I<ptr>B<, size_t *>I<sizeloc>B<);>\n"
1132 #: build/C/man3/fmemopen.3:24
1134 msgid "B<FILE *open_wmemstream(wchar_t **>I<ptr>B<, size_t *>I<sizeloc>B<);>\n"
1138 #: build/C/man3/fmemopen.3:34
1139 msgid "B<fmemopen>(), B<open_memstream>(), B<open_wmemstream>():"
1143 #: build/C/man3/fmemopen.3:57
1145 "The B<fmemopen>() function opens a stream that permits the access specified "
1146 "by I<mode>. The stream allows I/O to be performed on the string or memory "
1147 "buffer pointed to by I<buf>. This buffer must be at least I<size> bytes "
1152 #: build/C/man3/fmemopen.3:77
1154 "The argument I<mode> is the same as for B<fopen>(3). If I<mode> specifies "
1155 "an append mode, then the initial file position is set to the location of the "
1156 "first null byte (\\(aq\\e0\\(aq) in the buffer; otherwise the initial file "
1157 "position is set to the start of the buffer. Since glibc 2.9, the letter "
1158 "\\(aqb\\(aq may be specified as the second character in I<mode>. This "
1159 "provides \"binary\" mode: writes don't implicitly add a terminating null "
1160 "byte, and B<fseek>(3) B<SEEK_END> is relative to the end of the buffer "
1161 "(i.e., the value specified by the I<size> argument), rather than the current "
1166 #: build/C/man3/fmemopen.3:89
1168 "When a stream that has been opened for writing is flushed (B<fflush>(3)) or "
1169 "closed (B<fclose>(3)), a null byte is written at the end of the buffer if "
1170 "there is space. The caller should ensure that an extra byte is available in "
1171 "the buffer (and that I<size> counts that byte) to allow for this."
1175 #: build/C/man3/fmemopen.3:98
1177 "Attempts to write more than I<size> bytes to the buffer result in an error. "
1178 "(By default, such errors will be visible only when the I<stdio> buffer is "
1179 "flushed. Disabling buffering with the following call may be useful to "
1180 "detect errors at the time of an output operation:"
1184 #: build/C/man3/fmemopen.3:100
1186 msgid " setbuf(stdream, NULL);\n"
1190 #: build/C/man3/fmemopen.3:105
1192 "Alternatively, the caller can explicitly set I<buf> as the stdio stream "
1193 "buffer, at the same time informing stdio of the buffer's size, using:"
1197 #: build/C/man3/fmemopen.3:107
1199 msgid " setbuffer(stream, buf, size);\n"
1203 #: build/C/man3/fmemopen.3:119
1205 "In a stream opened for reading, null bytes (\\(aq\\e0\\(aq) in the buffer do "
1206 "not cause read operations to return an end-of-file indication. A read from "
1207 "the buffer will indicate end-of-file only when the file pointer advances "
1208 "I<size> bytes past the start of the buffer."
1212 #: build/C/man3/fmemopen.3:134
1214 "If I<buf> is specified as NULL, then B<fmemopen>() dynamically allocates a "
1215 "buffer I<size> bytes long. This is useful for an application that wants to "
1216 "write data to a temporary buffer and then read it back again. The buffer is "
1217 "automatically freed when the stream is closed. Note that the caller has no "
1218 "way to obtain a pointer to the temporary buffer allocated by this call (but "
1219 "see B<open_memstream>() below)."
1223 #: build/C/man3/fmemopen.3:145
1225 "The B<open_memstream>() function opens a stream for writing to a buffer. "
1226 "The buffer is dynamically allocated (as with B<malloc>(3)), and "
1227 "automatically grows as required. After closing the stream, the caller "
1228 "should B<free>(3) this buffer."
1232 #: build/C/man3/fmemopen.3:160
1234 "When the stream is closed (B<fclose>(3)) or flushed (B<fflush>(3)), the "
1235 "locations pointed to by I<ptr> and I<sizeloc> are updated to contain, "
1236 "respectively, a pointer to the buffer and the current size of the buffer. "
1237 "These values remain valid only as long as the caller performs no further "
1238 "output on the stream. If further output is performed, then the stream must "
1239 "again be flushed before trying to access these variables."
1243 #: build/C/man3/fmemopen.3:166
1245 "A null byte is maintained at the end of the buffer. This byte is I<not> "
1246 "included in the size value stored at I<sizeloc>."
1250 #: build/C/man3/fmemopen.3:174
1252 "The stream's file position can be changed with B<fseek>(3) or "
1253 "B<fseeko>(3). Moving the file position past the end of the data already "
1254 "written fills the intervening space with zeros."
1258 #: build/C/man3/fmemopen.3:180
1260 "The B<open_wmemstream>() is similar to B<open_memstream>(), but operates on "
1261 "wide characters instead of bytes."
1265 #: build/C/man3/fmemopen.3:192
1267 "Upon successful completion B<fmemopen>(), B<open_memstream>() and "
1268 "B<open_wmemstream>() return a I<FILE> pointer. Otherwise, NULL is returned "
1269 "and I<errno> is set to indicate the error."
1273 #: build/C/man3/fmemopen.3:192 build/C/man3/fmtmsg.3:222 build/C/man3/fseeko.3:100 build/C/man2/link.2:334 build/C/man2/open.2:1016 build/C/man2/open_by_handle_at.2:349 build/C/man2/pipe.2:154 build/C/man2/readlink.2:212 build/C/man2/readv.2:211 build/C/man2/rename.2:397 build/C/man2/symlink.2:224 build/C/man2/unlink.2:269
1279 #: build/C/man3/fmemopen.3:199
1281 "B<fmemopen>() and B<open_memstream>() were already available in glibc "
1282 "1.0.x. B<open_wmemstream>() is available since glibc 2.4."
1286 #: build/C/man3/fmemopen.3:203
1288 "POSIX.1-2008. These functions are not specified in POSIX.1-2001, and are "
1289 "not widely available on other systems."
1292 #. http://austingroupbugs.net/view.php?id=396
1294 #: build/C/man3/fmemopen.3:211
1296 "POSIX.1-2008 specifies that \\(aqb\\(aq in I<mode> shall be ignored. "
1297 "However, Technical Corrigendum 1 adjusts the standard to allow "
1298 "implementation-specific treatment for this case, thus permitting the glibc "
1299 "treatment of \\(aqb\\(aq."
1303 #: build/C/man3/fmemopen.3:217
1305 "There is no file descriptor associated with the file stream returned by "
1306 "these functions (i.e., B<fileno>(3) will return an error if called on the "
1310 #. http://sourceware.org/bugzilla/show_bug.cgi?id=1996
1312 #: build/C/man3/fmemopen.3:224
1314 "In glibc before version 2.7, seeking past the end of a stream created by "
1315 "B<open_memstream>() does not enlarge the buffer; instead the B<fseek>(3) "
1316 "call fails, returning -1."
1319 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216
1321 #: build/C/man3/fmemopen.3:235
1323 "If I<size> is specified as zero, B<fmemopen>() fails with the error "
1324 "B<EINVAL>. It would be more consistent if this case successfully created a "
1325 "stream that then returned end of file on the first attempt at reading. "
1326 "Furthermore, POSIX.1-2008 does not specify a failure for this case."
1329 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152
1331 #: build/C/man3/fmemopen.3:243
1333 "Specifying append mode (\"a\" or \"a+\") for B<fmemopen>() sets the initial "
1334 "file position to the first null byte, but (if the file offset is reset to a "
1335 "location other than the end of the stream) does not force subsequent writes "
1336 "to append at the end of the stream."
1339 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151
1341 #: build/C/man3/fmemopen.3:259
1343 "If the I<mode> argument to B<fmemopen>() specifies append (\"a\" or "
1344 "\"a+\"), and the I<size> argument does not cover a null byte in I<buf>, "
1345 "then, according to POSIX.1-2008, the initial file position should be set to "
1346 "the next byte after the end of the buffer. However, in this case the glibc "
1347 "B<fmemopen>() sets the file position to -1."
1350 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836
1352 #: build/C/man3/fmemopen.3:272
1354 "To specify binary mode for B<fmemopen>() the \\(aqb\\(aq must be the "
1355 "I<second> character in I<mode>. Thus, for example, \"wb+\" has the desired "
1356 "effect, but \"w+b\" does not. This is inconsistent with the treatment of "
1357 "I<mode> by B<fopen>(3)."
1360 #. http://sourceware.org/bugzilla/show_bug.cgi?id=6544
1362 #: build/C/man3/fmemopen.3:280
1364 "The glibc 2.9 addition of \"binary\" mode for B<fmemopen>() silently "
1365 "changed the ABI: previously, B<fmemopen>() ignored \\(aqb\\(aq in I<mode>."
1369 #: build/C/man3/fmemopen.3:280 build/C/man3/fmtmsg.3:256 build/C/man3/fopencookie.3:247 build/C/man3/getline.3:144 build/C/man2/open_by_handle_at.2:439 build/C/man2/pipe.2:165 build/C/man3/printf.3:995 build/C/man2/readlink.2:269 build/C/man2/readv.2:301 build/C/man3/scanf.3:704
1375 #: build/C/man3/fmemopen.3:290
1377 "The program below uses B<fmemopen>() to open an input buffer, and "
1378 "B<open_memstream>() to open a dynamically sized output buffer. The program "
1379 "scans its input string (taken from the program's first command-line "
1380 "argument) reading integers, and writes the squares of these integers to the "
1381 "output buffer. An example of the output produced by this program is the "
1386 #: build/C/man3/fmemopen.3:295
1389 "$B< ./a.out \\(aq1 23 43\\(aq>\n"
1390 "size=11; ptr=1 529 1849\n"
1394 #: build/C/man3/fmemopen.3:297 build/C/man3/fopencookie.3:271 build/C/man2/pipe.2:181
1396 msgid "Program source"
1400 #: build/C/man3/fmemopen.3:304
1403 "#define _GNU_SOURCE\n"
1404 "#include E<lt>string.hE<gt>\n"
1405 "#include E<lt>stdio.hE<gt>\n"
1406 "#include E<lt>stdlib.hE<gt>\n"
1410 #: build/C/man3/fmemopen.3:307
1413 "#define handle_error(msg) \\e\n"
1414 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
1418 #: build/C/man3/fmemopen.3:315
1422 "main(int argc, char *argv[])\n"
1424 " FILE *out, *in;\n"
1431 #: build/C/man3/fmemopen.3:320
1434 " if (argc != 2) {\n"
1435 " fprintf(stderr, \"Usage: %s E<lt>fileE<gt>\\en\", argv[0]);\n"
1436 " exit(EXIT_FAILURE);\n"
1441 #: build/C/man3/fmemopen.3:324
1444 " in = fmemopen(argv[1], strlen(argv[1]), \"r\");\n"
1445 " if (in == NULL)\n"
1446 " handle_error(\"fmemopen\");\n"
1450 #: build/C/man3/fmemopen.3:328
1453 " out = open_memstream(&ptr, &size);\n"
1454 " if (out == NULL)\n"
1455 " handle_error(\"open_memstream\");\n"
1459 #: build/C/man3/fmemopen.3:333
1463 " s = fscanf(in, \"%d\", &v);\n"
1464 " if (s E<lt>= 0)\n"
1469 #: build/C/man3/fmemopen.3:344
1472 " s = fprintf(out, \"%d \", v * v);\n"
1474 " handle_error(\"fprintf\");\n"
1478 " printf(\"size=%zu; ptr=%s\\en\", size, ptr);\n"
1480 " exit(EXIT_SUCCESS);\n"
1485 #: build/C/man3/fmemopen.3:348
1486 msgid "B<fopen>(3), B<fopencookie>(3)"
1490 #: build/C/man3/fmtmsg.3:13
1496 #: build/C/man3/fmtmsg.3:16
1497 msgid "fmtmsg - print formatted error messages"
1501 #: build/C/man3/fmtmsg.3:19
1503 msgid "B<#include E<lt>fmtmsg.hE<gt>>\n"
1507 #: build/C/man3/fmtmsg.3:21
1509 msgid "B<int fmtmsg(long >I<classification>B<, const char *>I<label>B<,>\n"
1513 #: build/C/man3/fmtmsg.3:23
1515 msgid "B< int >I<severity>B<, const char *>I<text>B<,>\n"
1519 #: build/C/man3/fmtmsg.3:25
1521 msgid "B< const char *>I<action>B<, const char *>I<tag>B<);>\n"
1525 #: build/C/man3/fmtmsg.3:36
1527 "This function displays a message described by its arguments on the device(s) "
1528 "specified in the I<classification> argument. For messages written to "
1529 "I<stderr>, the format depends on the B<MSGVERB> environment variable."
1533 #: build/C/man3/fmtmsg.3:43
1535 "The I<label> argument identifies the source of the message. The string must "
1536 "consist of two colon separated parts where the first part has not more than "
1537 "10 and the second part not more than 14 characters."
1541 #: build/C/man3/fmtmsg.3:47
1542 msgid "The I<text> argument describes the condition of the error."
1546 #: build/C/man3/fmtmsg.3:52
1548 "The I<action> argument describes possible steps to recover from the error. "
1549 "If it is printed, it is prefixed by \"TO FIX: \"."
1553 #: build/C/man3/fmtmsg.3:60
1555 "The I<tag> argument is a reference to the online documentation where more "
1556 "information can be found. It should contain the I<label> value and a unique "
1557 "identification number."
1561 #: build/C/man3/fmtmsg.3:60
1563 msgid "Dummy arguments"
1567 #: build/C/man3/fmtmsg.3:79
1569 "Each of the arguments can have a dummy value. The dummy classification "
1570 "value B<MM_NULLMC> (0L) does not specify any output, so nothing is printed. "
1571 "The dummy severity value B<NO_SEV> (0) says that no severity is supplied. "
1572 "The values B<MM_NULLLBL>, B<MM_NULLTXT>, B<MM_NULLACT>, B<MM_NULLTAG> are "
1573 "synonyms for I<((char\\ *)\\ 0)>, the empty string, and B<MM_NULLSEV> is a "
1574 "synonym for B<NO_SEV>."
1578 #: build/C/man3/fmtmsg.3:79
1580 msgid "The classification argument"
1584 #: build/C/man3/fmtmsg.3:83
1586 "The I<classification> argument is the sum of values describing 4 types of "
1591 #: build/C/man3/fmtmsg.3:86
1592 msgid "The first value defines the output channel."
1596 #: build/C/man3/fmtmsg.3:86
1602 #: build/C/man3/fmtmsg.3:90
1603 msgid "Output to I<stderr>."
1607 #: build/C/man3/fmtmsg.3:90
1609 msgid "B<MM_CONSOLE>"
1613 #: build/C/man3/fmtmsg.3:93
1614 msgid "Output to the system console."
1618 #: build/C/man3/fmtmsg.3:93
1620 msgid "B<MM_PRINT | MM_CONSOLE>"
1624 #: build/C/man3/fmtmsg.3:96
1625 msgid "Output to both."
1629 #: build/C/man3/fmtmsg.3:98
1630 msgid "The second value is the source of the error:"
1634 #: build/C/man3/fmtmsg.3:98
1640 #: build/C/man3/fmtmsg.3:101
1641 msgid "A hardware error occurred."
1645 #: build/C/man3/fmtmsg.3:101
1651 #: build/C/man3/fmtmsg.3:104
1652 msgid "A firmware error occurred."
1656 #: build/C/man3/fmtmsg.3:104
1662 #: build/C/man3/fmtmsg.3:107
1663 msgid "A software error occurred."
1667 #: build/C/man3/fmtmsg.3:109
1668 msgid "The third value encodes the detector of the problem:"
1672 #: build/C/man3/fmtmsg.3:109
1678 #: build/C/man3/fmtmsg.3:112
1679 msgid "It is detected by an application."
1683 #: build/C/man3/fmtmsg.3:112
1689 #: build/C/man3/fmtmsg.3:115
1690 msgid "It is detected by a utility."
1694 #: build/C/man3/fmtmsg.3:115
1700 #: build/C/man3/fmtmsg.3:118
1701 msgid "It is detected by the operating system."
1705 #: build/C/man3/fmtmsg.3:120
1706 msgid "The fourth value shows the severity of the incident:"
1710 #: build/C/man3/fmtmsg.3:120
1712 msgid "B<MM_RECOVER>"
1716 #: build/C/man3/fmtmsg.3:123
1717 msgid "It is a recoverable error."
1721 #: build/C/man3/fmtmsg.3:123
1723 msgid "B<MM_NRECOV>"
1727 #: build/C/man3/fmtmsg.3:126
1728 msgid "It is a nonrecoverable error."
1732 #: build/C/man3/fmtmsg.3:126
1734 msgid "The severity argument"
1738 #: build/C/man3/fmtmsg.3:130
1739 msgid "The I<severity> argument can take one of the following values:"
1743 #: build/C/man3/fmtmsg.3:130
1749 #: build/C/man3/fmtmsg.3:133
1750 msgid "No severity is printed."
1754 #: build/C/man3/fmtmsg.3:133
1760 #: build/C/man3/fmtmsg.3:136
1761 msgid "This value is printed as HALT."
1765 #: build/C/man3/fmtmsg.3:136
1771 #: build/C/man3/fmtmsg.3:139
1772 msgid "This value is printed as ERROR."
1776 #: build/C/man3/fmtmsg.3:139
1778 msgid "B<MM_WARNING>"
1782 #: build/C/man3/fmtmsg.3:142
1783 msgid "This value is printed as WARNING."
1787 #: build/C/man3/fmtmsg.3:142
1793 #: build/C/man3/fmtmsg.3:145
1794 msgid "This value is printed as INFO."
1798 #: build/C/man3/fmtmsg.3:152
1800 "The numeric values are between 0 and 4. Using B<addseverity>(3) or the "
1801 "environment variable B<SEV_LEVEL> you can add more levels and strings to "
1806 #: build/C/man3/fmtmsg.3:154
1807 msgid "The function can return 4 values:"
1811 #: build/C/man3/fmtmsg.3:154
1817 #: build/C/man3/fmtmsg.3:157
1818 msgid "Everything went smooth."
1822 #: build/C/man3/fmtmsg.3:157
1828 #: build/C/man3/fmtmsg.3:160
1829 msgid "Complete failure."
1833 #: build/C/man3/fmtmsg.3:160
1839 #: build/C/man3/fmtmsg.3:164
1840 msgid "Error writing to I<stderr>."
1844 #: build/C/man3/fmtmsg.3:164
1850 #: build/C/man3/fmtmsg.3:167
1851 msgid "Error writing to the console."
1855 #: build/C/man3/fmtmsg.3:167
1861 #: build/C/man3/fmtmsg.3:178
1863 "The environment variable B<MSGVERB> (\"message verbosity\") can be used to "
1864 "suppress parts of the output to I<stderr>. (It does not influence output to "
1865 "the console.) When this variable is defined, is non-NULL, and is a "
1866 "colon-separated list of valid keywords, then only the parts of the message "
1867 "corresponding to these keywords is printed. Valid keywords are \"label\", "
1868 "\"severity\", \"text\", \"action\" and \"tag\"."
1872 #: build/C/man3/fmtmsg.3:190
1874 "The environment variable B<SEV_LEVEL> can be used to introduce new severity "
1875 "levels. By default, only the five severity levels described above are "
1876 "available. Any other numeric value would make B<fmtmsg>() print nothing. "
1877 "If the user puts B<SEV_LEVEL> with a format like"
1881 #: build/C/man3/fmtmsg.3:193
1882 msgid "SEV_LEVEL=[description[:description[:...]]]"
1886 #: build/C/man3/fmtmsg.3:198
1888 "in the environment of the process before the first call to B<fmtmsg>(), "
1889 "where each description is of the form"
1893 #: build/C/man3/fmtmsg.3:201
1894 msgid "severity-keyword,level,printstring"
1898 #: build/C/man3/fmtmsg.3:208
1900 "then B<fmtmsg>() will also accept the indicated values for the level (in "
1901 "addition to the standard levels 0-4), and use the indicated printstring when "
1902 "such a level occurs."
1906 #: build/C/man3/fmtmsg.3:222
1908 "The severity-keyword part is not used by B<fmtmsg>() but it has to be "
1909 "present. The level part is a string representation of a number. The "
1910 "numeric value must be a number greater than 4. This value must be used in "
1911 "the severity argument of B<fmtmsg>() to select this class. It is not "
1912 "possible to overwrite any of the predefined classes. The printstring is the "
1913 "string printed when a message of this class is processed by B<fmtmsg>()."
1917 #: build/C/man3/fmtmsg.3:225
1918 msgid "B<fmtmsg>() is provided in glibc since version 2.1."
1922 #: build/C/man3/fmtmsg.3:231
1924 "Before glibc 2.16, the B<fmtmsg>() function uses a static variable that is "
1925 "not protected, so it is not thread-safe."
1928 #. Modified in commit 7724defcf8873116fe4efab256596861eef21a94
1930 #: build/C/man3/fmtmsg.3:237
1932 "Since glibc 2.16, the B<fmtmsg>() function uses a lock to protect the "
1933 "static variable, so it is thread-safe."
1937 #: build/C/man3/fmtmsg.3:252
1939 "The functions B<fmtmsg>() and B<addseverity>(3), and environment variables "
1940 "B<MSGVERB> and B<SEV_LEVEL> come from System V. The function B<fmtmsg>() "
1941 "and the environment variable B<MSGVERB> are described in POSIX.1-2001."
1945 #: build/C/man3/fmtmsg.3:256
1947 "System V and UnixWare man pages tell us that these functions have been "
1948 "replaced by \"pfmt() and addsev()\" or by \"pfmt(), vpfmt(), lfmt(), and "
1949 "vlfmt()\", and will be removed later."
1953 #: build/C/man3/fmtmsg.3:261
1956 "#include E<lt>stdio.hE<gt>\n"
1957 "#include E<lt>stdlib.hE<gt>\n"
1958 "#include E<lt>fmtmsg.hE<gt>\n"
1962 #: build/C/man3/fmtmsg.3:267
1968 " long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;\n"
1973 #: build/C/man3/fmtmsg.3:288
1976 " err = fmtmsg(class, \"util-linux:mount\", MM_ERROR,\n"
1977 " \"unknown mount option\", \"See mount(8).\",\n"
1978 " \"util-linux:mount:017\");\n"
1983 " printf(\"Nothing printed\\en\");\n"
1986 " printf(\"Nothing printed to stderr\\en\");\n"
1989 " printf(\"No console output\\en\");\n"
1992 " printf(\"Unknown error from fmtmsg()\\en\");\n"
1994 " exit(EXIT_SUCCESS);\n"
1999 #: build/C/man3/fmtmsg.3:291
2000 msgid "The output should be:"
2004 #: build/C/man3/fmtmsg.3:295
2007 " util-linux:mount: ERROR: unknown mount option\n"
2008 " TO FIX: See mount(8). util-linux:mount:017\n"
2012 #: build/C/man3/fmtmsg.3:298
2017 #: build/C/man3/fmtmsg.3:301
2019 msgid " MSGVERB=text:action; export MSGVERB\n"
2023 #: build/C/man3/fmtmsg.3:304
2024 msgid "the output becomes:"
2028 #: build/C/man3/fmtmsg.3:308
2031 " unknown mount option\n"
2032 " TO FIX: See mount(8).\n"
2036 #: build/C/man3/fmtmsg.3:312
2037 msgid "B<addseverity>(3), B<perror>(3)"
2041 #: build/C/man3/fopen.3:44
2047 #: build/C/man3/fopen.3:44
2053 #: build/C/man3/fopen.3:47
2054 msgid "fopen, fdopen, freopen - stream open functions"
2058 #: build/C/man3/fopen.3:52
2060 msgid "B<FILE *fopen(const char *>I<path>B<, const char *>I<mode>B<);>\n"
2064 #: build/C/man3/fopen.3:54
2066 msgid "B<FILE *fdopen(int >I<fd>B<, const char *>I<mode>B<);>\n"
2070 #: build/C/man3/fopen.3:56
2073 "B<FILE *freopen(const char *>I<path>B<, const char *>I<mode>B<, FILE "
2074 "*>I<stream>B<);>\n"
2078 #: build/C/man3/fopen.3:65
2079 msgid "B<fdopen>(): _POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE"
2083 #: build/C/man3/fopen.3:71
2085 "The B<fopen>() function opens the file whose name is the string pointed to "
2086 "by I<path> and associates a stream with it."
2090 #: build/C/man3/fopen.3:76
2092 "The argument I<mode> points to a string beginning with one of the following "
2093 "sequences (possibly followed by additional characters, as described below):"
2097 #: build/C/man3/fopen.3:76
2103 #: build/C/man3/fopen.3:80
2105 "Open text file for reading. The stream is positioned at the beginning of "
2110 #: build/C/man3/fopen.3:80
2116 #: build/C/man3/fopen.3:84
2118 "Open for reading and writing. The stream is positioned at the beginning of "
2123 #: build/C/man3/fopen.3:84
2129 #: build/C/man3/fopen.3:88
2131 "Truncate file to zero length or create text file for writing. The stream is "
2132 "positioned at the beginning of the file."
2136 #: build/C/man3/fopen.3:88
2142 #: build/C/man3/fopen.3:94
2144 "Open for reading and writing. The file is created if it does not exist, "
2145 "otherwise it is truncated. The stream is positioned at the beginning of the "
2150 #: build/C/man3/fopen.3:94 build/C/man3/scanf.3:447
2156 #: build/C/man3/fopen.3:99
2158 "Open for appending (writing at end of file). The file is created if it does "
2159 "not exist. The stream is positioned at the end of the file."
2163 #: build/C/man3/fopen.3:99
2169 #: build/C/man3/fopen.3:105
2171 "Open for reading and appending (writing at end of file). The file is "
2172 "created if it does not exist. The initial file position for reading is at "
2173 "the beginning of the file, but output is always appended to the end of the "
2178 #: build/C/man3/fopen.3:118
2180 "The I<mode> string can also include the letter \\(aqb\\(aq either as a last "
2181 "character or as a character between the characters in any of the "
2182 "two-character strings described above. This is strictly for compatibility "
2183 "with C89 and has no effect; the \\(aqb\\(aq is ignored on all POSIX "
2184 "conforming systems, including Linux. (Other systems may treat text files "
2185 "and binary files differently, and adding the \\(aqb\\(aq may be a good idea "
2186 "if you do I/O to a binary file and expect that your program may be ported to "
2187 "non-UNIX environments.)"
2191 #: build/C/man3/fopen.3:121
2192 msgid "See NOTES below for details of glibc extensions for I<mode>."
2196 #: build/C/man3/fopen.3:126
2198 "Any created files will have mode B<S_IRUSR> | B<S_IWUSR> | B<S_IRGRP> | "
2199 "B<S_IWGRP> | B<S_IROTH> | B<S_IWOTH> (0666), as modified by the process's "
2200 "umask value (see B<umask>(2))."
2204 #: build/C/man3/fopen.3:141
2206 "Reads and writes may be intermixed on read/write streams in any order. Note "
2207 "that ANSI C requires that a file positioning function intervene between "
2208 "output and input, unless an input operation encounters end-of-file. (If "
2209 "this condition is not met, then a read is allowed to return the result of "
2210 "writes other than the most recent.) Therefore it is good practice (and "
2211 "indeed sometimes necessary under Linux) to put an B<fseek>(3) or "
2212 "B<fgetpos>(3) operation between write and read operations on such a "
2213 "stream. This operation may be an apparent no-op (as in I<fseek(..., 0L, "
2214 "SEEK_CUR)> called for its synchronizing side effect)."
2218 #: build/C/man3/fopen.3:146
2220 "Opening a file in append mode (B<a> as the first character of I<mode>) "
2221 "causes all subsequent write operations to this stream to occur at "
2222 "end-of-file, as if preceded the call:"
2226 #: build/C/man3/fopen.3:149
2228 msgid " fseek(stream, 0, SEEK_END);\n"
2232 #: build/C/man3/fopen.3:171
2234 "The B<fdopen>() function associates a stream with the existing file "
2235 "descriptor, I<fd>. The I<mode> of the stream (one of the values \"r\", "
2236 "\"r+\", \"w\", \"w+\", \"a\", \"a+\") must be compatible with the mode of "
2237 "the file descriptor. The file position indicator of the new stream is set "
2238 "to that belonging to I<fd>, and the error and end-of-file indicators are "
2239 "cleared. Modes \"w\" or \"w+\" do not cause truncation of the file. The "
2240 "file descriptor is not dup'ed, and will be closed when the stream created by "
2241 "B<fdopen>() is closed. The result of applying B<fdopen>() to a shared "
2242 "memory object is undefined."
2246 #: build/C/man3/fopen.3:189
2248 "The B<freopen>() function opens the file whose name is the string pointed "
2249 "to by I<path> and associates the stream pointed to by I<stream> with it. "
2250 "The original stream (if it exists) is closed. The I<mode> argument is used "
2251 "just as in the B<fopen>() function. The primary use of the B<freopen>() "
2252 "function is to change the file associated with a standard text stream "
2253 "(I<stderr>, I<stdin>, or I<stdout>)."
2257 #: build/C/man3/fopen.3:201
2259 "Upon successful completion B<fopen>(), B<fdopen>() and B<freopen>() return "
2260 "a I<FILE> pointer. Otherwise, NULL is returned and I<errno> is set to "
2261 "indicate the error."
2265 #: build/C/man3/fopen.3:202 build/C/man3/fseek.3:142 build/C/man3/getline.3:128 build/C/man2/link.2:282 build/C/man2/llseek.2:77 build/C/man2/lseek.2:192 build/C/man2/open.2:825 build/C/man2/open.2:833 build/C/man2/open.2:838 build/C/man2/open_by_handle_at.2:273 build/C/man2/open_by_handle_at.2:277 build/C/man2/open_by_handle_at.2:325 build/C/man2/pipe.2:143 build/C/man2/read.2:126 build/C/man2/read.2:137 build/C/man2/readlink.2:169 build/C/man2/readlink.2:178 build/C/man2/readv.2:200 build/C/man2/readv.2:207 build/C/man2/rename.2:251 build/C/man2/rename.2:376 build/C/man2/rename.2:385 build/C/man2/rmdir.2:67 build/C/man3/scanf.3:565 build/C/man2/unlink.2:252 build/C/man2/write.2:154
2271 #: build/C/man3/fopen.3:212
2273 "The I<mode> provided to B<fopen>(), B<fdopen>(), or B<freopen>() was "
2278 #: build/C/man3/fopen.3:222
2280 "The B<fopen>(), B<fdopen>() and B<freopen>() functions may also fail and "
2281 "set I<errno> for any of the errors specified for the routine B<malloc>(3)."
2285 #: build/C/man3/fopen.3:229
2287 "The B<fopen>() function may also fail and set I<errno> for any of the "
2288 "errors specified for the routine B<open>(2)."
2292 #: build/C/man3/fopen.3:236
2294 "The B<fdopen>() function may also fail and set I<errno> for any of the "
2295 "errors specified for the routine B<fcntl>(2)."
2299 #: build/C/man3/fopen.3:246
2301 "The B<freopen>() function may also fail and set I<errno> for any of the "
2302 "errors specified for the routines B<open>(2), B<fclose>(3), and "
2307 #: build/C/man3/fopen.3:255
2309 "The B<fopen>() and B<freopen>() functions conform to C89. The B<fdopen>() "
2310 "function conforms to POSIX.1-1990."
2314 #: build/C/man3/fopen.3:256 build/C/man2/link.2:385 build/C/man2/readlink.2:256 build/C/man2/rename.2:415 build/C/man2/symlink.2:247 build/C/man2/unlink.2:282
2320 #: build/C/man3/fopen.3:259
2322 "The GNU C library allows the following extensions for the string specified "
2327 #: build/C/man3/fopen.3:259
2329 msgid "B<c> (since glibc 2.3.3)"
2333 #: build/C/man3/fopen.3:266
2335 "Do not make the open operation, or subsequent read and write operations, "
2336 "thread cancellation points. This flag is ignored for B<fdopen>()."
2340 #: build/C/man3/fopen.3:266
2342 msgid "B<e> (since glibc 2.7)"
2346 #: build/C/man3/fopen.3:276
2348 "Open the file with the B<O_CLOEXEC> flag. See B<open>(2) for more "
2349 "information. This flag is ignored for B<fdopen>()."
2353 #: build/C/man3/fopen.3:276
2355 msgid "B<m> (since glibc 2.3)"
2360 #: build/C/man3/fopen.3:288
2362 "Attempt to access the file using B<mmap>(2), rather than I/O system calls "
2363 "(B<read>(2), B<write>(2)). Currently, use of B<mmap>(2) is attempted only "
2364 "for a file opened for reading."
2368 #: build/C/man3/fopen.3:288 build/C/man3/scanf.3:421
2374 #. FIXME . C11 specifies this flag
2376 #: build/C/man3/fopen.3:305
2378 "Open the file exclusively (like the B<O_EXCL> flag of B<open>(2)). If the "
2379 "file already exists, B<fopen>() fails, and sets I<errno> to B<EEXIST>. "
2380 "This flag is ignored for B<fdopen>()."
2384 #: build/C/man3/fopen.3:313
2386 "In addition to the above characters, B<fopen>() and B<freopen>() support "
2387 "the following syntax in I<mode>:"
2391 #: build/C/man3/fopen.3:315
2392 msgid "B< ,ccs=>I<string>"
2396 #: build/C/man3/fopen.3:331
2398 "The given I<string> is taken as the name of a coded character set and the "
2399 "stream is marked as wide-oriented. Thereafter, internal conversion "
2400 "functions convert I/O to and from the character set I<string>. If the "
2401 "B<,ccs=>I<string> syntax is not specified, then the wide-orientation of the "
2402 "stream is determined by the first file operation. If that operation is a "
2403 "wide-character operation, the stream is marked wide-oriented, and functions "
2404 "to convert to the coded character set are loaded."
2407 #. FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685
2409 #: build/C/man3/fopen.3:348
2411 "When parsing for individual flag characters in I<mode> (i.e., the characters "
2412 "preceding the \"ccs\" specification), the glibc implementation of B<fopen>() "
2413 "and B<freopen>() limits the number of characters examined in I<mode> to 7 "
2414 "(or, in glibc versions before 2.14, to 6, which was not enough to include "
2415 "possible specifications such as \"rb+cmxe\"). The current implementation of "
2416 "B<fdopen>() parses at most 5 characters in I<mode>."
2420 #: build/C/man3/fopen.3:354
2421 msgid "B<open>(2), B<fclose>(3), B<fileno>(3), B<fmemopen>(3), B<fopencookie>(3)"
2425 #: build/C/man3/fopencookie.3:26
2431 #: build/C/man3/fopencookie.3:26 build/C/man2/link.2:32 build/C/man2/llseek.2:28 build/C/man2/lseek.2:47 build/C/man3/lseek64.3:25 build/C/man2/open.2:51 build/C/man2/open_by_handle_at.2:25 build/C/man2/pipe.2:36 build/C/man2/read.2:35 build/C/man2/readlink.2:44 build/C/man2/readv.2:32 build/C/man2/rename.2:33 build/C/man2/rmdir.2:30 build/C/man3/setbuf.3:48 build/C/man3/stdin.3:13 build/C/man2/symlink.2:33 build/C/man7/symlink.7:37 build/C/man2/unlink.2:33 build/C/man2/write.2:39
2437 #: build/C/man3/fopencookie.3:29
2438 msgid "fopencookie - opening a custom stream"
2442 #: build/C/man3/fopencookie.3:36
2445 "B<FILE *fopencookie(void *>I<cookie>B<, const char *>I<mode>B<,>\n"
2446 "B< cookie_io_functions_t >I<io_funcs>B<);>\n"
2450 #: build/C/man3/fopencookie.3:49
2452 "The B<fopencookie>() function allows the programmer to create a custom "
2453 "implementation for a standard I/O stream. This implementation can store the "
2454 "stream's data at a location of its own choosing; for example, "
2455 "B<fopencookie>() is used to implement B<fmemopen>(3), which provides a "
2456 "stream interface to data that is stored in a buffer in memory."
2460 #: build/C/man3/fopencookie.3:51
2461 msgid "In order to create a custom stream the programmer must:"
2465 #: build/C/man3/fopencookie.3:51 build/C/man3/fopencookie.3:54 build/C/man3/fopencookie.3:65 build/C/man2/lseek.2:168 build/C/man2/lseek.2:170 build/C/man2/lseek.2:173 build/C/man2/lseek.2:175 build/C/man2/lseek.2:177 build/C/man2/open.2:527 build/C/man2/open.2:535 build/C/man2/open.2:541 build/C/man2/open.2:547 build/C/man2/open.2:553 build/C/man2/open.2:566 build/C/man2/open.2:688 build/C/man2/open.2:696 build/C/man2/open_by_handle_at.2:138 build/C/man2/open_by_handle_at.2:146 build/C/man2/open_by_handle_at.2:157 build/C/man2/open_by_handle_at.2:170 build/C/man2/pipe.2:95 build/C/man2/pipe.2:105 build/C/man2/pipe.2:115 build/C/man3/scanf.3:658 build/C/man3/scanf.3:663 build/C/man7/symlink.7:290 build/C/man7/symlink.7:300 build/C/man7/symlink.7:330 build/C/man7/symlink.7:390 build/C/man7/symlink.7:419 build/C/man7/symlink.7:448 build/C/man7/symlink.7:479 build/C/man7/symlink.7:492
2471 #: build/C/man3/fopencookie.3:54
2473 "Implement four \"hook\" functions that are used internally by the standard "
2474 "I/O library when performing I/O on the stream."
2478 #: build/C/man3/fopencookie.3:65
2480 "Define a \"cookie\" data type, a structure that provides bookkeeping "
2481 "information (e.g., where to store data) used by the aforementioned hook "
2482 "functions. The standard I/O package knows nothing about the contents of "
2483 "this cookie (thus it is typed as I<void\\ *> when passed to "
2484 "B<fopencookie>()), but automatically supplies the cookie as the first "
2485 "argument when calling the hook functions."
2489 #: build/C/man3/fopencookie.3:70
2491 "Call B<fopencookie>() to open a new stream and associate the cookie and "
2492 "hook functions with that stream."
2496 #: build/C/man3/fopencookie.3:78
2498 "The B<fopencookie>() function serves a purpose similar to B<fopen>(3): it "
2499 "opens a new stream and returns a pointer to a I<FILE> object that is used to "
2500 "operate on that stream."
2504 #: build/C/man3/fopencookie.3:85
2506 "The I<cookie> argument is a pointer to the caller's cookie structure that is "
2507 "to be associated with the new stream. This pointer is supplied as the first "
2508 "argument when the standard I/O library invokes any of the hook functions "
2513 #: build/C/man3/fopencookie.3:101
2515 "The I<mode> argument serves the same purpose as for B<fopen>(3). The "
2516 "following modes are supported: I<r>, I<w>, I<a>, I<r+>, I<w+>, and I<a+>. "
2517 "See B<fopen>(3) for details."
2521 #: build/C/man3/fopencookie.3:107
2523 "The I<io_funcs> argument is a structure that contains four fields pointing "
2524 "to the programmer-defined hook functions that are used to implement this "
2525 "stream. The structure is defined as follows"
2529 #: build/C/man3/fopencookie.3:116
2532 "typedef struct {\n"
2533 " cookie_read_function_t *read;\n"
2534 " cookie_write_function_t *write;\n"
2535 " cookie_seek_function_t *seek;\n"
2536 " cookie_close_function_t *close;\n"
2537 "} cookie_io_functions_t;\n"
2541 #: build/C/man3/fopencookie.3:120
2542 msgid "The four fields are as follows:"
2546 #: build/C/man3/fopencookie.3:120
2548 msgid "I<cookie_read_function_t *read>"
2552 #: build/C/man3/fopencookie.3:124
2554 "This function implements read operations for the stream. When called, it "
2555 "receives three arguments:"
2559 #: build/C/man3/fopencookie.3:126
2561 msgid " ssize_t read(void *cookie, char *buf, size_t size);\n"
2565 #: build/C/man3/fopencookie.3:141
2567 "The I<buf> and I<size> arguments are, respectively, a buffer into which "
2568 "input data can be placed and the size of that buffer. As its function "
2569 "result, the I<read> function should return the number of bytes copied into "
2570 "I<buf>, 0 on end of file, or -1 on error. The I<read> function should "
2571 "update the stream offset appropriately."
2575 #: build/C/man3/fopencookie.3:146
2577 "If I<*read> is a null pointer, then reads from the custom stream always "
2578 "return end of file."
2582 #: build/C/man3/fopencookie.3:146
2584 msgid "I<cookie_write_function_t *write>"
2588 #: build/C/man3/fopencookie.3:150
2590 "This function implements write operations for the stream. When called, it "
2591 "receives three arguments:"
2595 #: build/C/man3/fopencookie.3:152
2597 msgid " ssize_t write(void *cookie, const char *buf, size_t size);\n"
2601 #: build/C/man3/fopencookie.3:168
2603 "The I<buf> and I<size> arguments are, respectively, a buffer of data to be "
2604 "output to the stream and the size of that buffer. As its function result, "
2605 "the I<write> function should return the number of bytes copied from I<buf>, "
2606 "or 0 on error. (The function must not return a negative value.) The "
2607 "I<write> function should update the stream offset appropriately."
2611 #: build/C/man3/fopencookie.3:173
2612 msgid "If I<*write> is a null pointer, then output to the stream is discarded."
2616 #: build/C/man3/fopencookie.3:173
2618 msgid "I<cookie_seek_function_t *seek>"
2622 #: build/C/man3/fopencookie.3:177
2624 "This function implements seek operations on the stream. When called, it "
2625 "receives three arguments:"
2629 #: build/C/man3/fopencookie.3:179
2631 msgid " int seek(void *cookie, off64_t *offset, int whence);\n"
2635 #: build/C/man3/fopencookie.3:185
2637 "The I<*offset> argument specifies the new file offset depending on which of "
2638 "the following three values is supplied in I<whence>:"
2642 #: build/C/man3/fopencookie.3:186 build/C/man2/lseek.2:67
2648 #: build/C/man3/fopencookie.3:191
2650 "The stream offset should be set I<*offset> bytes from the start of the "
2655 #: build/C/man3/fopencookie.3:191 build/C/man2/lseek.2:72
2661 #: build/C/man3/fopencookie.3:195
2662 msgid "I<*offset> should be added to the current stream offset."
2666 #: build/C/man3/fopencookie.3:195 build/C/man2/lseek.2:77
2672 #: build/C/man3/fopencookie.3:199
2673 msgid "The stream offset should be set to the size of the stream plus I<*offset>."
2677 #: build/C/man3/fopencookie.3:206
2679 "Before returning, the I<seek> function should update I<*offset> to indicate "
2680 "the new stream offset."
2684 #: build/C/man3/fopencookie.3:210
2686 "As its function result, the I<seek> function should return 0 on success, and "
2691 #: build/C/man3/fopencookie.3:215
2693 "If I<*seek> is a null pointer, then it is not possible to perform seek "
2694 "operations on the stream."
2698 #: build/C/man3/fopencookie.3:215
2700 msgid "I<cookie_close_function_t *close>"
2704 #: build/C/man3/fopencookie.3:221
2706 "This function closes the stream. The hook function can do things such as "
2707 "freeing buffers allocated for the stream. When called, it receives one "
2712 #: build/C/man3/fopencookie.3:223
2714 msgid " int close(void *cookie);\n"
2718 #: build/C/man3/fopencookie.3:228
2720 "The I<cookie> argument is the cookie that the programmer supplied when "
2721 "calling B<fopencookie>()."
2725 #: build/C/man3/fopencookie.3:234
2727 "As its function result, the I<close> function should return 0 on success, "
2728 "and B<EOF> on error."
2732 #: build/C/man3/fopencookie.3:238
2734 "If I<*close> is NULL, then no special action is performed when the stream is "
2739 #. It's not clear if errno ever gets set...
2741 #: build/C/man3/fopencookie.3:245
2743 "On success B<fopencookie>() returns a pointer to the new stream. On error, "
2748 #: build/C/man3/fopencookie.3:247
2749 msgid "This function is a nonstandard GNU extension."
2753 #: build/C/man3/fopencookie.3:256
2755 "The program below implements a custom stream whose functionality is similar "
2756 "(but not identical) to that available via B<fmemopen>(3). It implements a "
2757 "stream whose data is stored in a memory buffer. The program writes its "
2758 "command-line arguments to the stream, and then seeks through the stream "
2759 "reading two out of every five characters and writing them to standard "
2760 "output. The following shell session demonstrates the use of the program:"
2764 #: build/C/man3/fopencookie.3:264
2767 "$B< ./a.out \\(aqhello world\\(aq>\n"
2771 "Reached end of file\n"
2775 #: build/C/man3/fopencookie.3:271
2777 "Note that a more general version of the program below could be improved to "
2778 "more robustly handle various error situations (e.g., opening a stream with a "
2779 "cookie that already has an open stream; closing a stream that has already "
2784 #: build/C/man3/fopencookie.3:280
2787 "#define _GNU_SOURCE\n"
2788 "#include E<lt>sys/types.hE<gt>\n"
2789 "#include E<lt>stdio.hE<gt>\n"
2790 "#include E<lt>stdlib.hE<gt>\n"
2791 "#include E<lt>unistd.hE<gt>\n"
2792 "#include E<lt>string.hE<gt>\n"
2796 #: build/C/man3/fopencookie.3:282
2798 msgid "#define INIT_BUF_SIZE 4\n"
2802 #: build/C/man3/fopencookie.3:289
2805 "struct memfile_cookie {\n"
2806 " char *buf; /* Dynamically sized buffer for data */\n"
2807 " size_t allocated; /* Size of buf */\n"
2808 " size_t endpos; /* Number of characters in buf */\n"
2809 " off_t offset; /* Current file offset in buf */\n"
2814 #: build/C/man3/fopencookie.3:295
2818 "memfile_write(void *c, const char *buf, size_t size)\n"
2820 " char *new_buff;\n"
2821 " struct memfile_cookie *cookie = c;\n"
2825 #: build/C/man3/fopencookie.3:297
2827 msgid " /* Buffer too small? Keep doubling size until big enough */\n"
2831 #: build/C/man3/fopencookie.3:307
2834 " while (size + cookie-E<gt>offset E<gt> cookie-E<gt>allocated) {\n"
2835 " new_buff = realloc(cookie-E<gt>buf, cookie-E<gt>allocated * 2);\n"
2836 " if (new_buff == NULL) {\n"
2839 " cookie-E<gt>allocated *= 2;\n"
2840 " cookie-E<gt>buf = new_buff;\n"
2846 #: build/C/man3/fopencookie.3:309
2848 msgid " memcpy(cookie-E<gt>buf + cookie-E<gt>offset, buf, size);\n"
2852 #: build/C/man3/fopencookie.3:313
2855 " cookie-E<gt>offset += size;\n"
2856 " if (cookie-E<gt>offset E<gt> cookie-E<gt>endpos)\n"
2857 " cookie-E<gt>endpos = cookie-E<gt>offset;\n"
2861 #: build/C/man3/fopencookie.3:316
2869 #: build/C/man3/fopencookie.3:322
2873 "memfile_read(void *c, char *buf, size_t size)\n"
2875 " ssize_t xbytes;\n"
2876 " struct memfile_cookie *cookie = c;\n"
2880 #: build/C/man3/fopencookie.3:324
2882 msgid " /* Fetch minimum of bytes requested and bytes available */\n"
2886 #: build/C/man3/fopencookie.3:330
2890 " if (cookie-E<gt>offset + size E<gt> cookie-E<gt>endpos)\n"
2891 " xbytes = cookie-E<gt>endpos - cookie-E<gt>offset;\n"
2892 " if (xbytes E<lt> 0) /* offset may be past endpos */\n"
2897 #: build/C/man3/fopencookie.3:332
2899 msgid " memcpy(buf, cookie-E<gt>buf + cookie-E<gt>offset, xbytes);\n"
2903 #: build/C/man3/fopencookie.3:336
2906 " cookie-E<gt>offset += xbytes;\n"
2912 #: build/C/man3/fopencookie.3:342
2916 "memfile_seek(void *c, off64_t *offset, int whence)\n"
2918 " off64_t new_offset;\n"
2919 " struct memfile_cookie *cookie = c;\n"
2923 #: build/C/man3/fopencookie.3:351
2926 " if (whence == SEEK_SET)\n"
2927 " new_offset = *offset;\n"
2928 " else if (whence == SEEK_END)\n"
2929 " new_offset = cookie-E<gt>endpos + *offset;\n"
2930 " else if (whence == SEEK_CUR)\n"
2931 " new_offset = cookie-E<gt>offset + *offset;\n"
2937 #: build/C/man3/fopencookie.3:354
2940 " if (new_offset E<lt> 0)\n"
2945 #: build/C/man3/fopencookie.3:359
2948 " cookie-E<gt>offset = new_offset;\n"
2949 " *offset = new_offset;\n"
2955 #: build/C/man3/fopencookie.3:364
2959 "memfile_close(void *c)\n"
2961 " struct memfile_cookie *cookie = c;\n"
2965 #: build/C/man3/fopencookie.3:368
2968 " free(cookie-E<gt>buf);\n"
2969 " cookie-E<gt>allocated = 0;\n"
2970 " cookie-E<gt>buf = NULL;\n"
2974 #: build/C/man3/fopencookie.3:371
2982 #: build/C/man3/fopencookie.3:387
2986 "main(int argc, char *argv[])\n"
2988 " cookie_io_functions_t memfile_func = {\n"
2989 " .read = memfile_read,\n"
2990 " .write = memfile_write,\n"
2991 " .seek = memfile_seek,\n"
2992 " .close = memfile_close\n"
2995 " struct memfile_cookie mycookie;\n"
2999 " char buf[1000];\n"
3003 #: build/C/man3/fopencookie.3:389
3005 msgid " /* Set up the cookie before calling fopencookie() */\n"
3009 #: build/C/man3/fopencookie.3:395
3012 " mycookie.buf = malloc(INIT_BUF_SIZE);\n"
3013 " if (mycookie.buf == NULL) {\n"
3014 " perror(\"malloc\");\n"
3015 " exit(EXIT_FAILURE);\n"
3020 #: build/C/man3/fopencookie.3:399
3023 " mycookie.allocated = INIT_BUF_SIZE;\n"
3024 " mycookie.offset = 0;\n"
3025 " mycookie.endpos = 0;\n"
3029 #: build/C/man3/fopencookie.3:405
3032 " stream = fopencookie(&mycookie,\"w+\", memfile_func);\n"
3033 " if (stream == NULL) {\n"
3034 " perror(\"fopencookie\");\n"
3035 " exit(EXIT_FAILURE);\n"
3040 #: build/C/man3/fopencookie.3:407
3042 msgid " /* Write command-line arguments to our file */\n"
3046 #: build/C/man3/fopencookie.3:413
3049 " for (j = 1; j E<lt> argc; j++)\n"
3050 " if (fputs(argv[j], stream) == EOF) {\n"
3051 " perror(\"fputs\");\n"
3052 " exit(EXIT_FAILURE);\n"
3057 #: build/C/man3/fopencookie.3:415
3059 msgid " /* Read two bytes out of every five, until EOF */\n"
3063 #: build/C/man3/fopencookie.3:430
3066 " for (p = 0; ; p += 5) {\n"
3067 " if (fseek(stream, p, SEEK_SET) == -1) {\n"
3068 " perror(\"fseek\");\n"
3069 " exit(EXIT_FAILURE);\n"
3071 " nread = fread(buf, 1, 2, stream);\n"
3072 " if (nread == -1) {\n"
3073 " perror(\"fread\");\n"
3074 " exit(EXIT_FAILURE);\n"
3076 " if (nread == 0) {\n"
3077 " printf(\"Reached end of file\\en\");\n"
3083 #: build/C/man3/fopencookie.3:433
3086 " printf(\"/%.*s/\\en\", nread, buf);\n"
3091 #: build/C/man3/fopencookie.3:436 build/C/man2/open_by_handle_at.2:579 build/C/man2/open_by_handle_at.2:719 build/C/man2/readlink.2:327
3094 " exit(EXIT_SUCCESS);\n"
3099 #: build/C/man3/fopencookie.3:442
3100 msgid "B<fclose>(3), B<fmemopen>(3), B<fopen>(3), B<fseek>(3)"
3104 #: build/C/man3/fpurge.3:25
3110 #: build/C/man3/fpurge.3:25
3116 #: build/C/man3/fpurge.3:28
3117 msgid "fpurge, __fpurge - purge a stream"
3121 #: build/C/man3/fpurge.3:32
3124 "/* unsupported */\n"
3125 "B<#include E<lt>stdio.hE<gt>>\n"
3129 #: build/C/man3/fpurge.3:34
3131 msgid "B<int fpurge(FILE *>I<stream>B<);>\n"
3135 #: build/C/man3/fpurge.3:37
3139 "B<#include E<lt>stdio.hE<gt>>\n"
3143 #: build/C/man3/fpurge.3:39
3145 msgid "B<#include E<lt>stdio_ext.hE<gt>>\n"
3149 #: build/C/man3/fpurge.3:41
3151 msgid "B<void __fpurge(FILE *>I<stream>B<);>\n"
3155 #: build/C/man3/fpurge.3:54
3157 "The function B<fpurge>() clears the buffers of the given stream. For "
3158 "output streams this discards any unwritten output. For input streams this "
3159 "discards any input read from the underlying object but not yet obtained via "
3160 "B<getc>(3); this includes any text pushed back via B<ungetc>(3). See also "
3165 #: build/C/man3/fpurge.3:58
3167 "The function B<__fpurge>() does precisely the same, but without returning a "
3172 #: build/C/man3/fpurge.3:65
3174 "Upon successful completion B<fpurge>() returns 0. On error, it returns -1 "
3175 "and sets I<errno> appropriately."
3179 #: build/C/man3/fpurge.3:70
3180 msgid "I<stream> is not an open stream."
3184 #: build/C/man3/fpurge.3:78
3186 "These functions are nonstandard and not portable. The function B<fpurge>() "
3187 "was introduced in 4.4BSD and is not available under Linux. The function "
3188 "B<__fpurge>() was introduced in Solaris, and is present in glibc 2.1.95 and "
3193 #: build/C/man3/fpurge.3:80
3194 msgid "Usually it is a mistake to want to discard input buffers."
3199 #: build/C/man3/fpurge.3:85
3200 msgid "B<fflush>(3), B<setbuf>(3), B<stdio_ext>(3)"
3204 #: build/C/man3/fputwc.3:16
3210 #: build/C/man3/fputwc.3:19
3211 msgid "fputwc, putwc - write a wide character to a FILE stream"
3215 #: build/C/man3/fputwc.3:27
3218 "B<wint_t fputwc(wchar_t >I<wc>B<, FILE *>I<stream>B<);>\n"
3219 "B<wint_t putwc(wchar_t >I<wc>B<, FILE *>I<stream>B<);>\n"
3223 #: build/C/man3/fputwc.3:43
3225 "The B<fputwc>() function is the wide-character equivalent of the "
3226 "B<fputc>(3) function. It writes the wide character I<wc> to I<stream>. If "
3227 "I<ferror(stream)> becomes true, it returns B<WEOF>. If a wide-character "
3228 "conversion error occurs, it sets I<errno> to B<EILSEQ> and returns B<WEOF>. "
3229 "Otherwise, it returns I<wc>."
3233 #: build/C/man3/fputwc.3:51
3235 "The B<putwc>() function or macro functions identically to B<fputwc>(). It "
3236 "may be implemented as a macro, and may evaluate its argument more than "
3237 "once. There is no reason ever to use it."
3241 #: build/C/man3/fputwc.3:63
3243 "The B<fputwc>() function returns I<wc> if no error occurred, or B<WEOF> to "
3244 "indicate an error. In the event of an error, I<errno> is set to indicate "
3249 #: build/C/man3/fputwc.3:68
3250 msgid "Conversion of I<wc> to the stream's encoding fails."
3254 #: build/C/man3/fputwc.3:77
3256 "The behavior of B<fputwc>() depends on the B<LC_CTYPE> category of the "
3261 #: build/C/man3/fputwc.3:85
3263 "In the absence of additional information passed to the B<fopen>(3) call, it "
3264 "is reasonable to expect that B<fputwc>() will actually write the multibyte "
3265 "sequence corresponding to the wide character I<wc>."
3269 #: build/C/man3/fputwc.3:89
3270 msgid "B<fgetwc>(3), B<fputws>(3), B<unlocked_stdio>(3)"
3274 #: build/C/man3/fread.3:45
3280 #: build/C/man3/fread.3:45
3286 #: build/C/man3/fread.3:48
3287 msgid "fread, fwrite - binary stream input/output"
3291 #: build/C/man3/fread.3:54
3294 "B<size_t fread(void *>I<ptr>B<, size_t >I<size>B<, size_t >I<nmemb>B<, FILE "
3295 "*>I<stream>B<);>\n"
3299 #: build/C/man3/fread.3:57
3302 "B<size_t fwrite(const void *>I<ptr>B<, size_t >I<size>B<, size_t "
3304 "B< FILE *>I<stream>B<);>\n"
3308 #: build/C/man3/fread.3:69
3310 "The function B<fread>() reads I<nmemb> elements of data, each I<size> bytes "
3311 "long, from the stream pointed to by I<stream>, storing them at the location "
3316 #: build/C/man3/fread.3:80
3318 "The function B<fwrite>() writes I<nmemb> elements of data, each I<size> "
3319 "bytes long, to the stream pointed to by I<stream>, obtaining them from the "
3320 "location given by I<ptr>."
3324 #: build/C/man3/fread.3:96
3326 "On success, B<fread>() and B<fwrite>() return the number of I<items> read "
3327 "or written. This number equals the number of bytes transferred only when "
3328 "I<size> is 1. If an error occurs, or the end of the file is reached, the "
3329 "return value is a short item count (or zero)."
3333 #: build/C/man3/fread.3:103
3335 "B<fread>() does not distinguish between end-of-file and error, and callers "
3336 "must use B<feof>(3) and B<ferror>(3) to determine which occurred."
3340 #: build/C/man3/fread.3:105
3341 msgid "C89, POSIX.1-2001."
3345 #: build/C/man3/fread.3:111
3346 msgid "B<read>(2), B<write>(2), B<feof>(3), B<ferror>(3), B<unlocked_stdio>(3)"
3350 #: build/C/man3/fseek.3:42
3356 #: build/C/man3/fseek.3:42 build/C/man3/perror.3:31
3362 #: build/C/man3/fseek.3:45
3363 msgid "fgetpos, fseek, fsetpos, ftell, rewind - reposition a stream"
3367 #: build/C/man3/fseek.3:49
3368 msgid "B<int fseek(FILE *>I<stream>B<, long >I<offset>B<, int >I<whence>B<);>"
3372 #: build/C/man3/fseek.3:51
3373 msgid "B<long ftell(FILE *>I<stream>B<);>"
3377 #: build/C/man3/fseek.3:53
3378 msgid "B<void rewind(FILE *>I<stream>B<);>"
3382 #: build/C/man3/fseek.3:55
3383 msgid "B<int fgetpos(FILE *>I<stream>B<, fpos_t *>I<pos>B<);>"
3387 #: build/C/man3/fseek.3:57
3388 msgid "B<int fsetpos(FILE *>I<stream>B<, const fpos_t *>I<pos>B<);>"
3392 #: build/C/man3/fseek.3:81
3394 "The B<fseek>() function sets the file position indicator for the stream "
3395 "pointed to by I<stream>. The new position, measured in bytes, is obtained "
3396 "by adding I<offset> bytes to the position specified by I<whence>. If "
3397 "I<whence> is set to B<SEEK_SET>, B<SEEK_CUR>, or B<SEEK_END>, the offset is "
3398 "relative to the start of the file, the current position indicator, or "
3399 "end-of-file, respectively. A successful call to the B<fseek>() function "
3400 "clears the end-of-file indicator for the stream and undoes any effects of "
3401 "the B<ungetc>(3) function on the same stream."
3405 #: build/C/man3/fseek.3:87
3407 "The B<ftell>() function obtains the current value of the file position "
3408 "indicator for the stream pointed to by I<stream>."
3412 #: build/C/man3/fseek.3:94
3414 "The B<rewind>() function sets the file position indicator for the stream "
3415 "pointed to by I<stream> to the beginning of the file. It is equivalent to:"
3419 #: build/C/man3/fseek.3:97
3420 msgid "(void) fseek(stream, 0L, SEEK_SET)"
3424 #: build/C/man3/fseek.3:101
3426 "except that the error indicator for the stream is also cleared (see "
3431 #: build/C/man3/fseek.3:121
3433 "The B<fgetpos>() and B<fsetpos>() functions are alternate interfaces "
3434 "equivalent to B<ftell>() and B<fseek>() (with I<whence> set to "
3435 "B<SEEK_SET>), setting and storing the current value of the file offset into "
3436 "or from the object referenced by I<pos>. On some non-UNIX systems, an "
3437 "I<fpos_t> object may be a complex object and these routines may be the only "
3438 "way to portably reposition a text stream."
3442 #: build/C/man3/fseek.3:136
3444 "The B<rewind>() function returns no value. Upon successful completion, "
3445 "B<fgetpos>(), B<fseek>(), B<fsetpos>() return 0, and B<ftell>() returns "
3446 "the current offset. Otherwise, -1 is returned and I<errno> is set to "
3447 "indicate the error."
3451 #: build/C/man3/fseek.3:142
3452 msgid "The I<stream> specified is not a seekable stream."
3456 #: build/C/man3/fseek.3:154
3458 "The I<whence> argument to B<fseek>() was not B<SEEK_SET>, B<SEEK_END>, or "
3459 "B<SEEK_CUR>. Or: the resulting file offset would be negative."
3463 #: build/C/man3/fseek.3:169
3465 "The functions B<fgetpos>(), B<fseek>(), B<fsetpos>(), and B<ftell>() may "
3466 "also fail and set I<errno> for any of the errors specified for the routines "
3467 "B<fflush>(3), B<fstat>(2), B<lseek>(2), and B<malloc>(3)."
3471 #: build/C/man3/fseek.3:174
3472 msgid "B<lseek>(2), B<fseeko>(3)"
3476 #: build/C/man3/fseeko.3:25
3482 #: build/C/man3/fseeko.3:25
3488 #: build/C/man3/fseeko.3:28
3489 msgid "fseeko, ftello - seek to or report file position"
3493 #: build/C/man3/fseeko.3:33
3495 msgid "B<int fseeko(FILE *>I<stream>B<, off_t >I<offset>B<, int >I<whence>B<);>\n"
3499 #: build/C/man3/fseeko.3:36
3502 "B<off_t ftello(FILE *>I<stream>B<);>\n"
3507 #: build/C/man3/fseeko.3:45
3508 msgid "B<fseeko>(), B<ftello>():"
3512 #: build/C/man3/fseeko.3:50
3514 "_FILE_OFFSET_BITS\\ ==\\ 64 || _POSIX_C_SOURCE\\ E<gt>=\\ 200112L || "
3515 "_XOPEN_SOURCE\\ E<gt>=\\ 600"
3519 #: build/C/man3/fseeko.3:52
3520 msgid "(defining the obsolete _LARGEFILE_SOURCE macro also works)"
3524 #: build/C/man3/fseeko.3:75
3526 "The B<fseeko>() and B<ftello>() functions are identical to B<fseek>(3) "
3527 "and B<ftell>(3) (see B<fseek>(3)), respectively, except that the I<offset> "
3528 "argument of B<fseeko>() and the return value of B<ftello>() is of type "
3529 "I<off_t> instead of I<long>."
3533 #: build/C/man3/fseeko.3:88
3535 "On some architectures, both I<off_t> and I<long> are 32-bit types, but "
3536 "defining B<_FILE_OFFSET_BITS> with the value 64 (before including I<any> "
3537 "header files) will turn I<off_t> into a 64-bit type."
3541 #: build/C/man3/fseeko.3:97
3543 "On successful completion, B<fseeko>() returns 0, while B<ftello>() returns "
3544 "the current offset. Otherwise, -1 is returned and I<errno> is set to "
3545 "indicate the error."
3549 #: build/C/man3/fseeko.3:100
3550 msgid "See the ERRORS in B<fseek>(3)."
3554 #: build/C/man3/fseeko.3:102
3555 msgid "These functions are available under glibc since version 2.1."
3559 #: build/C/man3/fseeko.3:104
3560 msgid "SUSv2, POSIX.1-2001."
3564 #: build/C/man3/fseeko.3:106
3565 msgid "These functions are found on System V-like systems."
3569 #: build/C/man3/fseeko.3:108
3574 #: build/C/man3/getline.3:26
3580 #: build/C/man3/getline.3:29
3581 msgid "getline, getdelim - delimited string input"
3585 #: build/C/man3/getline.3:34
3588 "B<ssize_t getline(char **>I<lineptr>B<, size_t *>I<n>B<, FILE "
3589 "*>I<stream>B<);>\n"
3593 #: build/C/man3/getline.3:37
3596 "B<ssize_t getdelim(char **>I<lineptr>B<, size_t *>I<n>B<, int >I<delim>B<, "
3597 "FILE *>I<stream>B<);>\n"
3601 #: build/C/man3/getline.3:47
3602 msgid "B<getline>(), B<getdelim>():"
3606 #: build/C/man3/getline.3:52
3607 msgid "_POSIX_C_SOURCE\\ E<gt>=\\ 200809L || _XOPEN_SOURCE\\ E<gt>=\\ 700"
3611 #: build/C/man3/getline.3:65
3613 "B<getline>() reads an entire line from I<stream>, storing the address of "
3614 "the buffer containing the text into I<*lineptr>. The buffer is "
3615 "null-terminated and includes the newline character, if one was found."
3619 #: build/C/man3/getline.3:77
3621 "If I<*lineptr> is set to NULL and I<*n> is set 0 before the call, then "
3622 "B<getline>() will allocate a buffer for storing the line. This buffer "
3623 "should be freed by the user program even if B<getline>() failed."
3627 #: build/C/man3/getline.3:95
3629 "Alternatively, before calling B<getline>(), I<*lineptr> can contain a "
3630 "pointer to a B<malloc>(3)-allocated buffer I<*n> bytes in size. If the "
3631 "buffer is not large enough to hold the line, B<getline>() resizes it with "
3632 "B<realloc>(3), updating I<*lineptr> and I<*n> as necessary."
3636 #: build/C/man3/getline.3:101
3638 "In either case, on a successful call, I<*lineptr> and I<*n> will be updated "
3639 "to reflect the buffer address and allocated size respectively."
3643 #: build/C/man3/getline.3:112
3645 "B<getdelim>() works like B<getline>(), except that a line delimiter other "
3646 "than newline can be specified as the I<delimiter> argument. As with "
3647 "B<getline>(), a delimiter character is not added if one was not present in "
3648 "the input before end of file was reached."
3652 #: build/C/man3/getline.3:121
3654 "On success, B<getline>() and B<getdelim>() return the number of characters "
3655 "read, including the delimiter character, but not including the terminating "
3656 "null byte (\\(aq\\e0\\(aq). This value can be used to handle embedded null "
3657 "bytes in the line read."
3661 #: build/C/man3/getline.3:127
3663 "Both functions return -1 on failure to read a line (including end-of-file "
3664 "condition). In the event of an error, I<errno> is set to indicate the "
3669 #: build/C/man3/getline.3:137
3670 msgid "Bad arguments (I<n> or I<lineptr> is NULL, or I<stream> is not valid)."
3674 #: build/C/man3/getline.3:144
3676 "Both B<getline>() and B<getdelim>() were originally GNU extensions. They "
3677 "were standardized in POSIX.1-2008."
3681 #: build/C/man3/getline.3:149
3684 "#define _GNU_SOURCE\n"
3685 "#include E<lt>stdio.hE<gt>\n"
3686 "#include E<lt>stdlib.hE<gt>\n"
3690 #: build/C/man3/getline.3:157
3697 " char *line = NULL;\n"
3698 " size_t len = 0;\n"
3703 #: build/C/man3/getline.3:161
3706 " stream = fopen(\"/etc/motd\", \"r\");\n"
3707 " if (stream == NULL)\n"
3708 " exit(EXIT_FAILURE);\n"
3712 #: build/C/man3/getline.3:166
3715 " while ((read = getline(&line, &len, stream)) != -1) {\n"
3716 " printf(\"Retrieved line of length %zu :\\en\", read);\n"
3717 " printf(\"%s\", line);\n"
3722 #: build/C/man3/getline.3:171
3726 " fclose(stream);\n"
3727 " exit(EXIT_SUCCESS);\n"
3732 #: build/C/man3/getline.3:178
3733 msgid "B<read>(2), B<fgets>(3), B<fopen>(3), B<fread>(3), B<scanf>(3)"
3737 #: build/C/man3/gets.3:29
3743 #: build/C/man3/gets.3:29
3749 #: build/C/man3/gets.3:32
3750 msgid "gets - get a string from standard input (DEPRECATED)"
3754 #: build/C/man3/gets.3:37
3756 msgid "B<char *gets(char *>I<s>B<);>\n"
3760 #: build/C/man3/gets.3:40
3761 msgid "I<Never use this function>."
3765 #: build/C/man3/gets.3:50
3767 "B<gets>() reads a line from I<stdin> into the buffer pointed to by I<s> "
3768 "until either a terminating newline or B<EOF>, which it replaces with a null "
3769 "byte (\\(aq\\e0\\(aq). No check for buffer overrun is performed (see BUGS "
3774 #: build/C/man3/gets.3:58
3776 "B<gets>() returns I<s> on success, and NULL on error or when end of file "
3777 "occurs while no characters have been read. However, given the lack of "
3778 "buffer overrun checking, there can be no guarantees that the function will "
3783 #: build/C/man3/gets.3:72
3785 "LSB deprecates B<gets>(). POSIX.1-2008 marks B<gets>() obsolescent. ISO "
3786 "C11 removes the specification of B<gets>() from the C language, and since "
3787 "version 2.16, glibc header files don't expose the function declaration if "
3788 "the B<_ISOC11_SOURCE> feature test macro is defined."
3792 #: build/C/man3/gets.3:86
3794 "Never use B<gets>(). Because it is impossible to tell without knowing the "
3795 "data in advance how many characters B<gets>() will read, and because "
3796 "B<gets>() will continue to store characters past the end of the buffer, it "
3797 "is extremely dangerous to use. It has been used to break computer "
3798 "security. Use B<fgets>() instead."
3802 #: build/C/man3/gets.3:90
3804 "For more information, see CWE-242 (aka \"Use of Inherently Dangerous "
3805 "Function\") at http://cwe.mitre.org/data/definitions/242.html"
3809 #: build/C/man3/gets.3:108
3811 "B<read>(2), B<write>(2), B<ferror>(3), B<fgetc>(3), B<fgets>(3), "
3812 "B<fgetwc>(3), B<fgetws>(3), B<fopen>(3), B<fread>(3), B<fseek>(3), "
3813 "B<getline>(3), B<getwchar>(3), B<puts>(3), B<scanf>(3), B<ungetwc>(3), "
3814 "B<unlocked_stdio>(3), B<feature_test_macros>(7)"
3818 #: build/C/man3/getw.3:25
3824 #: build/C/man3/getw.3:25
3830 #: build/C/man3/getw.3:28
3831 msgid "getw, putw - input and output of words (ints)"
3835 #: build/C/man3/getw.3:33
3837 msgid "B<int getw(FILE *>I<stream>B<);>\n"
3841 #: build/C/man3/getw.3:35
3843 msgid "B<int putw(int >I<w>B<, FILE *>I<stream>B<);>\n"
3847 #: build/C/man3/getw.3:44
3848 msgid "B<getw>(), B<putw>():"
3852 #: build/C/man3/getw.3:47
3854 msgid "Since glibc 2.3.3:"
3858 #: build/C/man3/getw.3:50
3859 msgid "_SVID_SOURCE || _BSD_SOURCE ||"
3863 #: build/C/man3/getw.3:53
3866 "(_XOPEN_SOURCE &&\n"
3867 " !(_POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ E<gt>=\\ 600))\n"
3871 #: build/C/man3/getw.3:53
3873 msgid "Before glibc 2.3.3:"
3877 #: build/C/man3/getw.3:56
3878 msgid "_SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE"
3882 #: build/C/man3/getw.3:66
3884 "B<getw>() reads a word (that is, an I<int>) from I<stream>. It's provided "
3885 "for compatibility with SVr4. We recommend you use B<fread>(3) instead."
3889 #: build/C/man3/getw.3:73
3891 "B<putw>() writes the word I<w> (that is, an I<int>) to I<stream>. It is "
3892 "provided for compatibility with SVr4, but we recommend you use B<fwrite>(3) "
3897 #: build/C/man3/getw.3:80
3899 "Normally, B<getw>() returns the word read, and B<putw>() returns 0. On "
3900 "error, they return B<EOF>."
3904 #: build/C/man3/getw.3:83
3905 msgid "SVr4, SUSv2. Not present in POSIX.1-2001."
3909 #: build/C/man3/getw.3:87
3911 "The value returned on error is also a legitimate data value. B<ferror>(3) "
3912 "can be used to distinguish between the two cases."
3916 #: build/C/man3/getw.3:93
3917 msgid "B<ferror>(3), B<fread>(3), B<fwrite>(3), B<getc>(3), B<putc>(3)"
3921 #: build/C/man2/link.2:32
3927 #: build/C/man2/link.2:35
3928 msgid "link, linkat - make a new name for a file"
3932 #: build/C/man2/link.2:38 build/C/man2/pipe.2:42 build/C/man2/read.2:41 build/C/man2/readlink.2:50 build/C/man2/symlink.2:39 build/C/man2/unlink.2:39
3934 msgid "B<#include E<lt>unistd.hE<gt>>\n"
3938 #: build/C/man2/link.2:40
3940 msgid "B<int link(const char *>I<oldpath>B<, const char *>I<newpath>B<);>\n"
3944 #: build/C/man2/link.2:43 build/C/man2/readlink.2:56 build/C/man2/symlink.2:44 build/C/man2/unlink.2:44
3947 "B<#include E<lt>fcntl.hE<gt> >/* Definition of AT_* constants */\n"
3948 "B<#include E<lt>unistd.hE<gt>>\n"
3952 #: build/C/man2/link.2:46
3955 "B<int linkat(int >I<olddirfd>B<, const char *>I<oldpath>B<,>\n"
3956 "B< int >I<newdirfd>B<, const char *>I<newpath>B<, int "
3961 #: build/C/man2/link.2:54
3962 msgid "B<linkat>():"
3966 #: build/C/man2/link.2:63 build/C/man2/open.2:85 build/C/man2/readlink.2:83 build/C/man2/rename.2:69 build/C/man2/symlink.2:71 build/C/man2/unlink.2:63
3967 msgid "_ATFILE_SOURCE"
3971 #: build/C/man2/link.2:69
3973 "B<link>() creates a new link (also known as a hard link) to an existing "
3978 #: build/C/man2/link.2:75
3979 msgid "If I<newpath> exists, it will I<not> be overwritten."
3983 #: build/C/man2/link.2:80
3985 "This new name may be used exactly as the old one for any operation; both "
3986 "names refer to the same file (and so have the same permissions and "
3987 "ownership) and it is impossible to tell which name was the \"original\"."
3991 #: build/C/man2/link.2:80
3997 #: build/C/man2/link.2:86
3999 "The B<linkat>() system call operates in exactly the same way as B<link>(), "
4000 "except for the differences described here."
4004 #: build/C/man2/link.2:96
4006 "If the pathname given in I<oldpath> is relative, then it is interpreted "
4007 "relative to the directory referred to by the file descriptor I<olddirfd> "
4008 "(rather than relative to the current working directory of the calling "
4009 "process, as is done by B<link>() for a relative pathname)."
4013 #: build/C/man2/link.2:108
4015 "If I<oldpath> is relative and I<olddirfd> is the special value B<AT_FDCWD>, "
4016 "then I<oldpath> is interpreted relative to the current working directory of "
4017 "the calling process (like B<link>())."
4021 #: build/C/man2/link.2:114 build/C/man2/rename.2:158
4022 msgid "If I<oldpath> is absolute, then I<olddirfd> is ignored."
4026 #: build/C/man2/link.2:122 build/C/man2/rename.2:166
4028 "The interpretation of I<newpath> is as for I<oldpath>, except that a "
4029 "relative pathname is interpreted relative to the directory referred to by "
4030 "the file descriptor I<newdirfd>."
4034 #: build/C/man2/link.2:125
4035 msgid "The following values can be bitwise ORed in I<flags>:"
4039 #: build/C/man2/link.2:125
4041 msgid "B<AT_EMPTY_PATH> (since Linux 2.6.39)"
4044 #. commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3
4045 #. Before glibc 2.16, defining _ATFILE_SOURCE sufficed
4047 #: build/C/man2/link.2:152
4049 "If I<oldpath> is an empty string, create a link to the file referenced by "
4050 "I<olddirfd> (which may have been obtained using the B<open>(2) B<O_PATH> "
4051 "flag). In this case, I<olddirfd> can refer to any type of file, not just a "
4052 "directory. This will generally not work if the file has a link count of "
4053 "zero (files created with B<O_TMPFILE> and without B<O_EXCL> are an "
4054 "exception). The caller must have the B<CAP_DAC_READ_SEARCH> capability in "
4055 "order to use this flag. This flag is Linux-specific; define B<_GNU_SOURCE> "
4056 "to obtain its definition."
4060 #: build/C/man2/link.2:152
4062 msgid "B<AT_SYMLINK_FOLLOW> (since Linux 2.6.18)"
4066 #: build/C/man2/link.2:171
4068 "By default, B<linkat>(), does not dereference I<oldpath> if it is a symbolic "
4069 "link (like B<link>()). The flag B<AT_SYMLINK_FOLLOW> can be specified in "
4070 "I<flags> to cause I<oldpath> to be dereferenced if it is a symbolic link. "
4071 "If procfs is mounted, this can be used as an alternative to "
4072 "B<AT_EMPTY_PATH>, like this:"
4076 #: build/C/man2/link.2:176
4079 "linkat(AT_FDCWD, \"/proc/self/fd/E<lt>fdE<gt>\", newdirfd,\n"
4080 " newname, AT_SYMLINK_FOLLOW);\n"
4084 #: build/C/man2/link.2:182
4086 "Before kernel 2.6.18, the I<flags> argument was unused, and had to be "
4091 #: build/C/man2/link.2:187
4092 msgid "See B<openat>(2) for an explanation of the need for B<linkat>()."
4096 #: build/C/man2/link.2:192 build/C/man2/pipe.2:138 build/C/man3/remove.3:65 build/C/man2/rename.2:208 build/C/man2/rmdir.2:45 build/C/man2/symlink.2:145 build/C/man2/unlink.2:158
4098 "On success, zero is returned. On error, -1 is returned, and I<errno> is set "
4103 #: build/C/man2/link.2:193 build/C/man2/open.2:789 build/C/man2/readlink.2:160 build/C/man2/rename.2:209 build/C/man2/rmdir.2:46 build/C/man2/symlink.2:146 build/C/man3/tmpfile.3:57 build/C/man2/unlink.2:159
4109 #: build/C/man2/link.2:204
4111 "Write access to the directory containing I<newpath> is denied, or search "
4112 "permission is denied for one of the directories in the path prefix of "
4113 "I<oldpath> or I<newpath>. (See also B<path_resolution>(7).)"
4117 #: build/C/man2/link.2:204 build/C/man2/open.2:798 build/C/man2/rename.2:245 build/C/man2/symlink.2:155 build/C/man2/write.2:135
4123 #: build/C/man2/link.2:207 build/C/man2/rename.2:248
4124 msgid "The user's quota of disk blocks on the filesystem has been exhausted."
4128 #: build/C/man2/link.2:207 build/C/man2/open.2:804 build/C/man2/rename.2:368 build/C/man2/symlink.2:160 build/C/man3/tmpfile.3:60
4134 #: build/C/man2/link.2:211
4135 msgid "I<newpath> already exists."
4139 #: build/C/man2/link.2:211 build/C/man2/llseek.2:74 build/C/man2/open.2:810 build/C/man2/open_by_handle_at.2:266 build/C/man2/open_by_handle_at.2:321 build/C/man2/pipe.2:139 build/C/man2/read.2:118 build/C/man2/readlink.2:165 build/C/man2/rename.2:248 build/C/man2/rmdir.2:64 build/C/man2/symlink.2:164 build/C/man2/unlink.2:178 build/C/man2/write.2:141
4145 #: build/C/man2/link.2:214 build/C/man2/rename.2:251
4146 msgid "I<oldpath> or I<newpath> points outside your accessible address space."
4150 #: build/C/man2/link.2:214 build/C/man2/read.2:147 build/C/man2/readlink.2:181 build/C/man2/symlink.2:167 build/C/man2/unlink.2:182 build/C/man2/write.2:165
4156 #: build/C/man2/link.2:217 build/C/man2/symlink.2:170 build/C/man2/unlink.2:185
4157 msgid "An I/O error occurred."
4161 #: build/C/man2/link.2:217 build/C/man2/open.2:871 build/C/man2/open.2:875 build/C/man2/open_by_handle_at.2:331 build/C/man2/readlink.2:184 build/C/man2/rename.2:261 build/C/man2/rmdir.2:73 build/C/man2/symlink.2:170 build/C/man2/unlink.2:190
4167 #: build/C/man2/link.2:221 build/C/man2/rename.2:265
4169 "Too many symbolic links were encountered in resolving I<oldpath> or "
4174 #: build/C/man2/link.2:221 build/C/man2/rename.2:265
4180 #: build/C/man2/link.2:226
4182 "The file referred to by I<oldpath> already has the maximum number of links "
4187 #: build/C/man2/link.2:226 build/C/man2/open.2:891 build/C/man2/readlink.2:187 build/C/man2/rename.2:272 build/C/man2/rmdir.2:77 build/C/man2/symlink.2:174 build/C/man2/unlink.2:194
4189 msgid "B<ENAMETOOLONG>"
4193 #: build/C/man2/link.2:229 build/C/man2/rename.2:275
4194 msgid "I<oldpath> or I<newpath> was too long."
4198 #: build/C/man2/link.2:229 build/C/man2/link.2:286 build/C/man2/link.2:294 build/C/man2/link.2:304 build/C/man2/open.2:905 build/C/man2/open.2:912 build/C/man2/open_by_handle_at.2:282 build/C/man2/readlink.2:190 build/C/man2/rename.2:275 build/C/man2/rename.2:389 build/C/man2/rmdir.2:80 build/C/man2/symlink.2:177 build/C/man2/symlink.2:212 build/C/man2/unlink.2:197
4204 #: build/C/man2/link.2:234
4206 "A directory component in I<oldpath> or I<newpath> does not exist or is a "
4207 "dangling symbolic link."
4211 #: build/C/man2/link.2:234 build/C/man2/open.2:926 build/C/man2/readlink.2:193 build/C/man2/rename.2:288 build/C/man2/rmdir.2:85 build/C/man3/scanf.3:570 build/C/man2/symlink.2:184 build/C/man3/tempnam.3:102 build/C/man2/unlink.2:204
4217 #: build/C/man2/link.2:237 build/C/man2/open.2:929 build/C/man2/readlink.2:196 build/C/man2/rename.2:291 build/C/man2/rmdir.2:88 build/C/man2/symlink.2:187 build/C/man2/unlink.2:207
4218 msgid "Insufficient kernel memory was available."
4222 #: build/C/man2/link.2:237 build/C/man2/open.2:929 build/C/man2/rename.2:291 build/C/man2/symlink.2:187 build/C/man3/tmpfile.3:72 build/C/man2/write.2:168
4228 #: build/C/man2/link.2:241 build/C/man2/rename.2:295 build/C/man2/symlink.2:191
4229 msgid "The device containing the file has no room for the new directory entry."
4233 #: build/C/man2/link.2:241 build/C/man2/link.2:315 build/C/man2/open.2:935 build/C/man2/open.2:1010 build/C/man2/open_by_handle_at.2:289 build/C/man2/readlink.2:196 build/C/man2/readlink.2:206 build/C/man2/rename.2:295 build/C/man2/rename.2:355 build/C/man2/rmdir.2:88 build/C/man2/symlink.2:191 build/C/man2/symlink.2:218 build/C/man2/unlink.2:207 build/C/man2/unlink.2:263
4239 #: build/C/man2/link.2:246
4241 "A component used as a directory in I<oldpath> or I<newpath> is not, in fact, "
4246 #: build/C/man2/link.2:246 build/C/man2/link.2:250 build/C/man2/link.2:325 build/C/man2/open.2:974 build/C/man2/open.2:982 build/C/man2/open_by_handle_at.2:338 build/C/man2/rmdir.2:107 build/C/man2/rmdir.2:118 build/C/man2/symlink.2:196 build/C/man2/unlink.2:212 build/C/man2/write.2:173
4252 #: build/C/man2/link.2:250
4253 msgid "I<oldpath> is a directory."
4257 #: build/C/man2/link.2:255
4259 "The filesystem containing I<oldpath> and I<newpath> does not support the "
4260 "creation of hard links."
4264 #: build/C/man2/link.2:255
4266 msgid "B<EPERM> (since Linux 3.6)"
4270 #: build/C/man2/link.2:262
4272 "The caller does not have permission to create a hard link to this file (see "
4273 "the description of I</proc/sys/fs/protected_hardlinks> in B<proc>(5))."
4277 #: build/C/man2/link.2:262 build/C/man2/open.2:986 build/C/man2/rename.2:333 build/C/man2/rmdir.2:123 build/C/man2/symlink.2:201 build/C/man3/tmpfile.3:75 build/C/man2/unlink.2:235
4283 #: build/C/man2/link.2:265 build/C/man2/rename.2:336
4284 msgid "The file is on a read-only filesystem."
4288 #: build/C/man2/link.2:265 build/C/man2/rename.2:336
4294 #: build/C/man2/link.2:273
4296 "I<oldpath> and I<newpath> are not on the same mounted filesystem. (Linux "
4297 "permits a filesystem to be mounted at multiple points, but B<link>() does "
4298 "not work across different mount points, even if the same filesystem is "
4303 #: build/C/man2/link.2:276
4304 msgid "The following additional errors can occur for B<linkat>():"
4308 #: build/C/man2/link.2:282 build/C/man2/rename.2:355
4309 msgid "I<olddirfd> or I<newdirfd> is not a valid file descriptor."
4313 #: build/C/man2/link.2:286 build/C/man2/unlink.2:256
4314 msgid "An invalid flag value was specified in I<flags>."
4318 #: build/C/man2/link.2:294
4320 "B<AT_EMPTY_PATH> was specified in I<flags>, but the caller did not have the "
4321 "B<CAP_DAC_READ_SEARCH> capability."
4325 #: build/C/man2/link.2:299
4327 "An attempt was made to link to the I</proc/self/fd/NN> file corresponding to "
4328 "a file descriptor created with"
4332 #: build/C/man2/link.2:301
4334 msgid " open(path, O_TMPFILE | O_EXCL, mode);\n"
4338 #: build/C/man2/link.2:304
4339 msgid "See B<open>(2)."
4343 #: build/C/man2/link.2:315
4345 "I<oldpath> is a relative pathname and I<olddirfd> refers to a directory that "
4346 "has been deleted, or I<newpath> is a relative pathname and I<newdirfd> "
4347 "refers to a directory that has been deleted."
4351 #: build/C/man2/link.2:325 build/C/man2/rename.2:365
4353 "I<oldpath> is relative and I<olddirfd> is a file descriptor referring to a "
4354 "file other than a directory; or similar for I<newpath> and I<newdirfd>"
4358 #: build/C/man2/link.2:334
4360 "B<AT_EMPTY_PATH> was specified in I<flags>, I<oldpath> is an empty string, "
4361 "and I<olddirfd> refers to a directory."
4365 #: build/C/man2/link.2:338
4367 "B<linkat>() was added to Linux in kernel 2.6.16; library support was added "
4368 "to glibc in version 2.4."
4371 #. SVr4 documents additional ENOLINK and
4372 #. EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
4373 #. X/OPEN does not document EFAULT, ENOMEM or EIO.
4375 #: build/C/man2/link.2:344
4376 msgid "B<link>(): SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008."
4380 #: build/C/man2/link.2:347
4381 msgid "B<linkat>(): POSIX.1-2008."
4385 #: build/C/man2/link.2:354
4387 "Hard links, as created by B<link>(), cannot span filesystems. Use "
4388 "B<symlink>(2) if this is required."
4391 #. more precisely: since kernel 1.3.56
4392 #. For example, the default Solaris compilation environment
4393 #. behaves like Linux, and contributors to a March 2005
4394 #. thread in the Austin mailing list reported that some
4395 #. other (System V) implementations did/do the same -- MTK, Apr 05
4397 #: build/C/man2/link.2:385
4399 "POSIX.1-2001 says that B<link>() should dereference I<oldpath> if it is a "
4400 "symbolic link. However, since kernel 2.0, Linux does not do so: if "
4401 "I<oldpath> is a symbolic link, then I<newpath> is created as a (hard) link "
4402 "to the same symbolic link file (i.e., I<newpath> becomes a symbolic link to "
4403 "the same file that I<oldpath> refers to). Some other implementations behave "
4404 "in the same manner as Linux. POSIX.1-2008 changes the specification of "
4405 "B<link>(), making it implementation-dependent whether or not I<oldpath> is "
4406 "dereferenced if it is a symbolic link. For precise control over the "
4407 "treatment of symbolic links when creating a link, use B<linkat>(2)."
4411 #: build/C/man2/link.2:405
4413 "On older kernels where B<linkat>() is unavailable, the glibc wrapper "
4414 "function falls back to the use of B<link>(), unless the B<AT_SYMLINK_FOLLOW> "
4415 "is specified. When I<oldpath> and I<newpath> are relative pathnames, glibc "
4416 "constructs pathnames based on the symbolic links in I</proc/self/fd> that "
4417 "correspond to the I<olddirfd> and I<newdirfd> arguments."
4421 #: build/C/man2/link.2:411
4423 "On NFS filesystems, the return code may be wrong in case the NFS server "
4424 "performs the link creation and dies before it can say so. Use B<stat>(2) "
4425 "to find out if the link got created."
4429 #: build/C/man2/link.2:420
4431 "B<ln>(1), B<open>(2), B<rename>(2), B<stat>(2), B<symlink>(2), B<unlink>(2), "
4432 "B<path_resolution>(7), B<symlink>(7)"
4436 #: build/C/man2/llseek.2:28
4442 #: build/C/man2/llseek.2:28
4448 #: build/C/man2/llseek.2:31
4449 msgid "_llseek - reposition read/write file offset"
4453 #: build/C/man2/llseek.2:35
4456 "B<#include E<lt>sys/types.hE<gt>>\n"
4457 "B<#include E<lt>unistd.hE<gt>>\n"
4461 #: build/C/man2/llseek.2:39
4464 "B<int _llseek(unsigned int >I<fd>B<, unsigned long >I<offset_high>B<,>\n"
4465 "B< unsigned long >I<offset_low>B<, loff_t *>I<result>B<,>\n"
4466 "B< unsigned int >I<whence>B<);>\n"
4470 #: build/C/man2/llseek.2:43
4471 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
4475 #: build/C/man2/llseek.2:62
4477 "The B<_llseek>() function repositions the offset of the open file "
4478 "associated with the file descriptor I<fd> to I<(offset_highE<lt>E<lt>32) | "
4479 "offset_low> bytes relative to the beginning of the file, the current "
4480 "position in the file, or the end of the file, depending on whether I<whence> "
4481 "is B<SEEK_SET>, B<SEEK_CUR>, or B<SEEK_END>, respectively. It returns the "
4482 "resulting file position in the argument I<result>."
4486 #: build/C/man2/llseek.2:69
4488 "Upon successful completion, B<_llseek>() returns 0. Otherwise, a value of "
4489 "-1 is returned and I<errno> is set to indicate the error."
4493 #: build/C/man2/llseek.2:74 build/C/man2/lseek.2:192
4494 msgid "I<fd> is not an open file descriptor."
4498 #: build/C/man2/llseek.2:77
4499 msgid "Problem with copying results to user space."
4503 #: build/C/man2/llseek.2:81
4504 msgid "I<whence> is invalid."
4508 #: build/C/man2/llseek.2:84
4510 "This function is Linux-specific, and should not be used in programs intended "
4515 #: build/C/man2/llseek.2:87
4517 "Glibc does not provide a wrapper for this system call; call it using "
4522 #: build/C/man2/llseek.2:90
4523 msgid "B<lseek>(2), B<lseek64>(3)"
4527 #: build/C/man2/lseek.2:47
4533 #: build/C/man2/lseek.2:47 build/C/man2/open_by_handle_at.2:25
4539 #: build/C/man2/lseek.2:50
4540 msgid "lseek - reposition read/write file offset"
4544 #: build/C/man2/lseek.2:52 build/C/man3/lseek64.3:32
4545 msgid "B<#include E<lt>sys/types.hE<gt>>"
4549 #: build/C/man2/lseek.2:54 build/C/man3/lseek64.3:34 build/C/man2/rmdir.2:35 build/C/man2/write.2:44
4550 msgid "B<#include E<lt>unistd.hE<gt>>"
4554 #: build/C/man2/lseek.2:56
4555 msgid "B<off_t lseek(int >I<fd>B<, off_t >I<offset>B<, int >I<whence>B<);>"
4559 #: build/C/man2/lseek.2:67
4561 "The B<lseek>() function repositions the offset of the open file associated "
4562 "with the file descriptor I<fd> to the argument I<offset> according to the "
4563 "directive I<whence> as follows:"
4567 #: build/C/man2/lseek.2:72
4568 msgid "The offset is set to I<offset> bytes."
4572 #: build/C/man2/lseek.2:77
4573 msgid "The offset is set to its current location plus I<offset> bytes."
4577 #: build/C/man2/lseek.2:82
4578 msgid "The offset is set to the size of the file plus I<offset> bytes."
4582 #: build/C/man2/lseek.2:90
4584 "The B<lseek>() function allows the file offset to be set beyond the end of "
4585 "the file (but this does not change the size of the file). If data is later "
4586 "written at this point, subsequent reads of the data in the gap (a \"hole\") "
4587 "return null bytes (\\(aq\\e0\\(aq) until data is actually written into the "
4592 #: build/C/man2/lseek.2:90
4594 msgid "Seeking file data and holes"
4598 #: build/C/man2/lseek.2:93
4600 "Since version 3.1, Linux supports the following additional values for "
4605 #: build/C/man2/lseek.2:93
4607 msgid "B<SEEK_DATA>"
4611 #: build/C/man2/lseek.2:104
4613 "Adjust the file offset to the next location in the file greater than or "
4614 "equal to I<offset> containing data. If I<offset> points to data, then the "
4615 "file offset is set to I<offset>."
4619 #: build/C/man2/lseek.2:104
4621 msgid "B<SEEK_HOLE>"
4625 #: build/C/man2/lseek.2:118
4627 "Adjust the file offset to the next hole in the file greater than or equal to "
4628 "I<offset>. If I<offset> points into the middle of a hole, then the file "
4629 "offset is set to I<offset>. If there is no hole past I<offset>, then the "
4630 "file offset is adjusted to the end of the file (i.e., there is an implicit "
4631 "hole at the end of any file)."
4635 #: build/C/man2/lseek.2:124
4637 "In both of the above cases, B<lseek>() fails if I<offset> points past the "
4642 #: build/C/man2/lseek.2:130
4644 "These operations allow applications to map holes in a sparsely allocated "
4645 "file. This can be useful for applications such as file backup tools, which "
4646 "can save space when creating backups and preserve holes, if they have a "
4647 "mechanism for discovering holes."
4650 #. https://lkml.org/lkml/2011/4/22/79
4651 #. http://lwn.net/Articles/440255/
4652 #. http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
4654 #: build/C/man2/lseek.2:153
4656 "For the purposes of these operations, a hole is a sequence of zeros that "
4657 "(normally) has not been allocated in the underlying file storage. However, "
4658 "a filesystem is not obliged to report holes, so these operations are not a "
4659 "guaranteed mechanism for mapping the storage space actually allocated to a "
4660 "file. (Furthermore, a sequence of zeros that actually has been written to "
4661 "the underlying storage may not be reported as a hole.) In the simplest "
4662 "implementation, a filesystem can support the operations by making "
4663 "B<SEEK_HOLE> always return the offset of the end of the file, and making "
4664 "B<SEEK_DATA> always return I<offset> (i.e., even if the location referred to "
4665 "by I<offset> is a hole, it can be considered to consist of data that is a "
4666 "sequence of zeros)."
4670 #: build/C/man2/lseek.2:162
4672 "The B<_GNU_SOURCE> feature test macro must be defined in order to obtain the "
4673 "definitions of B<SEEK_DATA> and B<SEEK_HOLE> from I<E<lt>unistd.hE<gt>>."
4677 #: build/C/man2/lseek.2:168
4679 "The B<SEEK_HOLE> and B<SEEK_DATA> operations are supported for the following "
4684 #: build/C/man2/lseek.2:170
4685 msgid "Btrfs (since Linux 3.1)"
4688 #. commit 93862d5e1ab875664c6cc95254fc365028a48bb1
4690 #: build/C/man2/lseek.2:173
4691 msgid "OCFS (since Linux 3.2)"
4695 #: build/C/man2/lseek.2:175
4696 msgid "XFS (since Linux 3.5)"
4700 #: build/C/man2/lseek.2:177
4701 msgid "ext4 (since Linux 3.8)"
4705 #: build/C/man2/lseek.2:179
4706 msgid "tmpfs (since Linux 3.8)"
4710 #: build/C/man2/lseek.2:187
4712 "Upon successful completion, B<lseek>() returns the resulting offset "
4713 "location as measured in bytes from the beginning of the file. On error, the "
4714 "value I<(off_t)\\ -1> is returned and I<errno> is set to indicate the error."
4717 #. Some systems may allow negative offsets for character devices
4718 #. and/or for remote filesystems.
4720 #: build/C/man2/lseek.2:200
4722 "I<whence> is not valid. Or: the resulting file offset would be negative, or "
4723 "beyond the end of a seekable device."
4727 #: build/C/man2/lseek.2:200 build/C/man2/open.2:954 build/C/man2/open_by_handle_at.2:304
4729 msgid "B<EOVERFLOW>"
4732 #. HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW)
4734 #: build/C/man2/lseek.2:205
4735 msgid "The resulting file offset cannot be represented in an I<off_t>."
4739 #: build/C/man2/lseek.2:205
4745 #: build/C/man2/lseek.2:209
4746 msgid "I<fd> is associated with a pipe, socket, or FIFO."
4750 #: build/C/man2/lseek.2:209 build/C/man2/open.2:942
4756 #: build/C/man2/lseek.2:217
4758 "I<whence> is B<SEEK_DATA> or B<SEEK_HOLE>, and the current file offset is "
4759 "beyond the end of the file."
4762 #. SVr4 documents additional error
4763 #. conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE.
4765 #: build/C/man2/lseek.2:219 build/C/man2/read.2:175 build/C/man2/rmdir.2:129 build/C/man2/write.2:193
4766 msgid "SVr4, 4.3BSD, POSIX.1-2001."
4769 #. FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future
4771 #: build/C/man2/lseek.2:227
4773 "B<SEEK_DATA> and B<SEEK_HOLE> are nonstandard extensions also present in "
4774 "Solaris, FreeBSD, and DragonFly BSD; they are proposed for inclusion in the "
4775 "next POSIX revision (Issue 8)."
4779 #: build/C/man2/lseek.2:232
4781 "See B<open>(2) for a discussion of the relationship between file "
4782 "descriptors, open file descriptions, and files."
4786 #: build/C/man2/lseek.2:236
4788 "Some devices are incapable of seeking and POSIX does not specify which "
4789 "devices must support B<lseek>()."
4792 #. Other systems return the number of written characters,
4793 #. using SEEK_SET to set the counter. (Of written characters.)
4795 #: build/C/man2/lseek.2:243
4796 msgid "On Linux, using B<lseek>() on a terminal device returns B<ESPIPE>."
4800 #: build/C/man2/lseek.2:246
4802 "When converting old code, substitute values for I<whence> with the following "
4807 #: build/C/man2/lseek.2:249
4813 #: build/C/man2/lseek.2:250
4815 msgid "0\tSEEK_SET\n"
4819 #: build/C/man2/lseek.2:251
4821 msgid "1\tSEEK_CUR\n"
4825 #: build/C/man2/lseek.2:252
4827 msgid "2\tSEEK_END\n"
4831 #: build/C/man2/lseek.2:253
4833 msgid "L_SET\tSEEK_SET\n"
4837 #: build/C/man2/lseek.2:254
4839 msgid "L_INCR\tSEEK_CUR\n"
4843 #: build/C/man2/lseek.2:255
4845 msgid "L_XTND\tSEEK_END\n"
4849 #: build/C/man2/lseek.2:267
4851 "Note that file descriptors created by B<dup>(2) or B<fork>(2) share the "
4852 "current file position pointer, so seeking on such files may be subject to "
4857 #: build/C/man2/lseek.2:274
4859 "B<dup>(2), B<fork>(2), B<open>(2), B<fseek>(3), B<lseek64>(3), "
4860 "B<posix_fallocate>(3)"
4864 #: build/C/man3/lseek64.3:25
4870 #: build/C/man3/lseek64.3:28
4871 msgid "lseek64 - reposition 64-bit read/write file offset"
4875 #: build/C/man3/lseek64.3:30
4876 msgid "B<#define _LARGEFILE64_SOURCE> /* See feature_test_macros(7) */"
4880 #: build/C/man3/lseek64.3:36
4881 msgid "B<off64_t lseek64(int >I<fd>B<, off64_t >I<offset>B<, int >I<whence>B<);>"
4885 #: build/C/man3/lseek64.3:53
4887 "The B<lseek>(2) family of functions reposition the offset of the open file "
4888 "associated with the file descriptor I<fd> to I<offset> bytes relative to the "
4889 "start, current position, or end of the file, when I<whence> has the value "
4890 "B<SEEK_SET>, B<SEEK_CUR>, or B<SEEK_END>, respectively."
4894 #: build/C/man3/lseek64.3:56
4895 msgid "For more details, return value, and errors, see B<lseek>(2)."
4899 #: build/C/man3/lseek64.3:63
4901 "Four interfaces are available: B<lseek>(2), B<lseek64>(), B<llseek>(2), and "
4902 "the raw system call B<_llseek>(2)."
4906 #: build/C/man3/lseek64.3:63
4912 #: build/C/man3/lseek64.3:65 build/C/man3/lseek64.3:87 build/C/man3/lseek64.3:116
4917 #: build/C/man3/lseek64.3:69
4919 msgid "B<off_t lseek(int >I<fd>B<, off_t >I<offset>B<, int >I<whence>B<);>\n"
4923 #: build/C/man3/lseek64.3:77
4925 "B<lseek>(2) uses the type I<off_t>. This is a 32-bit signed type on 32-bit "
4926 "architectures, unless one compiles with"
4930 #: build/C/man3/lseek64.3:81
4932 msgid "#define _FILE_OFFSET_BITS 64\n"
4936 #: build/C/man3/lseek64.3:85
4937 msgid "in which case it is a 64-bit signed type."
4941 #: build/C/man3/lseek64.3:85
4947 #: build/C/man3/lseek64.3:91
4949 msgid "B<off64_t lseek64(int >I<fd>B<, off64_t >I<offset>B<, int >I<whence>B<);>\n"
4953 #: build/C/man3/lseek64.3:102
4955 "The library routine B<lseek64>() uses a 64-bit type even when I<off_t> is a "
4956 "32-bit type. Its prototype (and the type I<off64_t>) is available only "
4957 "when one compiles with"
4961 #: build/C/man3/lseek64.3:106
4963 msgid "#define _LARGEFILE64_SOURCE\n"
4966 #. in glibc 2.0.94, not in 2.0.6
4968 #: build/C/man3/lseek64.3:114
4970 "The function B<lseek64>() is available since glibc 2.1, and is defined to "
4971 "be an alias for B<llseek>()."
4975 #: build/C/man3/lseek64.3:114
4981 #: build/C/man3/lseek64.3:120
4983 msgid "B<loff_t llseek(int >I<fd>B<, loff_t >I<offset>B<, int >I<whence>B<);>\n"
4986 #. in libc 5.0.9, not in 4.7.6
4988 #: build/C/man3/lseek64.3:136
4990 "The type I<loff_t> is a 64-bit signed type. The library routine B<llseek>() "
4991 "is available in the glibc and works without special defines. However, the "
4992 "glibc headers do not provide a prototype. Users should add the above "
4993 "prototype, or something equivalent, to their own source. When users "
4994 "complained about data loss caused by a miscompilation of B<e2fsck>(8), glibc "
4995 "2.1.3 added the link-time warning"
4999 #: build/C/man3/lseek64.3:139
5000 msgid "the \\`llseek\\' function may be dangerous; use \\`lseek64\\' instead."
5004 #: build/C/man3/lseek64.3:143
5005 msgid "This makes this function unusable if one desires a warning-free compilation."
5009 #: build/C/man3/lseek64.3:143
5015 #: build/C/man3/lseek64.3:146
5017 "All the above functions are implemented in terms of this system call. The "
5022 #: build/C/man3/lseek64.3:151
5025 "B<int _llseek(int >I<fd>B<, off_t >I<offset_hi>B<, off_t >I<offset_lo>B<,>\n"
5026 "B< loff_t *>I<result>B<, int >I<whence>B<);>\n"
5030 #: build/C/man3/lseek64.3:156
5031 msgid "For more details, see B<llseek>(2)."
5035 #: build/C/man3/lseek64.3:161
5036 msgid "The B<lseek64>() function is thread-safe."
5040 #: build/C/man3/lseek64.3:164
5041 msgid "B<llseek>(2), B<lseek>(2)"
5045 #: build/C/man2/open.2:51
5051 #: build/C/man2/open.2:54
5052 msgid "open, openat, creat - open and possibly create a file"
5056 #: build/C/man2/open.2:59
5059 "B<#include E<lt>sys/types.hE<gt>>\n"
5060 "B<#include E<lt>sys/stat.hE<gt>>\n"
5061 "B<#include E<lt>fcntl.hE<gt>>\n"
5065 #: build/C/man2/open.2:62
5068 "B<int open(const char *>I<pathname>B<, int >I<flags>B<);>\n"
5069 "B<int open(const char *>I<pathname>B<, int >I<flags>B<, mode_t "
5074 #: build/C/man2/open.2:64
5076 msgid "B<int creat(const char *>I<pathname>B<, mode_t >I<mode>B<);>\n"
5080 #: build/C/man2/open.2:68
5083 "B<int openat(int >I<dirfd>B<, const char *>I<pathname>B<, int "
5085 "B<int openat(int >I<dirfd>B<, const char *>I<pathname>B<, int >I<flags>B<, "
5086 "mode_t >I<mode>B<);>\n"
5090 #: build/C/man2/open.2:76
5091 msgid "B<openat>():"
5095 #: build/C/man2/open.2:98
5097 "Given a I<pathname> for a file, B<open>() returns a file descriptor, a "
5098 "small, nonnegative integer for use in subsequent system calls (B<read>(2), "
5099 "B<write>(2), B<lseek>(2), B<fcntl>(2), etc.). The file descriptor returned "
5100 "by a successful call will be the lowest-numbered file descriptor not "
5101 "currently open for the process."
5105 #: build/C/man2/open.2:110
5107 "By default, the new file descriptor is set to remain open across an "
5108 "B<execve>(2) (i.e., the B<FD_CLOEXEC> file descriptor flag described in "
5109 "B<fcntl>(2) is initially disabled); the B<O_CLOEXEC> flag, described below, "
5110 "can be used to change this default. The file offset is set to the beginning "
5111 "of the file (see B<lseek>(2))."
5115 #: build/C/man2/open.2:123
5117 "A call to B<open>() creates a new I<open file description>, an entry in the "
5118 "system-wide table of open files. The open file description records the file "
5119 "offset and the file status flags (see below). A file descriptor is a "
5120 "reference to an open file description; this reference is unaffected if "
5121 "I<pathname> is subsequently removed or modified to refer to a different "
5122 "file. For further details on open file descriptions, see NOTES."
5126 #: build/C/man2/open.2:131
5128 "The argument I<flags> must include one of the following I<access modes>: "
5129 "B<O_RDONLY>, B<O_WRONLY>, or B<O_RDWR>. These request opening the file "
5130 "read-only, write-only, or read/write, respectively."
5133 #. SUSv4 divides the flags into:
5137 #. * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
5138 #. though it's not clear what the difference between "other" and
5139 #. "File creation" flags is. I raised an Aardvark to see if this
5140 #. can be clarified in SUSv4; 10 Oct 2008.
5141 #. http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
5142 #. TC1 (balloted in 2013), resolved this, so that those three constants
5143 #. are also categorized" as file status flags.
5145 #: build/C/man2/open.2:170
5147 "In addition, zero or more file creation flags and file status flags can be "
5148 "bitwise-I<or>'d in I<flags>. The I<file creation flags> are B<O_CLOEXEC>, "
5149 "B<O_CREAT>, B<O_DIRECTORY>, B<O_EXCL>, B<O_NOCTTY>, B<O_NOFOLLOW>, "
5150 "B<O_TMPFILE>, B<O_TRUNC>, and B<O_TTY_INIT>. The I<file status flags> are "
5151 "all of the remaining flags listed below. The distinction between these two "
5152 "groups of flags is that the file status flags can be retrieved and (in some "
5153 "cases) modified; see B<fcntl>(2) for details."
5157 #: build/C/man2/open.2:172
5158 msgid "The full list of file creation flags and file status flags is as follows:"
5162 #: build/C/man2/open.2:172
5167 #. For more background, see
5168 #. http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
5169 #. http://nfs.sourceforge.net/
5171 #: build/C/man2/open.2:189
5173 "The file is opened in append mode. Before each B<write>(2), the file offset "
5174 "is positioned at the end of the file, as if with B<lseek>(2). B<O_APPEND> "
5175 "may lead to corrupted files on NFS filesystems if more than one process "
5176 "appends data to a file at once. This is because NFS does not support "
5177 "appending to a file, so the client kernel has to simulate it, which can't be "
5178 "done without a race condition."
5182 #: build/C/man2/open.2:189
5188 #: build/C/man2/open.2:203
5190 "Enable signal-driven I/O: generate a signal (B<SIGIO> by default, but this "
5191 "can be changed via B<fcntl>(2)) when input or output becomes possible on "
5192 "this file descriptor. This feature is available only for terminals, "
5193 "pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See "
5194 "B<fcntl>(2) for further details. See also BUGS, below."
5198 #: build/C/man2/open.2:203
5200 msgid "B<O_CLOEXEC> (since Linux 2.6.23)"
5203 #. NOTE! several other man pages refer to this text
5205 #: build/C/man2/open.2:213
5207 "Enable the close-on-exec flag for the new file descriptor. Specifying this "
5208 "flag permits a program to avoid additional B<fcntl>(2) B<F_SETFD> "
5209 "operations to set the B<FD_CLOEXEC> flag."
5212 #. This flag fixes only one form of the race condition;
5213 #. The race can also occur with, for example, descriptors
5214 #. returned by accept(), pipe(), etc.
5216 #: build/C/man2/open.2:242
5218 "Note that the use of this flag is essential in some multithreaded programs, "
5219 "because using a separate B<fcntl>(2) B<F_SETFD> operation to set the "
5220 "B<FD_CLOEXEC> flag does not suffice to avoid race conditions where one "
5221 "thread opens a file descriptor and attempts to set its close-on-exec flag "
5222 "using B<fcntl>(2) at the same time as another thread does a B<fork>(2) "
5223 "plus B<execve>(2). Depending on the order of execution, the race may lead "
5224 "to the file descriptor returned by B<open>() being unintentionally leaked "
5225 "to the program executed by the child process created by B<fork>(2). (This "
5226 "kind of race is in principle possible for any system call that creates a "
5227 "file descriptor whose close-on-exec flag should be set, and various other "
5228 "Linux system calls provide an equivalent of the B<O_CLOEXEC> flag to deal "
5229 "with this problem.)"
5233 #: build/C/man2/open.2:242
5238 #. As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
5239 #. XFS (since 2.6.14).
5241 #: build/C/man2/open.2:258
5243 "If the file does not exist, it will be created. The owner (user ID) of the "
5244 "file is set to the effective user ID of the process. The group ownership "
5245 "(group ID) is set either to the effective group ID of the process or to the "
5246 "group ID of the parent directory (depending on filesystem type and mount "
5247 "options, and the mode of the parent directory; see the mount options "
5248 "I<bsdgroups> and I<sysvgroups> described in B<mount>(8))."
5252 #: build/C/man2/open.2:285
5254 "I<mode> specifies the permissions to use in case a new file is created. "
5255 "This argument must be supplied when B<O_CREAT> or B<O_TMPFILE> is specified "
5256 "in I<flags>; if neither B<O_CREAT> nor B<O_TMPFILE> is specified, then "
5257 "I<mode> is ignored. The effective permissions are modified by the process's "
5258 "I<umask> in the usual way: The permissions of the created file are I<(mode\\ "
5259 "&\\ ~umask)>. Note that this mode applies only to future accesses of the "
5260 "newly created file; the B<open>() call that creates a read-only file may "
5261 "well return a read/write file descriptor."
5265 #: build/C/man2/open.2:288
5266 msgid "The following symbolic constants are provided for I<mode>:"
5270 #: build/C/man2/open.2:288
5276 #: build/C/man2/open.2:291
5277 msgid "00700 user (file owner) has read, write and execute permission"
5281 #: build/C/man2/open.2:291
5287 #: build/C/man2/open.2:294
5288 msgid "00400 user has read permission"
5292 #: build/C/man2/open.2:294
5298 #: build/C/man2/open.2:297
5299 msgid "00200 user has write permission"
5303 #: build/C/man2/open.2:297
5309 #: build/C/man2/open.2:300
5310 msgid "00100 user has execute permission"
5314 #: build/C/man2/open.2:300
5320 #: build/C/man2/open.2:303
5321 msgid "00070 group has read, write and execute permission"
5325 #: build/C/man2/open.2:303
5331 #: build/C/man2/open.2:306
5332 msgid "00040 group has read permission"
5336 #: build/C/man2/open.2:306
5342 #: build/C/man2/open.2:309
5343 msgid "00020 group has write permission"
5347 #: build/C/man2/open.2:309
5353 #: build/C/man2/open.2:312
5354 msgid "00010 group has execute permission"
5358 #: build/C/man2/open.2:312
5364 #: build/C/man2/open.2:315
5365 msgid "00007 others have read, write and execute permission"
5369 #: build/C/man2/open.2:315
5375 #: build/C/man2/open.2:318
5376 msgid "00004 others have read permission"
5380 #: build/C/man2/open.2:318
5386 #: build/C/man2/open.2:321
5387 msgid "00002 others have write permission"
5391 #: build/C/man2/open.2:321
5397 #: build/C/man2/open.2:324
5398 msgid "00001 others have execute permission"
5402 #: build/C/man2/open.2:325
5404 msgid "B<O_DIRECT> (since Linux 2.4.10)"
5408 #: build/C/man2/open.2:342
5410 "Try to minimize cache effects of the I/O to and from this file. In general "
5411 "this will degrade performance, but it is useful in special situations, such "
5412 "as when applications do their own caching. File I/O is done directly "
5413 "to/from user-space buffers. The B<O_DIRECT> flag on its own makes an effort "
5414 "to transfer data synchronously, but does not give the guarantees of the "
5415 "B<O_SYNC> flag that data and necessary metadata are transferred. To "
5416 "guarantee synchronous I/O, B<O_SYNC> must be used in addition to "
5417 "B<O_DIRECT>. See NOTES below for further discussion."
5421 #: build/C/man2/open.2:346
5423 "A semantically similar (but deprecated) interface for block devices is "
5424 "described in B<raw>(8)."
5428 #: build/C/man2/open.2:346
5430 msgid "B<O_DIRECTORY>"
5433 #. But see the following and its replies:
5434 #. http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
5435 #. [PATCH] open: O_DIRECTORY and O_CREAT together should fail
5436 #. O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
5438 #: build/C/man2/open.2:358
5440 "If I<pathname> is not a directory, cause the open to fail. This flag was "
5441 "added in kernel version 2.1.126, to avoid denial-of-service problems if "
5442 "B<opendir>(3) is called on a FIFO or tape device."
5446 #: build/C/man2/open.2:358
5452 #: build/C/man2/open.2:364
5454 "Write operations on the file will complete according to the requirements of "
5455 "synchronized I/O I<data> integrity completion."
5459 #: build/C/man2/open.2:376
5461 "By the time B<write>(2) (and similar) return, the output data has been "
5462 "transferred to the underlying hardware, along with any file metadata that "
5463 "would be required to retrieve that data (i.e., as though each B<write>(2) "
5464 "was followed by a call to B<fdatasync>(2)). I<See NOTES below>."
5468 #: build/C/man2/open.2:376
5474 #: build/C/man2/open.2:386
5476 "Ensure that this call creates the file: if this flag is specified in "
5477 "conjunction with B<O_CREAT>, and I<pathname> already exists, then B<open>() "
5481 #. POSIX.1-2001 explicitly requires this behavior.
5483 #: build/C/man2/open.2:394
5485 "When these two flags are specified, symbolic links are not followed: if "
5486 "I<pathname> is a symbolic link, then B<open>() fails regardless of where "
5487 "the symbolic link points to."
5491 #: build/C/man2/open.2:410
5493 "In general, the behavior of B<O_EXCL> is undefined if it is used without "
5494 "B<O_CREAT>. There is one exception: on Linux 2.6 and later, B<O_EXCL> can "
5495 "be used without B<O_CREAT> if I<pathname> refers to a block device. If the "
5496 "block device is in use by the system (e.g., mounted), B<open>() fails with "
5497 "the error B<EBUSY>."
5501 #: build/C/man2/open.2:432
5503 "On NFS, B<O_EXCL> is supported only when using NFSv3 or later on kernel 2.6 "
5504 "or later. In NFS environments where B<O_EXCL> support is not provided, "
5505 "programs that rely on it for performing locking tasks will contain a race "
5506 "condition. Portable programs that want to perform atomic file locking using "
5507 "a lockfile, and need to avoid reliance on NFS support for B<O_EXCL>, can "
5508 "create a unique file on the same filesystem (e.g., incorporating hostname "
5509 "and PID), and use B<link>(2) to make a link to the lockfile. If B<link>(2) "
5510 "returns 0, the lock is successful. Otherwise, use B<stat>(2) on the unique "
5511 "file to check if its link count has increased to 2, in which case the lock "
5512 "is also successful."
5516 #: build/C/man2/open.2:432
5518 msgid "B<O_LARGEFILE>"
5522 #: build/C/man2/open.2:454
5524 "(LFS) Allow files whose sizes cannot be represented in an I<off_t> (but can "
5525 "be represented in an I<off64_t>) to be opened. The B<_LARGEFILE64_SOURCE> "
5526 "macro must be defined (before including I<any> header files) in order to "
5527 "obtain this definition. Setting the B<_FILE_OFFSET_BITS> feature test macro "
5528 "to 64 (rather than using B<O_LARGEFILE>) is the preferred method of "
5529 "accessing large files on 32-bit systems (see B<feature_test_macros>(7))."
5533 #: build/C/man2/open.2:454
5535 msgid "B<O_NOATIME> (since Linux 2.6.8)"
5538 #. The O_NOATIME flag also affects the treatment of st_atime
5539 #. by mmap() and readdir(2), MTK, Dec 04.
5541 #: build/C/man2/open.2:467
5543 "Do not update the file last access time (I<st_atime> in the inode) when the "
5544 "file is B<read>(2). This flag is intended for use by indexing or backup "
5545 "programs, where its use can significantly reduce the amount of disk "
5546 "activity. This flag may not be effective on all filesystems. One example "
5547 "is NFS, where the server maintains the access time."
5551 #: build/C/man2/open.2:467
5557 #: build/C/man2/open.2:475
5559 "If I<pathname> refers to a terminal device\\(emsee B<tty>(4)\\(emit will not "
5560 "become the process's controlling terminal even if the process does not have "
5565 #: build/C/man2/open.2:475
5567 msgid "B<O_NOFOLLOW>"
5570 #. The headers from glibc 2.0.100 and later include a
5571 #. definition of this flag; \fIkernels before 2.1.126 will ignore it if
5574 #: build/C/man2/open.2:487
5576 "If I<pathname> is a symbolic link, then the open fails. This is a FreeBSD "
5577 "extension, which was added to Linux in version 2.1.126. Symbolic links in "
5578 "earlier components of the pathname will still be followed. See also "
5583 #: build/C/man2/open.2:487
5585 msgid "B<O_NONBLOCK> or B<O_NDELAY>"
5589 #: build/C/man2/open.2:500
5591 "When possible, the file is opened in nonblocking mode. Neither the "
5592 "B<open>() nor any subsequent operations on the file descriptor which is "
5593 "returned will cause the calling process to wait. For the handling of FIFOs "
5594 "(named pipes), see also B<fifo>(7). For a discussion of the effect of "
5595 "B<O_NONBLOCK> in conjunction with mandatory file locks and with file leases, "
5600 #: build/C/man2/open.2:500
5602 msgid "B<O_PATH> (since Linux 2.6.39)"
5605 #. commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
5606 #. commit 326be7b484843988afe57566b627fb7a70beac56
5607 #. commit 65cfc6722361570bfe255698d9cd4dccaf47570d
5609 #. http://thread.gmane.org/gmane.linux.man/2790/focus=3496
5610 #. Subject: Re: [PATCH] open(2): document O_PATH
5611 #. Newsgroups: gmane.linux.man, gmane.linux.kernel
5613 #: build/C/man2/open.2:522
5615 "Obtain a file descriptor that can be used for two purposes: to indicate a "
5616 "location in the filesystem tree and to perform operations that act purely at "
5617 "the file descriptor level. The file itself is not opened, and other file "
5618 "operations (e.g., B<read>(2), B<write>(2), B<fchmod>(2), B<fchown>(2), "
5619 "B<fgetxattr>(2), B<mmap>(2)) fail with the error B<EBADF>."
5623 #: build/C/man2/open.2:526
5625 "The following operations I<can> be performed on the resulting file "
5629 #. commit 332a2e1244bd08b9e3ecd378028513396a004a24
5630 #. fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
5632 #: build/C/man2/open.2:535
5634 "B<close>(2); B<fchdir>(2) (since Linux 3.5); B<fstat>(2) (since Linux "
5639 #: build/C/man2/open.2:541
5640 msgid "Duplicating the file descriptor (B<dup>(2), B<fcntl>(2) B<F_DUPFD>, etc.)."
5644 #: build/C/man2/open.2:547
5646 "Getting and setting file descriptor flags (B<fcntl>(2) B<F_GETFD> and "
5651 #: build/C/man2/open.2:553
5653 "Retrieving open file status flags using the B<fcntl>(2) B<F_GETFL> "
5654 "operation: the returned flags will include the bit B<O_PATH>."
5658 #: build/C/man2/open.2:566
5660 "Passing the file descriptor as the I<dirfd> argument of B<openat>(2) and "
5661 "the other \"*at()\" system calls. This includes B<linkat>(2) with "
5662 "B<AT_EMPTY_PATH> (or via procfs using B<AT_SYMLINK_FOLLOW>) even if the "
5663 "file is not a directory."
5667 #: build/C/man2/open.2:572
5669 "Passing the file descriptor to another process via a UNIX domain socket (see "
5670 "B<SCM_RIGHTS> in B<unix>(7))."
5674 #: build/C/man2/open.2:584
5676 "When B<O_PATH> is specified in I<flags>, flag bits other than B<O_CLOEXEC>, "
5677 "B<O_DIRECTORY>, and B<O_NOFOLLOW> are ignored."
5681 #: build/C/man2/open.2:600
5683 "If I<pathname> is a symbolic link and the B<O_NOFOLLOW> flag is also "
5684 "specified, then the call returns a file descriptor referring to the symbolic "
5685 "link. This file descriptor can be used as the I<dirfd> argument in calls to "
5686 "B<fchownat>(2), B<fstatat>(2), B<linkat>(2), and B<readlinkat>(2) with an "
5687 "empty pathname to have the calls operate on the symbolic link."
5691 #: build/C/man2/open.2:600
5697 #: build/C/man2/open.2:612
5699 "Write operations on the file will complete according to the requirements of "
5700 "synchronized I/O I<file> integrity completion (by contrast with the "
5701 "synchronized I/O I<data> integrity completion provided by B<O_DSYNC>.)"
5705 #: build/C/man2/open.2:623
5707 "By the time B<write>(2) (and similar) return, the output data and "
5708 "associated file metadata have been transferred to the underlying hardware "
5709 "(i.e., as though each B<write>(2) was followed by a call to B<fsync>(2)). "
5710 "I<See NOTES below>."
5714 #: build/C/man2/open.2:623
5716 msgid "B<O_TMPFILE> (since Linux 3.11)"
5719 #. commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
5720 #. commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
5721 #. commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
5723 #: build/C/man2/open.2:635
5725 "Create an unnamed temporary file. The I<pathname> argument specifies a "
5726 "directory; an unnamed inode will be created in that directory's filesystem. "
5727 "Anything written to the resulting file will be lost when the last file "
5728 "descriptor is closed, unless the file is given a name."
5732 #: build/C/man2/open.2:649
5734 "B<O_TMPFILE> must be specified with one of B<O_RDWR> or B<O_WRONLY> and, "
5735 "optionally, B<O_EXCL>. If B<O_EXCL> is not specified, then B<linkat>(2) "
5736 "can be used to link the temporary file into the filesystem, making it "
5737 "permanent, using code like the following:"
5741 #: build/C/man2/open.2:655
5744 "char path[PATH_MAX];\n"
5745 "fd = open(\"/path/to/dir\", O_TMPFILE | O_RDWR,\n"
5746 " S_IRUSR | S_IWUSR);\n"
5750 #: build/C/man2/open.2:657
5752 msgid "/* File I/O on 'fd'... */\n"
5756 #: build/C/man2/open.2:661
5759 "snprintf(path, PATH_MAX, \"/proc/self/fd/%d\", fd);\n"
5760 "linkat(AT_FDCWD, path, AT_FDCWD, \"/path/for/file\",\n"
5761 " AT_SYMLINK_FOLLOW);\n"
5765 #: build/C/man2/open.2:670
5767 "In this case, the B<open>() I<mode> argument determines the file permission "
5768 "mode, as with B<O_CREAT>."
5772 #: build/C/man2/open.2:682
5774 "Specifying B<O_EXCL> in conjunction with B<O_TMPFILE> prevents a temporary "
5775 "file from being linked into the filesystem in the above manner. (Note that "
5776 "the meaning of B<O_EXCL> in this case is different from the meaning of "
5777 "B<O_EXCL> otherwise.)"
5780 #. Inspired by http://lwn.net/Articles/559147/
5782 #: build/C/man2/open.2:687
5783 msgid "There are two main use cases for B<O_TMPFILE>:"
5787 #: build/C/man2/open.2:696
5789 "Improved B<tmpfile>(3) functionality: race-free creation of temporary files "
5790 "that (1) are automatically deleted when closed; (2) can never be reached via "
5791 "any pathname; (3) are not subject to symlink attacks; and (4) do not require "
5792 "the caller to devise unique names."
5796 #: build/C/man2/open.2:707
5798 "Creating a file that is initially invisible, which is then populated with "
5799 "data and adjusted to have appropriate filesystem attributes (B<chown>(2), "
5800 "B<chmod>(2), B<fsetxattr>(2), etc.) before being atomically linked into the "
5801 "filesystem in a fully formed state (using B<linkat>(2) as described above)."
5804 #. commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
5805 #. commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
5807 #: build/C/man2/open.2:718
5809 "B<O_TMPFILE> requires support by the underlying filesystem; only a subset of "
5810 "Linux filesystems provide that support. In the initial implementation, "
5811 "support was provided in the ext2, ext3, ext4, UDF, Minix, and shmem "
5812 "filesystems. XFS support was added in Linux 3.15."
5816 #: build/C/man2/open.2:718
5822 #: build/C/man2/open.2:732
5824 "If the file already exists and is a regular file and the access mode allows "
5825 "writing (i.e., is B<O_RDWR> or B<O_WRONLY>) it will be truncated to length "
5826 "0. If the file is a FIFO or terminal device file, the B<O_TRUNC> flag is "
5827 "ignored. Otherwise, the effect of B<O_TRUNC> is unspecified."
5831 #: build/C/man2/open.2:732
5837 #: build/C/man2/open.2:740
5839 "B<creat>() is equivalent to B<open>() with I<flags> equal to "
5840 "B<O_CREAT|O_WRONLY|O_TRUNC>."
5844 #: build/C/man2/open.2:740
5850 #: build/C/man2/open.2:746
5852 "The B<openat>() system call operates in exactly the same way as B<open>(), "
5853 "except for the differences described here."
5857 #: build/C/man2/open.2:756
5859 "If the pathname given in I<pathname> is relative, then it is interpreted "
5860 "relative to the directory referred to by the file descriptor I<dirfd> "
5861 "(rather than relative to the current working directory of the calling "
5862 "process, as is done by B<open>() for a relative pathname)."
5866 #: build/C/man2/open.2:768
5868 "If I<pathname> is relative and I<dirfd> is the special value B<AT_FDCWD>, "
5869 "then I<pathname> is interpreted relative to the current working directory of "
5870 "the calling process (like B<open>())."
5874 #: build/C/man2/open.2:774 build/C/man2/readlink.2:134
5875 msgid "If I<pathname> is absolute, then I<dirfd> is ignored."
5879 #: build/C/man2/open.2:783
5881 "B<open>(), B<openat>(), and B<creat>() return the new file descriptor, or "
5882 "-1 if an error occurred (in which case, I<errno> is set appropriately)."
5886 #: build/C/man2/open.2:789
5887 msgid "B<open>(), B<openat>(), and B<creat>() can fail with the following errors:"
5891 #: build/C/man2/open.2:798
5893 "The requested access to the file is not allowed, or search permission is "
5894 "denied for one of the directories in the path prefix of I<pathname>, or the "
5895 "file did not exist yet and write access to the parent directory is not "
5896 "allowed. (See also B<path_resolution>(7).)"
5900 #: build/C/man2/open.2:804
5902 "Where B<O_CREAT> is specified, the file does not exist, and the user's quota "
5903 "of disk blocks or inodes on the filesystem has been exhausted."
5907 #: build/C/man2/open.2:810
5908 msgid "I<pathname> already exists and B<O_CREAT> and B<O_EXCL> were used."
5912 #: build/C/man2/open.2:814 build/C/man2/rmdir.2:67 build/C/man2/unlink.2:182
5913 msgid "I<pathname> points outside your accessible address space."
5917 #: build/C/man2/open.2:814 build/C/man2/write.2:145
5923 #: build/C/man2/open.2:818
5924 msgid "See B<EOVERFLOW>."
5928 #: build/C/man2/open.2:818 build/C/man2/read.2:122 build/C/man3/scanf.3:561 build/C/man3/tmpfile.3:63 build/C/man2/write.2:150
5934 #: build/C/man2/open.2:825
5936 "While blocked waiting to complete an open of a slow device (e.g., a FIFO; "
5937 "see B<fifo>(7)), the call was interrupted by a signal handler; see "
5942 #: build/C/man2/open.2:833
5944 "The filesystem does not support the B<O_DIRECT> flag. See B<NOTES> for more "
5948 #. In particular, __O_TMPFILE instead of O_TMPFILE
5950 #: build/C/man2/open.2:838
5951 msgid "Invalid value in I<flags>."
5955 #: build/C/man2/open.2:848
5957 "B<O_TMPFILE> was specified in I<flags>, but neither B<O_WRONLY> nor "
5958 "B<O_RDWR> was specified."
5962 #: build/C/man2/open.2:848 build/C/man2/open.2:857 build/C/man2/read.2:158 build/C/man2/rename.2:255 build/C/man2/unlink.2:185 build/C/man2/unlink.2:256
5968 #: build/C/man2/open.2:857
5970 "I<pathname> refers to a directory and the access requested involved writing "
5971 "(that is, B<O_WRONLY> or B<O_RDWR> is set)."
5975 #: build/C/man2/open.2:871
5977 "I<pathname> refers to an existing directory, B<O_TMPFILE> and one of "
5978 "B<O_WRONLY> or B<O_RDWR> were specified in I<flags>, but this kernel version "
5979 "does not provide the B<O_TMPFILE> functionality."
5983 #: build/C/man2/open.2:875 build/C/man2/rmdir.2:77
5984 msgid "Too many symbolic links were encountered in resolving I<pathname>."
5988 #: build/C/man2/open.2:884
5990 "I<pathname> was a symbolic link, and I<flags> specified B<O_NOFOLLOW> but "
5995 #: build/C/man2/open.2:884 build/C/man2/pipe.2:148 build/C/man3/tmpfile.3:66
6001 #: build/C/man2/open.2:891
6003 "The process already has the maximum number of files open (see the "
6004 "description of B<RLIMIT_NOFILE> in B<getrlimit>(2))."
6008 #: build/C/man2/open.2:895 build/C/man2/rmdir.2:80 build/C/man2/unlink.2:197
6009 msgid "I<pathname> was too long."
6013 #: build/C/man2/open.2:895 build/C/man2/pipe.2:151 build/C/man3/tmpfile.3:69
6019 #: build/C/man2/open.2:898 build/C/man2/pipe.2:154
6020 msgid "The system limit on the total number of open files has been reached."
6024 #: build/C/man2/open.2:898
6030 #: build/C/man2/open.2:905
6032 "I<pathname> refers to a device special file and no corresponding device "
6033 "exists. (This is a Linux kernel bug; in this situation B<ENXIO> must be "
6038 #: build/C/man2/open.2:912
6040 "B<O_CREAT> is not set and the named file does not exist. Or, a directory "
6041 "component in I<pathname> does not exist or is a dangling symbolic link."
6045 #: build/C/man2/open.2:926
6047 "I<pathname> refers to a nonexistent directory, B<O_TMPFILE> and one of "
6048 "B<O_WRONLY> or B<O_RDWR> were specified in I<flags>, but this kernel version "
6049 "does not provide the B<O_TMPFILE> functionality."
6053 #: build/C/man2/open.2:935
6055 "I<pathname> was to be created but the device containing I<pathname> has no "
6056 "room for the new file."
6060 #: build/C/man2/open.2:942
6062 "A component used as a directory in I<pathname> is not, in fact, a directory, "
6063 "or B<O_DIRECTORY> was specified and I<pathname> was not a directory."
6067 #: build/C/man2/open.2:948
6069 "B<O_NONBLOCK> | B<O_WRONLY> is set, the named file is a FIFO, and no process "
6070 "has the FIFO open for reading. Or, the file is a device special file and no "
6071 "corresponding device exists."
6075 #: build/C/man2/open.2:948 build/C/man2/open_by_handle_at.2:301
6077 msgid "B<EOPNOTSUPP>"
6081 #: build/C/man2/open.2:954
6082 msgid "The filesystem containing I<pathname> does not support B<O_TMPFILE>."
6085 #. See http://bugzilla.kernel.org/show_bug.cgi?id=7253
6086 #. "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
6087 #. Reported 2006-10-03
6089 #: build/C/man2/open.2:974
6091 "I<pathname> refers to a regular file that is too large to be opened. The "
6092 "usual scenario here is that an application compiled on a 32-bit platform "
6093 "without I<-D_FILE_OFFSET_BITS=64> tried to open a file whose size exceeds "
6094 "I<(1E<lt>E<lt>31)-1> bytes; see also B<O_LARGEFILE> above. This is the "
6095 "error specified by POSIX.1-2001; in kernels before 2.6.24, Linux gave the "
6096 "error B<EFBIG> for this case."
6099 #. Strictly speaking, it's the filesystem UID... (MTK)
6101 #: build/C/man2/open.2:982
6103 "The B<O_NOATIME> flag was specified, but the effective user ID of the caller "
6104 "did not match the owner of the file and the caller was not privileged "
6109 #: build/C/man2/open.2:986 build/C/man2/write.2:177
6110 msgid "The operation was prevented by a file seal; see B<fcntl>(2)."
6114 #: build/C/man2/open.2:991
6116 "I<pathname> refers to a file on a read-only filesystem and write access was "
6121 #: build/C/man2/open.2:991
6127 #: build/C/man2/open.2:996
6129 "I<pathname> refers to an executable image which is currently being executed "
6130 "and write access was requested."
6134 #: build/C/man2/open.2:996
6136 msgid "B<EWOULDBLOCK>"
6140 #: build/C/man2/open.2:1003
6142 "The B<O_NONBLOCK> flag was specified, and an incompatible lease was held on "
6143 "the file (see B<fcntl>(2))."
6147 #: build/C/man2/open.2:1006
6148 msgid "The following additional errors can occur for B<openat>():"
6152 #: build/C/man2/open.2:1010 build/C/man2/readlink.2:206 build/C/man2/unlink.2:252
6153 msgid "I<dirfd> is not a valid file descriptor."
6157 #: build/C/man2/open.2:1016
6159 "I<pathname> is a relative pathname and I<dirfd> is a file descriptor "
6160 "referring to a file other than a directory."
6164 #: build/C/man2/open.2:1020
6166 "B<openat>() was added to Linux in kernel 2.6.16; library support was added "
6167 "to glibc in version 2.4."
6171 #: build/C/man2/open.2:1024
6172 msgid "B<open>(), B<creat>() SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008."
6176 #: build/C/man2/open.2:1027
6177 msgid "B<openat>(): POSIX.1-2008."
6181 #: build/C/man2/open.2:1038
6183 "The B<O_DIRECT>, B<O_NOATIME>, B<O_PATH>, and B<O_TMPFILE> flags are "
6184 "Linux-specific. One must define B<_GNU_SOURCE> to obtain their definitions."
6188 #: build/C/man2/open.2:1053
6190 "The B<O_CLOEXEC>, B<O_DIRECTORY>, and B<O_NOFOLLOW> flags are not specified "
6191 "in POSIX.1-2001, but are specified in POSIX.1-2008. Since glibc 2.12, one "
6192 "can obtain their definitions by defining either B<_POSIX_C_SOURCE> with a "
6193 "value greater than or equal to 200809L or B<_XOPEN_SOURCE> with a value "
6194 "greater than or equal to 700. In glibc 2.11 and earlier, one obtains the "
6195 "definitions by defining B<_GNU_SOURCE>."
6199 #: build/C/man2/open.2:1064
6201 "As noted in B<feature_test_macros>(7), feature test macros such as "
6202 "B<_POSIX_C_SOURCE>, B<_XOPEN_SOURCE>, and B<_GNU_SOURCE> must be defined "
6203 "before including I<any> header files."
6207 #: build/C/man2/open.2:1072
6209 "Under Linux, the B<O_NONBLOCK> flag indicates that one wants to open but "
6210 "does not necessarily have the intention to read or write. This is typically "
6211 "used to open devices in order to get a file descriptor for use with "
6215 #. Linux 2.0, 2.5: truncate
6216 #. Solaris 5.7, 5.8: truncate
6217 #. Irix 6.5: truncate
6218 #. Tru64 5.1B: truncate
6219 #. HP-UX 11.22: truncate
6220 #. FreeBSD 4.7: truncate
6222 #: build/C/man2/open.2:1084
6224 "The (undefined) effect of B<O_RDONLY | O_TRUNC> varies among "
6225 "implementations. On many systems the file is actually truncated."
6229 #: build/C/man2/open.2:1092
6231 "Note that B<open>() can open device special files, but B<creat>() cannot "
6232 "create them; use B<mknod>(2) instead."
6236 #: build/C/man2/open.2:1113
6238 "If the file is newly created, its I<st_atime>, I<st_ctime>, I<st_mtime> "
6239 "fields (respectively, time of last access, time of last status change, and "
6240 "time of last modification; see B<stat>(2)) are set to the current time, and "
6241 "so are the I<st_ctime> and I<st_mtime> fields of the parent directory. "
6242 "Otherwise, if the file is modified because of the B<O_TRUNC> flag, its "
6243 "st_ctime and st_mtime fields are set to the current time."
6247 #: build/C/man2/open.2:1113
6249 msgid "Open file descriptions"
6253 #: build/C/man2/open.2:1121
6255 "The term open file description is the one used by POSIX to refer to the "
6256 "entries in the system-wide table of open files. In other contexts, this "
6257 "object is variously also called an \"open file object\", a \"file handle\", "
6258 "an \"open file table entry\", or\\(emin kernel-developer parlance\\(ema "
6263 #: build/C/man2/open.2:1134
6265 "When a file descriptor is duplicated (using B<dup>(2) or similar), the "
6266 "duplicate refers to the same open file description as the original file "
6267 "descriptor, and the two file descriptors consequently share the file offset "
6268 "and file status flags. Such sharing can also occur between processes: a "
6269 "child process created via B<fork>(2) inherits duplicates of its parent's "
6270 "file descriptors, and those duplicates refer to the same open file "
6275 #: build/C/man2/open.2:1142
6277 "Each B<open>(2) of a file creates a new open file description; thus, there "
6278 "may be multiple open file descriptions corresponding to a file inode."
6282 #: build/C/man2/open.2:1142
6284 msgid "Synchronized I/O"
6288 #: build/C/man2/open.2:1157
6290 "The POSIX.1-2008 \"synchronized I/O\" option specifies different variants of "
6291 "synchronized I/O, and specifies the B<open>() flags B<O_SYNC>, B<O_DSYNC>, "
6292 "and B<O_RSYNC> for controlling the behavior. Regardless of whether an "
6293 "implementation supports this option, it must at least support the use of "
6294 "B<O_SYNC> for regular files."
6298 #: build/C/man2/open.2:1168
6300 "Linux implements B<O_SYNC> and B<O_DSYNC>, but not B<O_RSYNC>. (Somewhat "
6301 "incorrectly, glibc defines B<O_RSYNC> to have the same value as B<O_SYNC>.)"
6305 #: build/C/man2/open.2:1186
6307 "B<O_SYNC> provides synchronized I/O I<file> integrity completion, meaning "
6308 "write operations will flush data and all associated metadata to the "
6309 "underlying hardware. B<O_DSYNC> provides synchronized I/O I<data> integrity "
6310 "completion, meaning write operations will flush data to the underlying "
6311 "hardware, but will only flush metadata updates that are required to allow a "
6312 "subsequent read operation to complete successfully. Data integrity "
6313 "completion can reduce the number of disk operations that are required for "
6314 "applications that don't need the guarantees of file integrity completion."
6318 #: build/C/man2/open.2:1203
6320 "To understand the difference between the two types of completion, consider "
6321 "two pieces of file metadata: the file last modification timestamp "
6322 "(I<st_mtime>) and the file length. All write operations will update the "
6323 "last file modification timestamp, but only writes that add data to the end "
6324 "of the file will change the file length. The last modification timestamp is "
6325 "not needed to ensure that a read completes successfully, but the file length "
6326 "is. Thus, B<O_DSYNC> would only guarantee to flush updates to the file "
6327 "length metadata (whereas B<O_SYNC> would also always flush the last "
6328 "modification timestamp metadata)."
6332 #: build/C/man2/open.2:1215
6334 "Before Linux 2.6.33, Linux implemented only the B<O_SYNC> flag for "
6335 "B<open>(). However, when that flag was specified, most filesystems actually "
6336 "provided the equivalent of synchronized I/O I<data> integrity completion "
6337 "(i.e., B<O_SYNC> was actually implemented as the equivalent of B<O_DSYNC>)."
6341 #: build/C/man2/open.2:1234
6343 "Since Linux 2.6.33, proper B<O_SYNC> support is provided. However, to "
6344 "ensure backward binary compatibility, B<O_DSYNC> was defined with the same "
6345 "value as the historical B<O_SYNC>, and B<O_SYNC> was defined as a new "
6346 "(two-bit) flag value that includes the B<O_DSYNC> flag value. This ensures "
6347 "that applications compiled against new headers get at least B<O_DSYNC> "
6348 "semantics on pre-2.6.33 kernels."
6352 #: build/C/man2/open.2:1234
6358 #: build/C/man2/open.2:1238
6360 "There are many infelicities in the protocol underlying NFS, affecting "
6361 "amongst others B<O_SYNC> and B<O_NDELAY>."
6365 #: build/C/man2/open.2:1253
6367 "On NFS filesystems with UID mapping enabled, B<open>() may return a file "
6368 "descriptor but, for example, B<read>(2) requests are denied with "
6369 "B<EACCES>. This is because the client performs B<open>() by checking the "
6370 "permissions, but UID mapping is performed by the server upon read and write "
6375 #: build/C/man2/open.2:1253
6377 msgid "File access mode"
6381 #: build/C/man2/open.2:1268
6383 "Unlike the other values that can be specified in I<flags>, the I<access "
6384 "mode> values B<O_RDONLY>, B<O_WRONLY>, and B<O_RDWR> do not specify "
6385 "individual bits. Rather, they define the low order two bits of I<flags>, "
6386 "and are defined respectively as 0, 1, and 2. In other words, the "
6387 "combination B<O_RDONLY | O_WRONLY> is a logical error, and certainly does "
6388 "not have the same meaning as B<O_RDWR>."
6391 #. See for example util-linux's disk-utils/setfdprm.c
6392 #. For some background on access mode 3, see
6393 #. http://thread.gmane.org/gmane.linux.kernel/653123
6394 #. "[RFC] correct flags to f_mode conversion in __dentry_open"
6395 #. LKML, 12 Mar 2008
6397 #: build/C/man2/open.2:1285
6399 "Linux reserves the special, nonstandard access mode 3 (binary 11) in "
6400 "I<flags> to mean: check for read and write permission on the file and return "
6401 "a descriptor that can't be used for reading or writing. This nonstandard "
6402 "access mode is used by some Linux drivers to return a descriptor that is to "
6403 "be used only for device-specific B<ioctl>(2) operations."
6407 #: build/C/man2/open.2:1285
6409 msgid "Rationale for openat() and other directory file descriptor APIs"
6413 #: build/C/man2/open.2:1314
6415 "B<openat>() and the other system calls and library functions that take a "
6416 "directory file descriptor argument (i.e., B<execveat>(2), B<faccessat>(2), "
6417 "B<fanotify_mark>(2), B<fchmodat>(2), B<fchownat>(2), B<fstatat>(2), "
6418 "B<futimesat>(2), B<linkat>(2), B<mkdirat>(2), B<mknodat>(2), "
6419 "B<name_to_handle_at>(2), B<readlinkat>(2), B<renameat>(2), B<symlinkat>(2), "
6420 "B<unlinkat>(2), B<utimensat>(2) B<mkfifoat>(3), and B<scandirat>(3)) are "
6421 "supported for two reasons. Here, the explanation is in terms of the "
6422 "B<openat>() call, but the rationale is analogous for the other interfaces."
6426 #: build/C/man2/open.2:1345
6428 "First, B<openat>() allows an application to avoid race conditions that "
6429 "could occur when using B<open>() to open files in directories other than "
6430 "the current working directory. These race conditions result from the fact "
6431 "that some component of the directory prefix given to B<open>() could be "
6432 "changed in parallel with the call to B<open>(). Suppose, for example, that "
6433 "we wish to create the file I<path/to/xxx.dep> if the file I<path/to/xxx> "
6434 "exists. The problem is that between the existence check and the file "
6435 "creation step, I<path> or I<to> (which might be symbolic links) could be "
6436 "modified to point to a different location. Such races can be avoided by "
6437 "opening a file descriptor for the target directory, and then specifying that "
6438 "file descriptor as the I<dirfd> argument of (say) B<fstatat>(2) and "
6443 #: build/C/man2/open.2:1356
6445 "Second, B<openat>() allows the implementation of a per-thread \"current "
6446 "working directory\", via file descriptor(s) maintained by the application. "
6447 "(This functionality can also be obtained by tricks based on the use of "
6448 "I</proc/self/fd/>dirfd, but less efficiently.)"
6452 #: build/C/man2/open.2:1356
6458 #: build/C/man2/open.2:1373
6460 "The B<O_DIRECT> flag may impose alignment restrictions on the length and "
6461 "address of user-space buffers and the file offset of I/Os. In Linux "
6462 "alignment restrictions vary by filesystem and kernel version and might be "
6463 "absent entirely. However there is currently no filesystem-independent "
6464 "interface for an application to discover these restrictions for a given file "
6465 "or filesystem. Some filesystems provide their own interfaces for doing so, "
6466 "for example the B<XFS_IOC_DIOINFO> operation in B<xfsctl>(3)."
6470 #: build/C/man2/open.2:1383
6472 "Under Linux 2.4, transfer sizes, and the alignment of the user buffer and "
6473 "the file offset must all be multiples of the logical block size of the "
6474 "filesystem. Since Linux 2.6.0, alignment to the logical block size of the "
6475 "underlying storage (typically 512 bytes) suffices. The logical block size "
6476 "can be determined using the B<ioctl>(2) B<BLKSSZGET> operation or from the "
6477 "shell using the command:"
6481 #: build/C/man2/open.2:1385
6483 msgid " blockdev --getss\n"
6487 #: build/C/man2/open.2:1419
6489 "B<O_DIRECT> I/Os should never be run concurrently with the B<fork>(2) "
6490 "system call, if the memory buffer is a private mapping (i.e., any mapping "
6491 "created with the B<mmap>(2) B<MAP_PRIVATE> flag; this includes memory "
6492 "allocated on the heap and statically allocated buffers). Any such I/Os, "
6493 "whether submitted via an asynchronous I/O interface or from another thread "
6494 "in the process, should be completed before B<fork>(2) is called. Failure "
6495 "to do so can result in data corruption and undefined behavior in parent and "
6496 "child processes. This restriction does not apply when the memory buffer for "
6497 "the B<O_DIRECT> I/Os was created using B<shmat>(2) or B<mmap>(2) with the "
6498 "B<MAP_SHARED> flag. Nor does this restriction apply when the memory buffer "
6499 "has been advised as B<MADV_DONTFORK> with B<madvise>(2), ensuring that it "
6500 "will not be available to the child after B<fork>(2)."
6504 #: build/C/man2/open.2:1429
6506 "The B<O_DIRECT> flag was introduced in SGI IRIX, where it has alignment "
6507 "restrictions similar to those of Linux 2.4. IRIX has also a B<fcntl>(2) "
6508 "call to query appropriate alignments, and sizes. FreeBSD 4.x introduced a "
6509 "flag of the same name, but without alignment restrictions."
6513 #: build/C/man2/open.2:1438
6515 "B<O_DIRECT> support was added under Linux in kernel version 2.4.10. Older "
6516 "Linux kernels simply ignore this flag. Some filesystems may not implement "
6517 "the flag and B<open>() will fail with B<EINVAL> if it is used."
6521 #: build/C/man2/open.2:1449
6523 "Applications should avoid mixing B<O_DIRECT> and normal I/O to the same "
6524 "file, and especially to overlapping byte regions in the same file. Even "
6525 "when the filesystem correctly handles the coherency issues in this "
6526 "situation, overall I/O throughput is likely to be slower than using either "
6527 "mode alone. Likewise, applications should avoid mixing B<mmap>(2) of files "
6528 "with direct I/O to the same files."
6532 #: build/C/man2/open.2:1471
6534 "The behavior of B<O_DIRECT> with NFS will differ from local filesystems. "
6535 "Older kernels, or kernels configured in certain ways, may not support this "
6536 "combination. The NFS protocol does not support passing the flag to the "
6537 "server, so B<O_DIRECT> I/O will bypass the page cache only on the client; "
6538 "the server may still cache the I/O. The client asks the server to make the "
6539 "I/O synchronous to preserve the synchronous semantics of B<O_DIRECT>. Some "
6540 "servers will perform poorly under these circumstances, especially if the I/O "
6541 "size is small. Some servers may also be configured to lie to clients about "
6542 "the I/O having reached stable storage; this will avoid the performance "
6543 "penalty at some risk to data integrity in the event of server power "
6544 "failure. The Linux NFS client places no alignment restrictions on "
6549 #: build/C/man2/open.2:1478
6551 "In summary, B<O_DIRECT> is a potentially powerful tool that should be used "
6552 "with caution. It is recommended that applications treat use of B<O_DIRECT> "
6553 "as a performance option which is disabled by default."
6557 #: build/C/man2/open.2:1483
6559 "\"The thing that has always disturbed me about O_DIRECT is that the whole "
6560 "interface is just stupid, and was probably designed by a deranged monkey on "
6561 "some serious mind-controlling substances.\"\\(emLinus"
6564 #. FIXME . Check bugzilla report on open(O_ASYNC)
6565 #. See http://bugzilla.kernel.org/show_bug.cgi?id=5993
6567 #: build/C/man2/open.2:1495
6569 "Currently, it is not possible to enable signal-driven I/O by specifying "
6570 "B<O_ASYNC> when calling B<open>(); use B<fcntl>(2) to enable this flag."
6574 #: build/C/man2/open.2:1503
6576 "One must check for two different error codes, B<EISDIR> and B<ENOENT>, when "
6577 "trying to determine whether the kernel supports B<O_TMPFILE> functionality."
6581 #: build/C/man2/open.2:1525
6583 "B<chmod>(2), B<chown>(2), B<close>(2), B<dup>(2), B<fcntl>(2), B<link>(2), "
6584 "B<lseek>(2), B<mknod>(2), B<mmap>(2), B<mount>(2), B<open_by_handle_at>(2), "
6585 "B<read>(2), B<socket>(2), B<stat>(2), B<umask>(2), B<unlink>(2), "
6586 "B<write>(2), B<fopen>(3), B<fifo>(7), B<path_resolution>(7), B<symlink>(7)"
6590 #: build/C/man2/open_by_handle_at.2:25
6592 msgid "OPEN_BY_HANDLE_AT"
6596 #: build/C/man2/open_by_handle_at.2:29
6598 "name_to_handle_at, open_by_handle_at - obtain handle for a pathname and open "
6603 #: build/C/man2/open_by_handle_at.2:35
6606 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
6607 "B<#include E<lt>sys/types.hE<gt>>\n"
6608 "B<#include E<lt>sys/stat.hE<gt>>\n"
6609 "B<#include E<lt>fcntl.hE<gt>>\n"
6613 #: build/C/man2/open_by_handle_at.2:39
6616 "B<int name_to_handle_at(int >I<dirfd>B<, const char *>I<pathname>B<,>\n"
6617 "B< struct file_handle *>I<handle>B<,>\n"
6618 "B< int *>I<mount_id>B<, int >I<flags>B<);>\n"
6622 #: build/C/man2/open_by_handle_at.2:42
6625 "B<int open_by_handle_at(int >I<mount_fd>B<, struct file_handle "
6627 "B< int >I<flags>B<);>\n"
6631 #: build/C/man2/open_by_handle_at.2:59
6633 "The B<name_to_handle_at>() and B<open_by_handle_at>() system calls split "
6634 "the functionality of B<openat>(2) into two parts: B<name_to_handle_at>() "
6635 "returns an opaque handle that corresponds to a specified file; "
6636 "B<open_by_handle_at>() opens the file corresponding to a handle returned by "
6637 "a previous call to B<name_to_handle_at>() and returns an open file "
6642 #: build/C/man2/open_by_handle_at.2:59
6644 msgid "name_to_handle_at()"
6648 #: build/C/man2/open_by_handle_at.2:71
6650 "The B<name_to_handle_at>() system call returns a file handle and a mount ID "
6651 "corresponding to the file specified by the I<dirfd> and I<pathname> "
6652 "arguments. The file handle is returned via the argument I<handle>, which is "
6653 "a pointer to a structure of the following form:"
6657 #: build/C/man2/open_by_handle_at.2:80
6660 "struct file_handle {\n"
6661 " unsigned int handle_bytes; /* Size of f_handle [in, out] */\n"
6662 " int handle_type; /* Handle type [out] */\n"
6663 " unsigned char f_handle[0]; /* File identifier (sized by\n"
6664 " caller) [out] */\n"
6669 #: build/C/man2/open_by_handle_at.2:99
6671 "It is the caller's responsibility to allocate the structure with a size "
6672 "large enough to hold the handle returned in I<f_handle>. Before the call, "
6673 "the I<handle_bytes> field should be initialized to contain the allocated "
6674 "size for I<f_handle>. (The constant B<MAX_HANDLE_SZ>, defined in "
6675 "I<E<lt>fcntl.hE<gt>>, specifies the maximum possible size for a file "
6676 "handle.) Upon successful return, the I<handle_bytes> field is updated to "
6677 "contain the number of bytes actually written to I<f_handle>."
6681 #: build/C/man2/open_by_handle_at.2:112
6683 "The caller can discover the required size for the I<file_handle> structure "
6684 "by making a call in which I<handle-E<gt>handle_bytes> is zero; in this case, "
6685 "the call fails with the error B<EOVERFLOW> and I<handle-E<gt>handle_bytes> "
6686 "is set to indicate the required size; the caller can then use this "
6687 "information to allocate a structure of the correct size (see EXAMPLE below)."
6691 #: build/C/man2/open_by_handle_at.2:123
6693 "Other than the use of the I<handle_bytes> field, the caller should treat the "
6694 "I<file_handle> structure as an opaque data type: the I<handle_type> and "
6695 "I<f_handle> fields are needed only by a subsequent call to "
6696 "B<open_by_handle_at>()."
6700 #: build/C/man2/open_by_handle_at.2:131
6702 "The I<flags> argument is a bit mask constructed by ORing together zero or "
6703 "more of B<AT_EMPTY_PATH> and B<AT_SYMLINK_FOLLOW>, described below."
6707 #: build/C/man2/open_by_handle_at.2:138
6709 "Together, the I<pathname> and I<dirfd> arguments identify the file for which "
6710 "a handle is to be obtained. There are four distinct cases:"
6714 #: build/C/man2/open_by_handle_at.2:146
6716 "If I<pathname> is a nonempty string containing an absolute pathname, then a "
6717 "handle is returned for the file referred to by that pathname. In this case, "
6718 "I<dirfd> is ignored."
6722 #: build/C/man2/open_by_handle_at.2:157
6724 "If I<pathname> is a nonempty string containing a relative pathname and "
6725 "I<dirfd> has the special value B<AT_FDCWD>, then I<pathname> is interpreted "
6726 "relative to the current working directory of the caller, and a handle is "
6727 "returned for the file to which it refers."
6731 #: build/C/man2/open_by_handle_at.2:170
6733 "If I<pathname> is a nonempty string containing a relative pathname and "
6734 "I<dirfd> is a file descriptor referring to a directory, then I<pathname> is "
6735 "interpreted relative to the directory referred to by I<dirfd>, and a handle "
6736 "is returned for the file to which it refers. (See B<openat>(2) for an "
6737 "explanation of why \"directory file descriptors\" are useful.)"
6741 #: build/C/man2/open_by_handle_at.2:184
6743 "If I<pathname> is an empty string and I<flags> specifies the value "
6744 "B<AT_EMPTY_PATH>, then I<dirfd> can be an open file descriptor referring to "
6745 "any type of file, or B<AT_FDCWD>, meaning the current working directory, and "
6746 "a handle is returned for the file to which it refers."
6750 #: build/C/man2/open_by_handle_at.2:196
6752 "The I<mount_id> argument returns an identifier for the filesystem mount that "
6753 "corresponds to I<pathname>. This corresponds to the first field in one of "
6754 "the records in I</proc/self/mountinfo>. Opening the pathname in the fifth "
6755 "field of that record yields a file descriptor for the mount point; that file "
6756 "descriptor can be used in a subsequent call to B<open_by_handle_at>()."
6760 #: build/C/man2/open_by_handle_at.2:209
6762 "By default, B<name_to_handle_at>() does not dereference I<pathname> if it "
6763 "is a symbolic link, and thus returns a handle for the link itself. If "
6764 "B<AT_SYMLINK_FOLLOW> is specified in I<flags>, I<pathname> is dereferenced "
6765 "if it is a symbolic link (so that the call returns a handle for the file "
6766 "referred to by the link)."
6770 #: build/C/man2/open_by_handle_at.2:209
6772 msgid "open_by_handle_at()"
6776 #: build/C/man2/open_by_handle_at.2:216
6778 "The B<open_by_handle_at>() system call opens the file referred to by "
6779 "I<handle>, a file handle returned by a previous call to "
6780 "B<name_to_handle_at>()."
6784 #: build/C/man2/open_by_handle_at.2:226
6786 "The I<mount_fd> argument is a file descriptor for any object (file, "
6787 "directory, etc.) in the mounted filesystem with respect to which I<handle> "
6788 "should be interpreted. The special value B<AT_FDCWD> can be specified, "
6789 "meaning the current working directory of the caller."
6793 #: build/C/man2/open_by_handle_at.2:239
6795 "The I<flags> argument is as for B<open>(2). If I<handle> refers to a "
6796 "symbolic link, the caller must specify the B<O_PATH> flag, and the symbolic "
6797 "link is not dereferenced; the B<O_NOFOLLOW> flag, if specified, is ignored."
6801 #: build/C/man2/open_by_handle_at.2:245
6803 "The caller must have the B<CAP_DAC_READ_SEARCH> capability to invoke "
6804 "B<open_by_handle_at>()."
6808 #: build/C/man2/open_by_handle_at.2:252
6810 "On success, B<name_to_handle_at>() returns 0, and B<open_by_handle_at>() "
6811 "returns a nonnegative file descriptor."
6815 #: build/C/man2/open_by_handle_at.2:256
6817 "In the event of an error, both system calls return -1 and set I<errno> to "
6818 "indicate the cause of the error."
6822 #: build/C/man2/open_by_handle_at.2:263
6824 "B<name_to_handle_at>() and B<open_by_handle_at>() can fail for the same "
6825 "errors as B<openat>(2). In addition, they can fail with the errors noted "
6830 #: build/C/man2/open_by_handle_at.2:266
6831 msgid "B<name_to_handle_at>() can fail with the following errors:"
6835 #: build/C/man2/open_by_handle_at.2:273
6837 "I<pathname>, I<mount_id>, or I<handle> points outside your accessible "
6842 #: build/C/man2/open_by_handle_at.2:277
6843 msgid "I<flags> includes an invalid bit value."
6847 #: build/C/man2/open_by_handle_at.2:282
6848 msgid "I<handle-E<gt>handle_bytes> is greater than B<MAX_HANDLE_SZ>."
6852 #: build/C/man2/open_by_handle_at.2:289
6854 "I<pathname> is an empty string, but B<AT_EMPTY_PATH> was not specified in "
6859 #: build/C/man2/open_by_handle_at.2:301
6861 "The file descriptor supplied in I<dirfd> does not refer to a directory, and "
6862 "it is not the case that both I<flags> includes B<AT_EMPTY_PATH> and "
6863 "I<pathname> is an empty string."
6867 #: build/C/man2/open_by_handle_at.2:304
6868 msgid "The filesystem does not support decoding of a pathname to a file handle."
6872 #: build/C/man2/open_by_handle_at.2:314
6874 "The I<handle-E<gt>handle_bytes> value passed into the call was too small. "
6875 "When this error occurs, I<handle-E<gt>handle_bytes> is updated to indicate "
6876 "the required size for the handle."
6880 #: build/C/man2/open_by_handle_at.2:317
6881 msgid "B<open_by_handle_at>() can fail with the following errors:"
6885 #: build/C/man2/open_by_handle_at.2:321
6886 msgid "I<mount_fd> is not an open file descriptor."
6890 #: build/C/man2/open_by_handle_at.2:325
6891 msgid "I<handle> points outside your accessible address space."
6895 #: build/C/man2/open_by_handle_at.2:331
6897 "I<handle-E<gt>handle_bytes> is greater than B<MAX_HANDLE_SZ> or is equal to "
6902 #: build/C/man2/open_by_handle_at.2:338
6904 "I<handle> refers to a symbolic link, but B<O_PATH> was not specified in "
6909 #: build/C/man2/open_by_handle_at.2:343
6910 msgid "The caller does not have the B<CAP_DAC_READ_SEARCH> capability."
6914 #: build/C/man2/open_by_handle_at.2:343
6920 #: build/C/man2/open_by_handle_at.2:349
6922 "The specified I<handle> is not valid. This error will occur if, for "
6923 "example, the file has been deleted."
6927 #: build/C/man2/open_by_handle_at.2:352
6929 "These system calls first appeared in Linux 2.6.39. Library support is "
6930 "provided in glibc since version 2.14."
6934 #: build/C/man2/open_by_handle_at.2:354
6935 msgid "These system calls are nonstandard Linux extensions."
6939 #: build/C/man2/open_by_handle_at.2:359
6941 "FreeBSD has a broadly similar pair of system calls in the form of B<getfh>() "
6946 #: build/C/man2/open_by_handle_at.2:364
6948 "A file handle can be generated in one process using B<name_to_handle_at>() "
6949 "and later used in a different process that calls B<open_by_handle_at>()."
6953 #: build/C/man2/open_by_handle_at.2:370
6955 "Some filesystem don't support the translation of pathnames to file handles, "
6956 "for example, I</proc>, I</sys>, and various network filesystems."
6960 #: build/C/man2/open_by_handle_at.2:377
6962 "A file handle may become invalid (\"stale\") if a file is deleted, or for "
6963 "other filesystem-specific reasons. Invalid handles are notified by an "
6964 "B<ESTALE> error from B<open_by_handle_at>()."
6967 #. https://lwn.net/Articles/375888/
6968 #. "Open by handle" - Jonathan Corbet, 2010-02-23
6970 #: build/C/man2/open_by_handle_at.2:387
6972 "These system calls are designed for use by user-space file servers. For "
6973 "example, a user-space NFS server might generate a file handle and pass it to "
6974 "an NFS client. Later, when the client wants to open the file, it could pass "
6975 "the handle back to the server. This sort of functionality allows a "
6976 "user-space file server to operate in a stateless fashion with respect to the "
6980 #. commit bcda76524cd1fa32af748536f27f674a13e56700
6982 #: build/C/man2/open_by_handle_at.2:409
6984 "If I<pathname> refers to a symbolic link and I<flags> does not specify "
6985 "B<AT_SYMLINK_FOLLOW>, then B<name_to_handle_at>() returns a handle for the "
6986 "link (rather than the file to which it refers). The process receiving the "
6987 "handle can later perform operations on the symbolic link by converting the "
6988 "handle to a file descriptor using B<open_by_handle_at>() with the B<O_PATH> "
6989 "flag, and then passing the file descriptor as the I<dirfd> argument in "
6990 "system calls such as B<readlinkat>(2) and B<fchownat>(2)."
6994 #: build/C/man2/open_by_handle_at.2:409
6996 msgid "Obtaining a persistent filesystem ID"
7000 #: build/C/man2/open_by_handle_at.2:423
7002 "The mount IDs in I</proc/self/mountinfo> can be reused as filesystems are "
7003 "unmounted and mounted. Therefore, the mount ID returned by "
7004 "B<name_to_handle_at>() (in I<*mount_id>) should not be treated as a "
7005 "persistent identifier for the corresponding mounted filesystem. However, an "
7006 "application can use the information in the I<mountinfo> record that "
7007 "corresponds to the mount ID to derive a persistent identifier."
7010 #. e.g., http://stackoverflow.com/questions/6748429/using-libblkid-to-find-uuid-of-a-partition
7012 #: build/C/man2/open_by_handle_at.2:439
7014 "For example, one can use the device name in the fifth field of the "
7015 "I<mountinfo> record to search for the corresponding device UUID via the "
7016 "symbolic links in I</dev/disks/by-uuid>. (A more comfortable way of "
7017 "obtaining the UUID is to use the B<libblkid>(3) library.) That process can "
7018 "then be reversed, using the UUID to look up the device name, and then "
7019 "obtaining the corresponding mount point, in order to produce the I<mount_fd> "
7020 "argument used by B<open_by_handle_at>()."
7024 #: build/C/man2/open_by_handle_at.2:451
7026 "The two programs below demonstrate the use of B<name_to_handle_at>() and "
7027 "B<open_by_handle_at>(). The first program (I<t_name_to_handle_at.c>) uses "
7028 "B<name_to_handle_at>() to obtain the file handle and mount ID for the file "
7029 "specified in its command-line argument; the handle and mount ID are written "
7030 "to standard output."
7034 #: build/C/man2/open_by_handle_at.2:471
7036 "The second program (I<t_open_by_handle_at.c>) reads a mount ID and file "
7037 "handle from standard input. The program then employs B<open_by_handle_at>() "
7038 "to open the file using that handle. If an optional command-line argument is "
7039 "supplied, then the I<mount_fd> argument for B<open_by_handle_at>() is "
7040 "obtained by opening the directory named in that argument. Otherwise, "
7041 "I<mount_fd> is obtained by scanning I</proc/self/mountinfo> to find a record "
7042 "whose mount ID matches the mount ID read from standard input, and the mount "
7043 "directory specified in that record is opened. (These programs do not deal "
7044 "with the fact that mount IDs are not persistent.)"
7048 #: build/C/man2/open_by_handle_at.2:473
7049 msgid "The following shell session demonstrates the use of these two programs:"
7053 #: build/C/man2/open_by_handle_at.2:483
7056 "$ B<echo 'Can you please think about it?' E<gt> cecilia.txt>\n"
7057 "$ B<./t_name_to_handle_at cecilia.txt E<gt> fh>\n"
7058 "$ B<./t_open_by_handle_at E<lt> fh>\n"
7059 "open_by_handle_at: Operation not permitted\n"
7060 "$ B<sudo ./t_open_by_handle_at E<lt> fh> # Need CAP_SYS_ADMIN\n"
7062 "$ B<rm cecilia.txt>\n"
7065 #. Christoph Hellwig: That's why the file handles contain a generation
7066 #. counter that gets incremented in this case.
7068 #: build/C/man2/open_by_handle_at.2:494
7070 "Now we delete and (quickly) re-create the file so that it has the same "
7071 "content and (by chance) the same inode. Nevertheless, "
7072 "B<open_by_handle_at>() recognizes that the original file referred to by the "
7073 "file handle no longer exists."
7077 #: build/C/man2/open_by_handle_at.2:505
7080 "$ B<stat --printf=\"%i\\en\" cecilia.txt> # Display inode number\n"
7082 "$ B<rm cecilia.txt>\n"
7083 "$ B<echo 'Can you please think about it?' E<gt> cecilia.txt>\n"
7084 "$ B<stat --printf=\"%i\\en\" cecilia.txt> # Check inode number\n"
7086 "$ B<sudo ./t_open_by_handle_at E<lt> fh>\n"
7087 "open_by_handle_at: Stale NFS file handle\n"
7091 #: build/C/man2/open_by_handle_at.2:507
7093 msgid "Program source: t_name_to_handle_at.c"
7097 #: build/C/man2/open_by_handle_at.2:519
7100 "#define _GNU_SOURCE\n"
7101 "#include E<lt>sys/types.hE<gt>\n"
7102 "#include E<lt>sys/stat.hE<gt>\n"
7103 "#include E<lt>fcntl.hE<gt>\n"
7104 "#include E<lt>stdio.hE<gt>\n"
7105 "#include E<lt>stdlib.hE<gt>\n"
7106 "#include E<lt>unistd.hE<gt>\n"
7107 "#include E<lt>errno.hE<gt>\n"
7108 "#include E<lt>string.hE<gt>\n"
7112 #: build/C/man2/open_by_handle_at.2:522 build/C/man2/open_by_handle_at.2:595
7115 "#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\e\n"
7120 #: build/C/man2/open_by_handle_at.2:529
7124 "main(int argc, char *argv[])\n"
7126 " struct file_handle *fhp;\n"
7127 " int mount_id, fhsize, flags, dirfd, j;\n"
7128 " char *pathname;\n"
7132 #: build/C/man2/open_by_handle_at.2:534
7135 " if (argc != 2) {\n"
7136 " fprintf(stderr, \"Usage: %s pathname\\en\", argv[0]);\n"
7137 " exit(EXIT_FAILURE);\n"
7142 #: build/C/man2/open_by_handle_at.2:536
7144 msgid " pathname = argv[1];\n"
7148 #: build/C/man2/open_by_handle_at.2:538
7150 msgid " /* Allocate file_handle structure */\n"
7154 #: build/C/man2/open_by_handle_at.2:543
7157 " fhsize = sizeof(*fhp);\n"
7158 " fhp = malloc(fhsize);\n"
7159 " if (fhp == NULL)\n"
7160 " errExit(\"malloc\");\n"
7164 #: build/C/man2/open_by_handle_at.2:546
7167 " /* Make an initial call to name_to_handle_at() to discover\n"
7168 " the size required for file handle */\n"
7172 #: build/C/man2/open_by_handle_at.2:555
7175 " dirfd = AT_FDCWD; /* For name_to_handle_at() calls */\n"
7176 " flags = 0; /* For name_to_handle_at() calls */\n"
7177 " fhp-E<gt>handle_bytes = 0;\n"
7178 " if (name_to_handle_at(dirfd, pathname, fhp,\n"
7179 " &mount_id, flags) != -1 || errno != EOVERFLOW) {\n"
7180 " fprintf(stderr, \"Unexpected result from "
7181 "name_to_handle_at()\\en\");\n"
7182 " exit(EXIT_FAILURE);\n"
7187 #: build/C/man2/open_by_handle_at.2:557
7189 msgid " /* Reallocate file_handle structure with correct size */\n"
7193 #: build/C/man2/open_by_handle_at.2:562
7196 " fhsize = sizeof(struct file_handle) + fhp-E<gt>handle_bytes;\n"
7197 " fhp = realloc(fhp, fhsize); /* Copies fhp-E<gt>handle_bytes */\n"
7198 " if (fhp == NULL)\n"
7199 " errExit(\"realloc\");\n"
7203 #: build/C/man2/open_by_handle_at.2:564
7205 msgid " /* Get file handle from pathname supplied on command line */\n"
7209 #: build/C/man2/open_by_handle_at.2:567
7212 " if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1)\n"
7213 " errExit(\"name_to_handle_at\");\n"
7217 #: build/C/man2/open_by_handle_at.2:570
7220 " /* Write mount ID, file handle size, and file handle to stdout,\n"
7221 " for later reuse by t_open_by_handle_at.c */\n"
7225 #: build/C/man2/open_by_handle_at.2:576
7228 " printf(\"%d\\en\", mount_id);\n"
7229 " printf(\"%d %d \", fhp-E<gt>handle_bytes, fhp-E<gt>handle_type);\n"
7230 " for (j = 0; j E<lt> fhp-E<gt>handle_bytes; j++)\n"
7231 " printf(\" %02x\", fhp-E<gt>f_handle[j]);\n"
7232 " printf(\"\\en\");\n"
7236 #: build/C/man2/open_by_handle_at.2:580
7238 msgid "Program source: t_open_by_handle_at.c"
7242 #: build/C/man2/open_by_handle_at.2:592
7245 "#define _GNU_SOURCE\n"
7246 "#include E<lt>sys/types.hE<gt>\n"
7247 "#include E<lt>sys/stat.hE<gt>\n"
7248 "#include E<lt>fcntl.hE<gt>\n"
7249 "#include E<lt>limits.hE<gt>\n"
7250 "#include E<lt>stdio.hE<gt>\n"
7251 "#include E<lt>stdlib.hE<gt>\n"
7252 "#include E<lt>unistd.hE<gt>\n"
7253 "#include E<lt>string.hE<gt>\n"
7257 #: build/C/man2/open_by_handle_at.2:601
7260 "/* Scan /proc/self/mountinfo to find the line whose mount ID matches\n"
7261 " \\(aqmount_id\\(aq. (An easier way to do this is to install and use the\n"
7262 " \\(aqlibmount\\(aq library provided by the \\(aqutil-linux\\(aq "
7264 " Open the corresponding mount path and return the resulting file\n"
7269 #: build/C/man2/open_by_handle_at.2:611
7273 "open_mount_path_by_id(int mount_id)\n"
7277 " char mount_path[PATH_MAX];\n"
7278 " int mi_mount_id, found;\n"
7284 #: build/C/man2/open_by_handle_at.2:615
7287 " fp = fopen(\"/proc/self/mountinfo\", \"r\");\n"
7288 " if (fp == NULL)\n"
7289 " errExit(\"fopen\");\n"
7293 #: build/C/man2/open_by_handle_at.2:622
7298 " while (!found) {\n"
7299 " nread = getline(&linep, &lsize, fp);\n"
7300 " if (nread == -1)\n"
7305 #: build/C/man2/open_by_handle_at.2:629
7308 " nread = sscanf(linep, \"%d %*d %*s %*s %s\",\n"
7309 " &mi_mount_id, mount_path);\n"
7310 " if (nread != 2) {\n"
7311 " fprintf(stderr, \"Bad sscanf()\\en\");\n"
7312 " exit(EXIT_FAILURE);\n"
7317 #: build/C/man2/open_by_handle_at.2:634
7320 " if (mi_mount_id == mount_id)\n"
7327 #: build/C/man2/open_by_handle_at.2:636
7329 msgid " fclose(fp);\n"
7333 #: build/C/man2/open_by_handle_at.2:641
7337 " fprintf(stderr, \"Could not find mount point\\en\");\n"
7338 " exit(EXIT_FAILURE);\n"
7343 #: build/C/man2/open_by_handle_at.2:644
7346 " return open(mount_path, O_RDONLY);\n"
7351 #: build/C/man2/open_by_handle_at.2:655
7355 "main(int argc, char *argv[])\n"
7357 " struct file_handle *fhp;\n"
7358 " int mount_id, fd, mount_fd, handle_bytes, j;\n"
7360 " char buf[1000];\n"
7361 "#define LINE_SIZE 100\n"
7362 " char line1[LINE_SIZE], line2[LINE_SIZE];\n"
7367 #: build/C/man2/open_by_handle_at.2:660
7370 " if ((argc E<gt> 1 && strcmp(argv[1], \"--help\") == 0) || argc E<gt> 2) "
7372 " fprintf(stderr, \"Usage: %s [mount-path]\\en\", argv[0]);\n"
7373 " exit(EXIT_FAILURE);\n"
7378 #: build/C/man2/open_by_handle_at.2:662
7380 msgid " /* Standard input contains mount ID and file handle information:\n"
7384 #: build/C/man2/open_by_handle_at.2:666
7387 " Line 1: E<lt>mount_idE<gt>\n"
7388 " Line 2: E<lt>handle_bytesE<gt> E<lt>handle_typeE<gt> E<lt>bytes "
7389 "of handle in hexE<gt>\n"
7394 #: build/C/man2/open_by_handle_at.2:672
7397 " if ((fgets(line1, sizeof(line1), stdin) == NULL) ||\n"
7398 " (fgets(line2, sizeof(line2), stdin) == NULL)) {\n"
7399 " fprintf(stderr, \"Missing mount_id / file handle\\en\");\n"
7400 " exit(EXIT_FAILURE);\n"
7405 #: build/C/man2/open_by_handle_at.2:674
7407 msgid " mount_id = atoi(line1);\n"
7411 #: build/C/man2/open_by_handle_at.2:676
7413 msgid " handle_bytes = strtoul(line2, &nextp, 0);\n"
7417 #: build/C/man2/open_by_handle_at.2:678
7419 msgid " /* Given handle_bytes, we can now allocate file_handle structure */\n"
7423 #: build/C/man2/open_by_handle_at.2:682
7426 " fhp = malloc(sizeof(struct file_handle) + handle_bytes);\n"
7427 " if (fhp == NULL)\n"
7428 " errExit(\"malloc\");\n"
7432 #: build/C/man2/open_by_handle_at.2:684
7434 msgid " fhp-E<gt>handle_bytes = handle_bytes;\n"
7438 #: build/C/man2/open_by_handle_at.2:686
7440 msgid " fhp-E<gt>handle_type = strtoul(nextp, &nextp, 0);\n"
7444 #: build/C/man2/open_by_handle_at.2:689
7447 " for (j = 0; j E<lt> fhp-E<gt>handle_bytes; j++)\n"
7448 " fhp-E<gt>f_handle[j] = strtoul(nextp, &nextp, 16);\n"
7452 #: build/C/man2/open_by_handle_at.2:694
7455 " /* Obtain file descriptor for mount point, either by opening\n"
7456 " the pathname specified on the command line, or by scanning\n"
7457 " /proc/self/mounts to find a mount that matches the "
7458 "\\(aqmount_id\\(aq\n"
7459 " that we received from stdin. */\n"
7463 #: build/C/man2/open_by_handle_at.2:699
7466 " if (argc E<gt> 1)\n"
7467 " mount_fd = open(argv[1], O_RDONLY);\n"
7469 " mount_fd = open_mount_path_by_id(mount_id);\n"
7473 #: build/C/man2/open_by_handle_at.2:702
7476 " if (mount_fd == -1)\n"
7477 " errExit(\"opening mount fd\");\n"
7481 #: build/C/man2/open_by_handle_at.2:704
7483 msgid " /* Open file using handle and mount point */\n"
7487 #: build/C/man2/open_by_handle_at.2:708
7490 " fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);\n"
7492 " errExit(\"open_by_handle_at\");\n"
7496 #: build/C/man2/open_by_handle_at.2:710
7498 msgid " /* Try reading a few bytes from the file */\n"
7502 #: build/C/man2/open_by_handle_at.2:714
7505 " nread = read(fd, buf, sizeof(buf));\n"
7506 " if (nread == -1)\n"
7507 " errExit(\"read\");\n"
7511 #: build/C/man2/open_by_handle_at.2:716
7513 msgid " printf(\"Read %zd bytes\\en\", nread);\n"
7517 #: build/C/man2/open_by_handle_at.2:726
7518 msgid "B<open>(2), B<libblkid>(3), B<blkid>(8), B<findfs>(8), B<mount>(8)"
7522 #: build/C/man2/open_by_handle_at.2:736
7524 "The I<libblkid> and I<libmount> documentation in the latest I<util-linux> "
7525 "release at E<.UR https://www.kernel.org/pub/linux/utils/util-linux/> E<.UE>"
7529 #: build/C/man3/perror.3:31
7535 #: build/C/man3/perror.3:34
7536 msgid "perror - print a system error message"
7540 #: build/C/man3/perror.3:38
7541 msgid "B<void perror(const char *>I<s>B<);>"
7545 #: build/C/man3/perror.3:40
7546 msgid "B<#include E<lt>errno.hE<gt>>"
7550 #: build/C/man3/perror.3:42
7551 msgid "B<const char * const >I<sys_errlist>B<[];>"
7555 #: build/C/man3/perror.3:44
7556 msgid "B<int >I<sys_nerr>B<;>"
7560 #: build/C/man3/perror.3:46
7561 msgid "B<int >I<errno>B<; /* Not really declared this way; see errno(3). */>"
7565 #: build/C/man3/perror.3:55
7566 msgid "I<sys_errlist>, I<sys_nerr>: _BSD_SOURCE"
7570 #: build/C/man3/perror.3:68
7572 "The routine B<perror>() produces a message on the standard error output, "
7573 "describing the last error encountered during a call to a system or library "
7574 "function. First (if I<s> is not NULL and I<*s> is not a null byte "
7575 "(\\(aq\\e0\\(aq)) the argument string I<s> is printed, followed by a colon "
7576 "and a blank. Then the message and a new-line."
7580 #: build/C/man3/perror.3:76
7582 "To be of most use, the argument string should include the name of the "
7583 "function that incurred the error. The error number is taken from the "
7584 "external variable I<errno>, which is set when errors occur but not cleared "
7585 "when successful calls are made."
7589 #: build/C/man3/perror.3:90
7591 "The global error list I<sys_errlist>[] indexed by I<errno> can be used to "
7592 "obtain the error message without the newline. The largest message number "
7593 "provided in the table is I<sys_nerr>-1. Be careful when directly accessing "
7594 "this list because new error values may not have been added to "
7595 "I<sys_errlist>[]. The use of I<sys_errlist>[] is nowadays deprecated."
7599 #: build/C/man3/perror.3:111
7601 "When a system call fails, it usually returns -1 and sets the variable "
7602 "I<errno> to a value describing what went wrong. (These values can be found "
7603 "in I<E<lt>errno.hE<gt>>.) Many library functions do likewise. The function "
7604 "B<perror>() serves to translate this error code into human-readable form. "
7605 "Note that I<errno> is undefined after a successful library call: this call "
7606 "may well change this variable, even though it succeeds, for example because "
7607 "it internally used some other library function that failed. Thus, if a "
7608 "failing call is not immediately followed by a call to B<perror>(), the value "
7609 "of I<errno> should be saved."
7613 #: build/C/man3/perror.3:124
7615 "The function B<perror>() and the external I<errno> (see B<errno>(3)) "
7616 "conform to C89, C99, 4.3BSD, POSIX.1-2001. The externals I<sys_nerr> and "
7617 "I<sys_errlist> conform to BSD."
7620 #. and only when _BSD_SOURCE is defined.
7623 #. is defined, the symbols
7629 #: build/C/man3/perror.3:139
7631 "The externals I<sys_nerr> and I<sys_errlist> are defined by glibc, but in "
7632 "I<E<lt>stdio.hE<gt>>."
7636 #: build/C/man3/perror.3:144
7637 msgid "B<err>(3), B<errno>(3), B<error>(3), B<strerror>(3)"
7641 #: build/C/man2/pipe.2:36
7647 #: build/C/man2/pipe.2:36 build/C/man3/printf.3:34
7653 #: build/C/man2/pipe.2:39
7654 msgid "pipe, pipe2 - create pipe"
7658 #: build/C/man2/pipe.2:44
7660 msgid "B<int pipe(int >I<pipefd>B<[2]);>\n"
7664 #: build/C/man2/pipe.2:48
7667 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
7668 "B<#include E<lt>fcntl.hE<gt>> /* Obtain O_* constant "
7670 "B<#include E<lt>unistd.hE<gt>>\n"
7674 #: build/C/man2/pipe.2:50
7676 msgid "B<int pipe2(int >I<pipefd>B<[2], int >I<flags>B<);>\n"
7680 #: build/C/man2/pipe.2:66
7682 "B<pipe>() creates a pipe, a unidirectional data channel that can be used "
7683 "for interprocess communication. The array I<pipefd> is used to return two "
7684 "file descriptors referring to the ends of the pipe. I<pipefd[0]> refers to "
7685 "the read end of the pipe. I<pipefd[1]> refers to the write end of the "
7686 "pipe. Data written to the write end of the pipe is buffered by the kernel "
7687 "until it is read from the read end of the pipe. For further details, see "
7692 #: build/C/man2/pipe.2:76
7694 "If I<flags> is 0, then B<pipe2>() is the same as B<pipe>(). The following "
7695 "values can be bitwise ORed in I<flags> to obtain different behavior:"
7699 #: build/C/man2/pipe.2:76
7701 msgid "B<O_CLOEXEC>"
7705 #: build/C/man2/pipe.2:84
7707 "Set the close-on-exec (B<FD_CLOEXEC>) flag on the two new file "
7708 "descriptors. See the description of the same flag in B<open>(2) for "
7709 "reasons why this may be useful."
7713 #: build/C/man2/pipe.2:84
7715 msgid "B<O_DIRECT> (since Linux 3.4)"
7718 #. commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d
7720 #: build/C/man2/pipe.2:94
7722 "Create a pipe that performs I/O in \"packet\" mode. Each B<write>(2) to "
7723 "the pipe is dealt with as a separate packet, and B<read>(2)s from the pipe "
7724 "will read one packet at a time. Note the following points:"
7728 #: build/C/man2/pipe.2:105
7730 "Writes of greater than B<PIPE_BUF> bytes (see B<pipe>(7)) will be split "
7731 "into multiple packets. The constant B<PIPE_BUF> is defined in "
7732 "I<E<lt>limits.hE<gt>>."
7736 #: build/C/man2/pipe.2:115
7738 "If a B<read>(2) specifies a buffer size that is smaller than the next "
7739 "packet, then the requested number of bytes are read, and the excess bytes in "
7740 "the packet are discarded. Specifying a buffer size of B<PIPE_BUF> will be "
7741 "sufficient to read the largest possible packets (see the previous point)."
7745 #: build/C/man2/pipe.2:120
7747 "Zero-length packets are not supported. (A B<read>(2) that specifies a "
7748 "buffer size of zero is a no-op, and returns 0.)"
7752 #: build/C/man2/pipe.2:125
7754 "Older kernels that do not support this flag will indicate this via an "
7759 #: build/C/man2/pipe.2:125
7761 msgid "B<O_NONBLOCK>"
7765 #: build/C/man2/pipe.2:133
7767 "Set the B<O_NONBLOCK> file status flag on the two new open file "
7768 "descriptions. Using this flag saves extra calls to B<fcntl>(2) to achieve "
7773 #: build/C/man2/pipe.2:143
7774 msgid "I<pipefd> is not valid."
7778 #: build/C/man2/pipe.2:148
7779 msgid "(B<pipe2>()) Invalid value in I<flags>."
7783 #: build/C/man2/pipe.2:151
7784 msgid "Too many file descriptors are in use by the process."
7788 #: build/C/man2/pipe.2:159
7790 "B<pipe2>() was added to Linux in version 2.6.27; glibc support is available "
7791 "starting with version 2.9."
7795 #: build/C/man2/pipe.2:162
7796 msgid "B<pipe>(): POSIX.1-2001."
7800 #: build/C/man2/pipe.2:165
7801 msgid "B<pipe2>() is Linux-specific."
7804 #. fork.2 refers to this example program.
7806 #: build/C/man2/pipe.2:181
7808 "The following program creates a pipe, and then B<fork>(2)s to create a child "
7809 "process; the child inherits a duplicate set of file descriptors that refer "
7810 "to the same pipe. After the B<fork>(2), each process closes the descriptors "
7811 "that it doesn't need for the pipe (see B<pipe>(7)). The parent then writes "
7812 "the string contained in the program's command-line argument to the pipe, and "
7813 "the child reads this string a byte at a time from the pipe and echoes it on "
7818 #: build/C/man2/pipe.2:189
7821 "#include E<lt>sys/types.hE<gt>\n"
7822 "#include E<lt>sys/wait.hE<gt>\n"
7823 "#include E<lt>stdio.hE<gt>\n"
7824 "#include E<lt>stdlib.hE<gt>\n"
7825 "#include E<lt>unistd.hE<gt>\n"
7826 "#include E<lt>string.hE<gt>\n"
7830 #: build/C/man2/pipe.2:196
7834 "main(int argc, char *argv[])\n"
7842 #: build/C/man2/pipe.2:201
7845 " if (argc != 2) {\n"
7846 " fprintf(stderr, \"Usage: %s E<lt>stringE<gt>\\en\", argv[0]);\n"
7847 " exit(EXIT_FAILURE);\n"
7852 #: build/C/man2/pipe.2:206
7855 " if (pipe(pipefd) == -1) {\n"
7856 " perror(\"pipe\");\n"
7857 " exit(EXIT_FAILURE);\n"
7862 #: build/C/man2/pipe.2:212
7866 " if (cpid == -1) {\n"
7867 " perror(\"fork\");\n"
7868 " exit(EXIT_FAILURE);\n"
7873 #: build/C/man2/pipe.2:215
7876 " if (cpid == 0) { /* Child reads from pipe */\n"
7877 " close(pipefd[1]); /* Close unused write end */\n"
7881 #: build/C/man2/pipe.2:218
7884 " while (read(pipefd[0], &buf, 1) E<gt> 0)\n"
7885 " write(STDOUT_FILENO, &buf, 1);\n"
7889 #: build/C/man2/pipe.2:222
7892 " write(STDOUT_FILENO, \"\\en\", 1);\n"
7893 " close(pipefd[0]);\n"
7894 " _exit(EXIT_SUCCESS);\n"
7898 #: build/C/man2/pipe.2:231
7901 " } else { /* Parent writes argv[1] to pipe */\n"
7902 " close(pipefd[0]); /* Close unused read end */\n"
7903 " write(pipefd[1], argv[1], strlen(argv[1]));\n"
7904 " close(pipefd[1]); /* Reader will see EOF */\n"
7905 " wait(NULL); /* Wait for child */\n"
7906 " exit(EXIT_SUCCESS);\n"
7912 #: build/C/man2/pipe.2:239
7914 "B<fork>(2), B<read>(2), B<socketpair>(2), B<write>(2), B<popen>(3), "
7919 #: build/C/man3/popen.3:40
7925 #: build/C/man3/popen.3:43
7926 msgid "popen, pclose - pipe stream to or from a process"
7930 #: build/C/man3/popen.3:48
7932 msgid "B<FILE *popen(const char *>I<command>B<, const char *>I<type>B<);>\n"
7936 #: build/C/man3/popen.3:50
7938 msgid "B<int pclose(FILE *>I<stream>B<);>\n"
7942 #: build/C/man3/popen.3:60
7943 msgid "B<popen>(), B<pclose>():"
7947 #: build/C/man3/popen.3:62
7948 msgid "_POSIX_C_SOURCE\\ E<gt>=\\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE"
7952 #: build/C/man3/popen.3:73
7954 "The B<popen>() function opens a process by creating a pipe, forking, and "
7955 "invoking the shell. Since a pipe is by definition unidirectional, the "
7956 "I<type> argument may specify only reading or writing, not both; the "
7957 "resulting stream is correspondingly read-only or write-only."
7961 #: build/C/man3/popen.3:97
7963 "The I<command> argument is a pointer to a null-terminated string containing "
7964 "a shell command line. This command is passed to I</bin/sh> using the B<-c> "
7965 "flag; interpretation, if any, is performed by the shell. The I<type> "
7966 "argument is a pointer to a null-terminated string which must contain either "
7967 "the letter \\(aqr\\(aq for reading or the letter \\(aqw\\(aq for writing. "
7968 "Since glibc 2.9, this argument can additionally include the letter "
7969 "\\(aqe\\(aq, which causes the close-on-exec flag (B<FD_CLOEXEC>) to be set "
7970 "on the underlying file descriptor; see the description of the B<O_CLOEXEC> "
7971 "flag in B<open>(2) for reasons why this may be useful."
7975 #: build/C/man3/popen.3:113
7977 "The return value from B<popen>() is a normal standard I/O stream in all "
7978 "respects save that it must be closed with B<pclose>() rather than "
7979 "B<fclose>(3). Writing to such a stream writes to the standard input of the "
7980 "command; the command's standard output is the same as that of the process "
7981 "that called B<popen>(), unless this is altered by the command itself. "
7982 "Conversely, reading from the stream reads the command's standard output, and "
7983 "the command's standard input is the same as that of the process that called "
7988 #: build/C/man3/popen.3:117
7989 msgid "Note that output B<popen>() streams are fully buffered by default."
7993 #: build/C/man3/popen.3:123
7995 "The B<pclose>() function waits for the associated process to terminate and "
7996 "returns the exit status of the command as returned by B<wait4>(2)."
8000 #: build/C/man3/popen.3:131
8002 "The B<popen>() function returns NULL if the B<fork>(2) or B<pipe>(2) "
8003 "calls fail, or if it cannot allocate memory."
8006 #. These conditions actually give undefined results, so I commented
8009 #. is not associated with a "popen()ed" command, if
8011 #. already "pclose()d", or if
8013 #: build/C/man3/popen.3:146
8015 "The B<pclose>() function returns -1 if B<wait4>(2) returns an error, or "
8016 "some other error is detected. In the event of an error, these functions set "
8017 "I<errno> to indicate the cause of the error."
8021 #: build/C/man3/popen.3:165
8023 "The B<popen>() function does not set I<errno> if memory allocation fails. "
8024 "If the underlying B<fork>(2) or B<pipe>(2) fails, I<errno> is set "
8025 "appropriately. If the I<type> argument is invalid, and this condition is "
8026 "detected, I<errno> is set to B<EINVAL>."
8030 #: build/C/man3/popen.3:172
8032 "If B<pclose>() cannot obtain the child status, I<errno> is set to "
8037 #: build/C/man3/popen.3:178
8038 msgid "The \\(aqe\\(aq value for I<type> is a Linux extension."
8042 #: build/C/man3/popen.3:191
8044 "Since the standard input of a command opened for reading shares its seek "
8045 "offset with the process that called B<popen>(), if the original process has "
8046 "done a buffered read, the command's input position may not be as expected. "
8047 "Similarly, the output from a command opened for writing may become "
8048 "intermingled with that of the original process. The latter can be avoided "
8049 "by calling B<fflush>(3) before B<popen>()."
8057 #. function appeared in Version 7 AT&T UNIX.
8059 #: build/C/man3/popen.3:201
8061 "Failure to execute the shell is indistinguishable from the shell's failure "
8062 "to execute command, or an immediate exit of the command. The only hint is "
8063 "an exit status of 127."
8067 #: build/C/man3/popen.3:211
8069 "B<sh>(1), B<fork>(2), B<pipe>(2), B<wait4>(2), B<fclose>(3), B<fflush>(3), "
8070 "B<fopen>(3), B<stdio>(3), B<system>(3)"
8074 #: build/C/man3/printf.3:34
8080 #: build/C/man3/printf.3:38
8082 "printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - "
8083 "formatted output conversion"
8087 #: build/C/man3/printf.3:42
8088 msgid "B<int printf(const char *>I<format>B<, ...);>"
8092 #: build/C/man3/printf.3:44
8093 msgid "B<int fprintf(FILE *>I<stream>B<, const char *>I<format>B<, ...);>"
8097 #: build/C/man3/printf.3:46
8098 msgid "B<int sprintf(char *>I<str>B<, const char *>I<format>B<, ...);>"
8102 #: build/C/man3/printf.3:48
8104 "B<int snprintf(char *>I<str>B<, size_t >I<size>B<, const char *>I<format>B<, "
8109 #: build/C/man3/printf.3:50
8110 msgid "B<#include E<lt>stdarg.hE<gt>>"
8114 #: build/C/man3/printf.3:52
8115 msgid "B<int vprintf(const char *>I<format>B<, va_list >I<ap>B<);>"
8119 #: build/C/man3/printf.3:54
8121 "B<int vfprintf(FILE *>I<stream>B<, const char *>I<format>B<, va_list "
8126 #: build/C/man3/printf.3:56
8128 "B<int vsprintf(char *>I<str>B<, const char *>I<format>B<, va_list "
8133 #: build/C/man3/printf.3:59
8135 "B<int vsnprintf(char *>I<str>B<, size_t >I<size>B<, const char "
8136 "*>I<format>B<, va_list >I<ap>B<);>"
8140 #: build/C/man3/printf.3:68
8141 msgid "B<snprintf>(), B<vsnprintf>():"
8145 #: build/C/man3/printf.3:71
8147 "_BSD_SOURCE || _XOPEN_SOURCE\\ E<gt>=\\ 500 || _ISOC99_SOURCE || "
8148 "_POSIX_C_SOURCE\\ E<gt>=\\ 200112L;"
8152 #: build/C/man3/printf.3:74 build/C/man3/scanf.3:85
8153 msgid "or I<cc -std=c99>"
8157 #: build/C/man3/printf.3:101
8159 "The functions in the B<printf>() family produce output according to a "
8160 "I<format> as described below. The functions B<printf>() and B<vprintf>() "
8161 "write output to I<stdout>, the standard output stream; B<fprintf>() and "
8162 "B<vfprintf>() write output to the given output I<stream>; B<sprintf>(), "
8163 "B<snprintf>(), B<vsprintf>() and B<vsnprintf>() write to the character "
8168 #: build/C/man3/printf.3:110
8170 "The functions B<snprintf>() and B<vsnprintf>() write at most I<size> bytes "
8171 "(including the terminating null byte (\\(aq\\e0\\(aq)) to I<str>."
8175 #: build/C/man3/printf.3:134
8177 "The functions B<vprintf>(), B<vfprintf>(), B<vsprintf>(), B<vsnprintf>() "
8178 "are equivalent to the functions B<printf>(), B<fprintf>(), B<sprintf>(), "
8179 "B<snprintf>(), respectively, except that they are called with a I<va_list> "
8180 "instead of a variable number of arguments. These functions do not call the "
8181 "I<va_end> macro. Because they invoke the I<va_arg> macro, the value of "
8182 "I<ap> is undefined after the call. See B<stdarg>(3)."
8186 #: build/C/man3/printf.3:141
8188 "These eight functions write the output under the control of a I<format> "
8189 "string that specifies how subsequent arguments (or arguments accessed via "
8190 "the variable-length argument facilities of B<stdarg>(3)) are converted for "
8195 #: build/C/man3/printf.3:152
8197 "C99 and POSIX.1-2001 specify that the results are undefined if a call to "
8198 "B<sprintf>(), B<snprintf>(), B<vsprintf>(), or B<vsnprintf>() would cause "
8199 "copying to take place between objects that overlap (e.g., if the target "
8200 "string array and one of the supplied input arguments refer to the same "
8201 "buffer). See NOTES."
8205 #: build/C/man3/printf.3:152
8207 msgid "Return value"
8211 #: build/C/man3/printf.3:155
8213 "Upon successful return, these functions return the number of characters "
8214 "printed (excluding the null byte used to end output to strings)."
8218 #: build/C/man3/printf.3:171
8220 "The functions B<snprintf>() and B<vsnprintf>() do not write more than "
8221 "I<size> bytes (including the terminating null byte (\\(aq\\e0\\(aq)). If "
8222 "the output was truncated due to this limit, then the return value is the "
8223 "number of characters (excluding the terminating null byte) which would have "
8224 "been written to the final string if enough space had been available. Thus, "
8225 "a return value of I<size> or more means that the output was truncated. (See "
8226 "also below under NOTES.)"
8230 #: build/C/man3/printf.3:173
8231 msgid "If an output error is encountered, a negative value is returned."
8235 #: build/C/man3/printf.3:173
8237 msgid "Format of the format string"
8241 #: build/C/man3/printf.3:195
8243 "The format string is a character string, beginning and ending in its initial "
8244 "shift state, if any. The format string is composed of zero or more "
8245 "directives: ordinary characters (not B<%>), which are copied unchanged to "
8246 "the output stream; and conversion specifications, each of which results in "
8247 "fetching zero or more subsequent arguments. Each conversion specification "
8248 "is introduced by the character B<%>, and ends with a I<conversion "
8249 "specifier>. In between there may be (in this order) zero or more I<flags>, "
8250 "an optional minimum I<field width>, an optional I<precision> and an optional "
8251 "I<length modifier>."
8255 #: build/C/man3/printf.3:208
8257 "The arguments must correspond properly (after type promotion) with the "
8258 "conversion specifier. By default, the arguments are used in the order "
8259 "given, where each \\(aq*\\(aq and each conversion specifier asks for the "
8260 "next argument (and it is an error if insufficiently many arguments are "
8261 "given). One can also specify explicitly which argument is taken, at each "
8262 "place where an argument is required, by writing \"%m$\" instead of "
8263 "\\(aq%\\(aq and \"*m$\" instead of \\(aq*\\(aq, where the decimal integer m "
8264 "denotes the position in the argument list of the desired argument, indexed "
8265 "starting from 1. Thus,"
8269 #: build/C/man3/printf.3:212
8271 msgid "printf(\"%*d\", width, num);\n"
8275 #: build/C/man3/printf.3:216
8280 #: build/C/man3/printf.3:220
8282 msgid "printf(\"%2$*1$d\", width, num);\n"
8286 #: build/C/man3/printf.3:236
8288 "are equivalent. The second style allows repeated references to the same "
8289 "argument. The C99 standard does not include the style using \\(aq$\\(aq, "
8290 "which comes from the Single UNIX Specification. If the style using "
8291 "\\(aq$\\(aq is used, it must be used throughout for all conversions taking "
8292 "an argument and all width and precision arguments, but it may be mixed with "
8293 "\"%%\" formats which do not consume an argument. There may be no gaps in "
8294 "the numbers of arguments specified using \\(aq$\\(aq; for example, if "
8295 "arguments 1 and 3 are specified, argument 2 must also be specified somewhere "
8296 "in the format string."
8300 #: build/C/man3/printf.3:246
8302 "For some numeric conversions a radix character (\"decimal point\") or "
8303 "thousands' grouping character is used. The actual character used depends on "
8304 "the B<LC_NUMERIC> part of the locale. The POSIX locale uses \\(aq.\\(aq as "
8305 "radix character, and does not have a grouping character. Thus,"
8309 #: build/C/man3/printf.3:250
8311 msgid " printf(\"%\\(aq.2f\", 1234567.89);\n"
8315 #: build/C/man3/printf.3:255
8317 "results in \"1234567.89\" in the POSIX locale, in \"1234567,89\" in the "
8318 "nl_NL locale, and in \"1.234.567,89\" in the da_DK locale."
8322 #: build/C/man3/printf.3:255
8324 msgid "The flag characters"
8328 #: build/C/man3/printf.3:257
8329 msgid "The character % is followed by zero or more of the following flags:"
8333 #: build/C/man3/printf.3:257
8339 #: build/C/man3/printf.3:291
8341 "The value should be converted to an \"alternate form\". For B<o> "
8342 "conversions, the first character of the output string is made zero (by "
8343 "prefixing a 0 if it was not zero already). For B<x> and B<X> conversions, a "
8344 "nonzero result has the string \"0x\" (or \"0X\" for B<X> conversions) "
8345 "prepended to it. For B<a>, B<A>, B<e>, B<E>, B<f>, B<F>, B<g>, and B<G> "
8346 "conversions, the result will always contain a decimal point, even if no "
8347 "digits follow it (normally, a decimal point appears in the results of those "
8348 "conversions only if a digit follows). For B<g> and B<G> conversions, "
8349 "trailing zeros are not removed from the result as they would otherwise be. "
8350 "For other conversions, the result is undefined."
8354 #: build/C/man3/printf.3:291
8360 #: build/C/man3/printf.3:331
8362 "The value should be zero padded. For B<d>, B<i>, B<o>, B<u>, B<x>, B<X>, "
8363 "B<a>, B<A>, B<e>, B<E>, B<f>, B<F>, B<g>, and B<G> conversions, the "
8364 "converted value is padded on the left with zeros rather than blanks. If the "
8365 "B<\\&0> and B<-> flags both appear, the B<\\&0> flag is ignored. If a "
8366 "precision is given with a numeric conversion (B<d>, B<i>, B<o>, B<u>, B<x>, "
8367 "and B<X>), the B<\\&0> flag is ignored. For other conversions, the behavior "
8372 #: build/C/man3/printf.3:331
8378 #: build/C/man3/printf.3:342
8380 "The converted value is to be left adjusted on the field boundary. (The "
8381 "default is right justification.) The converted value is padded on the right "
8382 "with blanks, rather than on the left with blanks or zeros. A B<-> overrides "
8383 "a B<\\&0> if both are given."
8387 #: build/C/man3/printf.3:342
8389 msgid "B<\\(aq \\(aq>"
8393 #: build/C/man3/printf.3:346
8395 "(a space) A blank should be left before a positive number (or empty string) "
8396 "produced by a signed conversion."
8400 #: build/C/man3/printf.3:346
8406 #: build/C/man3/printf.3:354
8408 "A sign (+ or -) should always be placed before a number produced by a signed "
8409 "conversion. By default a sign is used only for negative numbers. A B<+> "
8410 "overrides a space if both are used."
8414 #: build/C/man3/printf.3:357
8416 "The five flag characters above are defined in the C99 standard. The Single "
8417 "UNIX Specification specifies one further flag character."
8421 #: build/C/man3/printf.3:357
8427 #: build/C/man3/printf.3:374
8429 "For decimal conversion (B<i>, B<d>, B<u>, B<f>, B<F>, B<g>, B<G>) the "
8430 "output is to be grouped with thousands' grouping characters if the locale "
8431 "information indicates any. Note that many versions of B<gcc>(1) cannot "
8432 "parse this option and will issue a warning. (SUSv2 did not include "
8433 "I<%\\(aqF>, but SUSv3 added it.)"
8437 #: build/C/man3/printf.3:376
8438 msgid "glibc 2.2 adds one further flag character."
8442 #: build/C/man3/printf.3:376
8447 #. outdigits keyword in locale file
8449 #: build/C/man3/printf.3:386
8451 "For decimal integer conversion (B<i>, B<d>, B<u>) the output uses the "
8452 "locale's alternative output digits, if any. For example, since glibc 2.2.3 "
8453 "this will give Arabic-Indic digits in the Persian (\"fa_IR\") locale."
8457 #: build/C/man3/printf.3:386
8459 msgid "The field width"
8463 #: build/C/man3/printf.3:402
8465 "An optional decimal digit string (with nonzero first digit) specifying a "
8466 "minimum field width. If the converted value has fewer characters than the "
8467 "field width, it will be padded with spaces on the left (or right, if the "
8468 "left-adjustment flag has been given). Instead of a decimal digit string one "
8469 "may write \"*\" or \"*m$\" (for some decimal integer I<m>) to specify that "
8470 "the field width is given in the next argument, or in the I<m>-th argument, "
8471 "respectively, which must be of type I<int>. A negative field width is taken "
8472 "as a \\(aq-\\(aq flag followed by a positive field width. In no case does a "
8473 "nonexistent or small field width cause truncation of a field; if the result "
8474 "of a conversion is wider than the field width, the field is expanded to "
8475 "contain the conversion result."
8479 #: build/C/man3/printf.3:402
8481 msgid "The precision"
8485 #: build/C/man3/printf.3:439
8487 "An optional precision, in the form of a period (\\(aq.\\(aq) followed by an "
8488 "optional decimal digit string. Instead of a decimal digit string one may "
8489 "write \"*\" or \"*m$\" (for some decimal integer m) to specify that the "
8490 "precision is given in the next argument, or in the m-th argument, "
8491 "respectively, which must be of type I<int>. If the precision is given as "
8492 "just \\(aq.\\(aq, the precision is taken to be zero. A negative precision "
8493 "is taken as if the precision were omitted. This gives the minimum number of "
8494 "digits to appear for B<d>, B<i>, B<o>, B<u>, B<x>, and B<X> conversions, the "
8495 "number of digits to appear after the radix character for B<a>, B<A>, B<e>, "
8496 "B<E>, B<f>, and B<F> conversions, the maximum number of significant digits "
8497 "for B<g> and B<G> conversions, or the maximum number of characters to be "
8498 "printed from a string for B<s> and B<S> conversions."
8502 #: build/C/man3/printf.3:439
8504 msgid "The length modifier"
8508 #: build/C/man3/printf.3:449
8510 "Here, \"integer conversion\" stands for B<d>, B<i>, B<o>, B<u>, B<x>, or "
8515 #: build/C/man3/printf.3:449 build/C/man3/scanf.3:294
8521 #: build/C/man3/printf.3:460
8523 "A following integer conversion corresponds to a I<signed char> or I<unsigned "
8524 "char> argument, or a following B<n> conversion corresponds to a pointer to a "
8525 "I<signed char> argument."
8529 #: build/C/man3/printf.3:460 build/C/man3/scanf.3:284
8535 #: build/C/man3/printf.3:471
8537 "A following integer conversion corresponds to a I<short int> or I<unsigned "
8538 "short int> argument, or a following B<n> conversion corresponds to a pointer "
8539 "to a I<short int> argument."
8543 #: build/C/man3/printf.3:471 build/C/man3/scanf.3:311
8549 #: build/C/man3/printf.3:490
8551 "(ell) A following integer conversion corresponds to a I<long int> or "
8552 "I<unsigned long int> argument, or a following B<n> conversion corresponds to "
8553 "a pointer to a I<long int> argument, or a following B<c> conversion "
8554 "corresponds to a I<wint_t> argument, or a following B<s> conversion "
8555 "corresponds to a pointer to I<wchar_t> argument."
8559 #: build/C/man3/printf.3:490
8565 #: build/C/man3/printf.3:502
8567 "(ell-ell). A following integer conversion corresponds to a I<long long int> "
8568 "or I<unsigned long long int> argument, or a following B<n> conversion "
8569 "corresponds to a pointer to a I<long long int> argument."
8573 #: build/C/man3/printf.3:502 build/C/man3/scanf.3:338
8580 #. ("quad". 4.4BSD and Linux libc5 only.
8583 #: build/C/man3/printf.3:524
8585 "A following B<a>, B<A>, B<e>, B<E>, B<f>, B<F>, B<g>, or B<G> conversion "
8586 "corresponds to a I<long double> argument. (C99 allows %LF, but SUSv2 does "
8587 "not.) This is a synonym for B<ll>."
8591 #: build/C/man3/printf.3:524 build/C/man3/scanf.3:302
8597 #: build/C/man3/printf.3:535
8599 "A following integer conversion corresponds to an I<intmax_t> or I<uintmax_t> "
8600 "argument, or a following B<n> conversion corresponds to a pointer to an "
8601 "I<intmax_t> argument."
8605 #: build/C/man3/printf.3:535 build/C/man3/scanf.3:366
8612 #. with this meaning.
8615 #: build/C/man3/printf.3:550
8617 "A following integer conversion corresponds to a I<size_t> or I<ssize_t> "
8618 "argument, or a following B<n> conversion corresponds to a pointer to a "
8619 "I<size_t> argument."
8623 #: build/C/man3/printf.3:550 build/C/man3/scanf.3:359
8629 #: build/C/man3/printf.3:559
8631 "A following integer conversion corresponds to a I<ptrdiff_t> argument, or a "
8632 "following B<n> conversion corresponds to a pointer to a I<ptrdiff_t> "
8637 #: build/C/man3/printf.3:589
8639 "SUSv3 specifies all of the above. SUSv2 specified only the length modifiers "
8640 "B<h> (in B<hd>, B<hi>, B<ho>, B<hx>, B<hX>, B<hn>) and B<l> (in B<ld>, "
8641 "B<li>, B<lo>, B<lx>, B<lX>, B<ln>, B<lc>, B<ls>) and B<L> (in B<Le>, B<LE>, "
8642 "B<Lf>, B<Lg>, B<LG>)."
8646 #: build/C/man3/printf.3:589
8648 msgid "The conversion specifier"
8652 #: build/C/man3/printf.3:592
8654 "A character that specifies the type of conversion to be applied. The "
8655 "conversion specifiers and their meanings are:"
8659 #: build/C/man3/printf.3:592
8665 #: build/C/man3/printf.3:602
8667 "The I<int> argument is converted to signed decimal notation. The precision, "
8668 "if any, gives the minimum number of digits that must appear; if the "
8669 "converted value requires fewer digits, it is padded on the left with zeros. "
8670 "The default precision is 1. When 0 is printed with an explicit precision 0, "
8671 "the output is empty."
8675 #: build/C/man3/printf.3:602
8677 msgid "B<o>, B<u>, B<x>, B<X>"
8681 #: build/C/man3/printf.3:629
8683 "The I<unsigned int> argument is converted to unsigned octal (B<o>), unsigned "
8684 "decimal (B<u>), or unsigned hexadecimal (B<x> and B<X>) notation. The "
8685 "letters B<abcdef> are used for B<x> conversions; the letters B<ABCDEF> are "
8686 "used for B<X> conversions. The precision, if any, gives the minimum number "
8687 "of digits that must appear; if the converted value requires fewer digits, it "
8688 "is padded on the left with zeros. The default precision is 1. When 0 is "
8689 "printed with an explicit precision 0, the output is empty."
8693 #: build/C/man3/printf.3:629
8699 #: build/C/man3/printf.3:648
8701 "The I<double> argument is rounded and converted in the style "
8702 "[-]dB<\\&.>dddB<e>\\(+-dd where there is one digit before the decimal-point "
8703 "character and the number of digits after it is equal to the precision; if "
8704 "the precision is missing, it is taken as 6; if the precision is zero, no "
8705 "decimal-point character appears. An B<E> conversion uses the letter B<E> "
8706 "(rather than B<e>) to introduce the exponent. The exponent always contains "
8707 "at least two digits; if the value is zero, the exponent is 00."
8711 #: build/C/man3/printf.3:648
8717 #: build/C/man3/printf.3:659
8719 "The I<double> argument is rounded and converted to decimal notation in the "
8720 "style [-]dddB<\\&.>ddd, where the number of digits after the decimal-point "
8721 "character is equal to the precision specification. If the precision is "
8722 "missing, it is taken as 6; if the precision is explicitly zero, no "
8723 "decimal-point character appears. If a decimal point appears, at least one "
8724 "digit appears before it."
8728 #: build/C/man3/printf.3:672
8730 "(SUSv2 does not know about B<F> and says that character string "
8731 "representations for infinity and NaN may be made available. SUSv3 adds a "
8732 "specification for B<F>. The C99 standard specifies \"[-]inf\" or "
8733 "\"[-]infinity\" for infinity, and a string starting with \"nan\" for NaN, in "
8734 "the case of B<f> conversion, and \"[-]INF\" or \"[-]INFINITY\" or \"NAN*\" "
8735 "in the case of B<F> conversion.)"
8739 #: build/C/man3/printf.3:672
8745 #: build/C/man3/printf.3:697
8747 "The I<double> argument is converted in style B<f> or B<e> (or B<F> or B<E> "
8748 "for B<G> conversions). The precision specifies the number of significant "
8749 "digits. If the precision is missing, 6 digits are given; if the precision "
8750 "is zero, it is treated as 1. Style B<e> is used if the exponent from its "
8751 "conversion is less than -4 or greater than or equal to the precision. "
8752 "Trailing zeros are removed from the fractional part of the result; a decimal "
8753 "point appears only if it is followed by at least one digit."
8757 #: build/C/man3/printf.3:697
8763 #: build/C/man3/printf.3:722
8765 "(C99; not in SUSv2, but added in SUSv3) For B<a> conversion, the I<double> "
8766 "argument is converted to hexadecimal notation (using the letters abcdef) in "
8767 "the style [-]B<0x>hB<\\&.>hhhhB<p>\\(+-; for B<A> conversion the prefix "
8768 "B<0X>, the letters ABCDEF, and the exponent separator B<P> is used. There "
8769 "is one hexadecimal digit before the decimal point, and the number of digits "
8770 "after it is equal to the precision. The default precision suffices for an "
8771 "exact representation of the value if an exact representation in base 2 "
8772 "exists and otherwise is sufficiently large to distinguish values of type "
8773 "I<double>. The digit before the decimal point is unspecified for "
8774 "nonnormalized numbers, and nonzero but otherwise unspecified for normalized "
8779 #: build/C/man3/printf.3:722 build/C/man3/scanf.3:459 build/C/man3/wprintf.3:149
8785 #: build/C/man3/printf.3:740
8787 "If no B<l> modifier is present, the I<int> argument is converted to an "
8788 "I<unsigned char>, and the resulting character is written. If an B<l> "
8789 "modifier is present, the I<wint_t> (wide character) argument is converted to "
8790 "a multibyte sequence by a call to the B<wcrtomb>(3) function, with a "
8791 "conversion state starting in the initial state, and the resulting multibyte "
8792 "string is written."
8796 #: build/C/man3/printf.3:740 build/C/man3/scanf.3:451 build/C/man3/wprintf.3:163
8802 #: build/C/man3/printf.3:755
8804 "If no B<l> modifier is present: The I<const char\\ *> argument is expected "
8805 "to be a pointer to an array of character type (pointer to a string). "
8806 "Characters from the array are written up to (but not including) a "
8807 "terminating null byte (\\(aq\\e0\\(aq); if a precision is specified, no more "
8808 "than the number specified are written. If a precision is given, no null "
8809 "byte need be present; if the precision is not specified, or is greater than "
8810 "the size of the array, the array must contain a terminating null byte."
8814 #: build/C/man3/printf.3:782
8816 "If an B<l> modifier is present: The I<const wchar_t\\ *> argument is "
8817 "expected to be a pointer to an array of wide characters. Wide characters "
8818 "from the array are converted to multibyte characters (each by a call to the "
8819 "B<wcrtomb>(3) function, with a conversion state starting in the initial "
8820 "state before the first wide character), up to and including a terminating "
8821 "null wide character. The resulting multibyte characters are written up to "
8822 "(but not including) the terminating null byte. If a precision is specified, "
8823 "no more bytes than the number specified are written, but no partial "
8824 "multibyte characters are written. Note that the precision determines the "
8825 "number of I<bytes> written, not the number of I<wide characters> or I<screen "
8826 "positions>. The array must contain a terminating null wide character, "
8827 "unless a precision is given and it is so small that the number of bytes "
8828 "written exceeds it before the end of the array is reached."
8832 #: build/C/man3/printf.3:782
8838 #: build/C/man3/printf.3:788
8840 "(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) Synonym for B<lc>. "
8845 #: build/C/man3/printf.3:788
8851 #: build/C/man3/printf.3:794
8853 "(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) Synonym for B<ls>. "
8858 #: build/C/man3/printf.3:794 build/C/man3/scanf.3:502
8864 #: build/C/man3/printf.3:802
8866 "The I<void\\ *> pointer argument is printed in hexadecimal (as if by B<%#x> "
8871 #: build/C/man3/printf.3:802 build/C/man3/scanf.3:510
8877 #: build/C/man3/printf.3:813
8879 "The number of characters written so far is stored into the integer pointed "
8880 "to by the corresponding argument. That argument shall be an I<int\\ *>, or "
8881 "variant whose size matches the (optionally) supplied integer length "
8882 "modifier. No argument is converted. The behavior is undefined if the "
8883 "conversion specification includes any flags, a field width, or a precision."
8887 #: build/C/man3/printf.3:813
8893 #: build/C/man3/printf.3:819
8895 "(Glibc extension.) Print output of I<strerror(errno)>. No argument is "
8900 #: build/C/man3/printf.3:819 build/C/man3/scanf.3:377
8906 #: build/C/man3/printf.3:825
8908 "A \\(aq%\\(aq is written. No argument is converted. The complete "
8909 "conversion specification is \\(aq%%\\(aq."
8913 #: build/C/man3/printf.3:840
8915 "The B<fprintf>(), B<printf>(), B<sprintf>(), B<vprintf>(), B<vfprintf>(), "
8916 "and B<vsprintf>() functions conform to C89 and C99. The B<snprintf>() and "
8917 "B<vsnprintf>() functions conform to C99."
8921 #. Linux libc4 knows about the five C standard flags.
8922 #. It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
8923 #. and the conversions
8924 #. \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
8925 #. \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
8926 #. \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
8927 #. where \fBF\fP is a synonym for \fBf\fP.
8928 #. Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
8929 #. for \fBld\fP, \fBlo\fP, and \fBlu\fP.
8930 #. (This is bad, and caused serious bugs later, when
8931 #. support for \fB%D\fP disappeared.)
8932 #. No locale-dependent radix character,
8933 #. no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
8935 #. Linux libc5 knows about the five C standard flags and the \(aq flag,
8936 #. locale, "%m$" and "*m$".
8937 #. It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
8938 #. \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
8939 #. both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
8940 #. It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
8941 #. but adds the conversion character
8944 #. .IR strerror(errno) .
8946 #. glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
8948 #: build/C/man3/printf.3:883
8950 "Concerning the return value of B<snprintf>(), SUSv2 and C99 contradict each "
8951 "other: when B<snprintf>() is called with I<size>=0 then SUSv2 stipulates an "
8952 "unspecified return value less than 1, while C99 allows I<str> to be NULL in "
8953 "this case, and gives the return value (as always) as the number of "
8954 "characters that would have been written in case the output string has been "
8955 "large enough. SUSv3 and later align their specification of B<snprintf>() "
8960 #: build/C/man3/printf.3:886
8962 "glibc 2.1 adds length modifiers B<hh>, B<j>, B<t>, and B<z> and conversion "
8963 "characters B<a> and B<A>."
8967 #: build/C/man3/printf.3:889
8969 "glibc 2.2 adds the conversion character B<F> with C99 semantics, and the "
8970 "flag character B<I>."
8974 #: build/C/man3/printf.3:891
8975 msgid "Some programs imprudently rely on code such as the following"
8979 #: build/C/man3/printf.3:893
8981 msgid " sprintf(buf, \"%s some further text\", buf);\n"
8984 #. http://sourceware.org/bugzilla/show_bug.cgi?id=7075
8986 #: build/C/man3/printf.3:909
8988 "to append text to I<buf>. However, the standards explicitly note that the "
8989 "results are undefined if source and destination buffers overlap when calling "
8990 "B<sprintf>(), B<snprintf>(), B<vsprintf>(), and B<vsnprintf>(). Depending "
8991 "on the version of B<gcc>(1) used, and the compiler options employed, calls "
8992 "such as the above will B<not> produce the expected results."
8996 #. UNIX V7 defines the three routines
9000 #. and has the flag \-, the width or precision *, the length modifier l,
9001 #. and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
9002 #. This is still true for 2.9.1BSD, but 2.10BSD has the flags
9003 #. #, + and <space> and no longer mentions D,O,U,X.
9008 #. and warns not to use D,O,U,X.
9009 #. 4.3BSD Reno has the flag 0, the length modifiers h and L,
9010 #. and the conversions n, p, E, G, X (with current meaning)
9011 #. and deprecates D,O,U.
9012 #. 4.4BSD introduces the functions
9015 #. .BR vsnprintf (),
9016 #. and the length modifier q.
9017 #. FreeBSD also has functions
9020 #. .BR vasprintf (),
9021 #. that allocate a buffer large enough for
9023 #. In glibc there are functions
9027 #. that print to a file descriptor instead of a stream.
9029 #: build/C/man3/printf.3:951
9031 "The glibc implementation of the functions B<snprintf>() and B<vsnprintf>() "
9032 "conforms to the C99 standard, that is, behaves as described above, since "
9033 "glibc version 2.1. Until glibc 2.0.6, they would return -1 when the output "
9038 #. Linux libc4.[45] does not have a
9040 #. but provides a libbsd that contains an
9044 #. that is, one that ignores the
9049 #. with early libc4 leads to serious security problems.
9051 #: build/C/man3/printf.3:981
9053 "Because B<sprintf>() and B<vsprintf>() assume an arbitrarily long string, "
9054 "callers must be careful not to overflow the actual space; this is often "
9055 "impossible to assure. Note that the length of the strings produced is "
9056 "locale-dependent and difficult to predict. Use B<snprintf>() and "
9057 "B<vsnprintf>() instead (or B<asprintf>(3) and B<vasprintf>(3))."
9061 #. Some floating-point conversions under early libc4
9062 #. caused memory leaks.
9064 #: build/C/man3/printf.3:995
9066 "Code such as B<printf(>I<foo>B<);> often indicates a bug, since I<foo> may "
9067 "contain a % character. If I<foo> comes from untrusted user input, it may "
9068 "contain B<%n>, causing the B<printf>() call to write to memory and creating "
9073 #: build/C/man3/printf.3:999
9074 msgid "To print I<Pi> to five decimal places:"
9078 #: build/C/man3/printf.3:1005
9081 "#include E<lt>math.hE<gt>\n"
9082 "#include E<lt>stdio.hE<gt>\n"
9083 "fprintf(stdout, \"pi = %.5f\\en\", 4 * atan(1.0));\n"
9087 #: build/C/man3/printf.3:1014
9089 "To print a date and time in the form \"Sunday, July 3, 10:02\", where "
9090 "I<weekday> and I<month> are pointers to strings:"
9094 #: build/C/man3/printf.3:1020
9097 "#include E<lt>stdio.hE<gt>\n"
9098 "fprintf(stdout, \"%s, %s %d, %.2d:%.2d\\en\",\n"
9099 " weekday, month, day, hour, min);\n"
9103 #: build/C/man3/printf.3:1026
9105 "Many countries use the day-month-year order. Hence, an internationalized "
9106 "version must be able to print the arguments in an order specified by the "
9111 #: build/C/man3/printf.3:1032
9114 "#include E<lt>stdio.hE<gt>\n"
9115 "fprintf(stdout, format,\n"
9116 " weekday, month, day, hour, min);\n"
9120 #: build/C/man3/printf.3:1039
9122 "where I<format> depends on locale, and may permute the arguments. With the "
9127 #: build/C/man3/printf.3:1043
9129 msgid "\"%1$s, %3$d. %2$s, %4$d:%5$.2d\\en\"\n"
9133 #: build/C/man3/printf.3:1047
9134 msgid "one might obtain \"Sonntag, 3. Juli, 10:02\"."
9138 #: build/C/man3/printf.3:1050
9140 "To allocate a sufficiently large string and print into it (code correct for "
9141 "both glibc 2.0 and glibc 2.1):"
9145 #: build/C/man3/printf.3:1055
9148 "#include E<lt>stdio.hE<gt>\n"
9149 "#include E<lt>stdlib.hE<gt>\n"
9150 "#include E<lt>stdarg.hE<gt>\n"
9154 #: build/C/man3/printf.3:1063
9158 "make_message(const char *fmt, ...)\n"
9161 " int size = 100; /* Guess we need no more than 100 bytes */\n"
9167 #: build/C/man3/printf.3:1067
9170 " p = malloc(size);\n"
9176 #: build/C/man3/printf.3:1069
9178 msgid " while (1) {\n"
9182 #: build/C/man3/printf.3:1071
9184 msgid " /* Try to print in the allocated space */\n"
9188 #: build/C/man3/printf.3:1075
9191 " va_start(ap, fmt);\n"
9192 " n = vsnprintf(p, size, fmt, ap);\n"
9197 #: build/C/man3/printf.3:1077
9199 msgid " /* Check error code */\n"
9203 #: build/C/man3/printf.3:1082
9206 " if (n E<lt> 0) {\n"
9213 #: build/C/man3/printf.3:1084
9215 msgid " /* If that worked, return the string */\n"
9219 #: build/C/man3/printf.3:1087
9222 " if (n E<lt> size)\n"
9227 #: build/C/man3/printf.3:1089
9229 msgid " /* Else try again with more space */\n"
9233 #: build/C/man3/printf.3:1091
9235 msgid " size = n + 1; /* Precisely what is needed */\n"
9239 #: build/C/man3/printf.3:1102
9242 " np = realloc(p, size);\n"
9243 " if (np == NULL) {\n"
9254 #: build/C/man3/printf.3:1106
9256 "If truncation occurs in glibc versions prior to 2.0.6, this is treated as an "
9257 "error instead of being handled gracefully."
9261 #: build/C/man3/printf.3:1115
9263 "B<printf>(1), B<asprintf>(3), B<dprintf>(3), B<scanf>(3), B<setlocale>(3), "
9264 "B<wcrtomb>(3), B<wprintf>(3), B<locale>(5)"
9268 #: build/C/man3/puts.3:26
9274 #: build/C/man3/puts.3:26 build/C/man3/scanf.3:52
9280 #: build/C/man3/puts.3:29
9281 msgid "fputc, fputs, putc, putchar, puts - output of characters and strings"
9285 #: build/C/man3/puts.3:34
9287 msgid "B<int fputc(int >I<c>B<, FILE *>I<stream>B<);>\n"
9291 #: build/C/man3/puts.3:36
9293 msgid "B<int fputs(const char *>I<s>B<, FILE *>I<stream>B<);>\n"
9297 #: build/C/man3/puts.3:38
9299 msgid "B<int putc(int >I<c>B<, FILE *>I<stream>B<);>\n"
9303 #: build/C/man3/puts.3:40
9305 msgid "B<int putchar(int >I<c>B<);>\n"
9309 #: build/C/man3/puts.3:42
9311 msgid "B<int puts(const char *>I<s>B<);>\n"
9315 #: build/C/man3/puts.3:51
9317 "B<fputc>() writes the character I<c>, cast to an I<unsigned char>, to "
9322 #: build/C/man3/puts.3:58
9324 "B<fputs>() writes the string I<s> to I<stream>, without its terminating "
9325 "null byte (\\(aq\\e0\\(aq)."
9329 #: build/C/man3/puts.3:65
9331 "B<putc>() is equivalent to B<fputc>() except that it may be implemented as "
9332 "a macro which evaluates I<stream> more than once."
9336 #: build/C/man3/puts.3:69
9337 msgid "B<putchar(>I<c>B<)> is equivalent to B<putc(>I<c>B<, >I<stdout>B<).>"
9341 #: build/C/man3/puts.3:76
9342 msgid "B<puts>() writes the string I<s> and a trailing newline to I<stdout>."
9346 #: build/C/man3/puts.3:81
9348 "Calls to the functions described here can be mixed with each other and with "
9349 "calls to other output functions from the I<stdio> library for the same "
9354 #: build/C/man3/puts.3:96
9356 "B<fputc>(), B<putc>() and B<putchar>() return the character written as an "
9357 "I<unsigned char> cast to an I<int> or B<EOF> on error."
9361 #: build/C/man3/puts.3:103
9363 "B<puts>() and B<fputs>() return a nonnegative number on success, or B<EOF> "
9368 #: build/C/man3/puts.3:112
9370 "It is not advisable to mix calls to output functions from the I<stdio> "
9371 "library with low-level calls to B<write>(2) for the file descriptor "
9372 "associated with the same output stream; the results will be undefined and "
9373 "very probably not what you want."
9377 #: build/C/man3/puts.3:124
9379 "B<write>(2), B<ferror>(3), B<fgets>(3), B<fopen>(3), B<fputwc>(3), "
9380 "B<fputws>(3), B<fseek>(3), B<fwrite>(3), B<putwchar>(3), B<scanf>(3), "
9381 "B<unlocked_stdio>(3)"
9385 #: build/C/man2/read.2:35
9391 #: build/C/man2/read.2:35
9397 #: build/C/man2/read.2:38
9398 msgid "read - read from a file descriptor"
9402 #: build/C/man2/read.2:43
9404 msgid "B<ssize_t read(int >I<fd>B<, void *>I<buf>B<, size_t >I<count>B<);>\n"
9408 #: build/C/man2/read.2:52
9410 "B<read>() attempts to read up to I<count> bytes from file descriptor I<fd> "
9411 "into the buffer starting at I<buf>."
9415 #: build/C/man2/read.2:60
9417 "On files that support seeking, the read operation commences at the current "
9418 "file offset, and the file offset is incremented by the number of bytes "
9419 "read. If the current file offset is at or past the end of file, no bytes "
9420 "are read, and B<read>() returns zero."
9424 #: build/C/man2/read.2:75
9426 "If I<count> is zero, B<read>() I<may> detect the errors described below. "
9427 "In the absence of any errors, or if B<read>() does not check for errors, a "
9428 "B<read>() with a I<count> of 0 returns zero and has no other effects."
9432 #: build/C/man2/read.2:81
9433 msgid "If I<count> is greater than B<SSIZE_MAX>, the result is unspecified."
9437 #: build/C/man2/read.2:95
9439 "On success, the number of bytes read is returned (zero indicates end of "
9440 "file), and the file position is advanced by this number. It is not an error "
9441 "if this number is smaller than the number of bytes requested; this may "
9442 "happen for example because fewer bytes are actually available right now "
9443 "(maybe because we were close to end-of-file, or because we are reading from "
9444 "a pipe, or from a terminal), or because B<read>() was interrupted by a "
9445 "signal. On error, -1 is returned, and I<errno> is set appropriately. In "
9446 "this case, it is left unspecified whether the file position (if any) "
9451 #: build/C/man2/read.2:96 build/C/man3/scanf.3:548 build/C/man2/write.2:108
9457 #: build/C/man2/read.2:103
9459 "The file descriptor I<fd> refers to a file other than a socket and has been "
9460 "marked nonblocking (B<O_NONBLOCK>), and the read would block."
9464 #: build/C/man2/read.2:103 build/C/man2/write.2:115
9466 msgid "B<EAGAIN> or B<EWOULDBLOCK>"
9469 #. Actually EAGAIN on Linux
9471 #: build/C/man2/read.2:114
9473 "The file descriptor I<fd> refers to a socket and has been marked nonblocking "
9474 "(B<O_NONBLOCK>), and the read would block. POSIX.1-2001 allows either error "
9475 "to be returned for this case, and does not require these constants to have "
9476 "the same value, so a portable application should check for both "
9481 #: build/C/man2/read.2:118
9482 msgid "I<fd> is not a valid file descriptor or is not open for reading."
9486 #: build/C/man2/read.2:122 build/C/man2/write.2:145
9487 msgid "I<buf> is outside your accessible address space."
9491 #: build/C/man2/read.2:126
9493 "The call was interrupted by a signal before any data was read; see "
9498 #: build/C/man2/read.2:137
9500 "I<fd> is attached to an object which is unsuitable for reading; or the file "
9501 "was opened with the B<O_DIRECT> flag, and either the address specified in "
9502 "I<buf>, the value specified in I<count>, or the current file offset is not "
9507 #: build/C/man2/read.2:147
9509 "I<fd> was created via a call to B<timerfd_create>(2) and the wrong size "
9510 "buffer was given to B<read>(); see B<timerfd_create>(2) for further "
9515 #: build/C/man2/read.2:158
9517 "I/O error. This will happen for example when the process is in a background "
9518 "process group, tries to read from its controlling terminal, and either it is "
9519 "ignoring or blocking B<SIGTTIN> or its process group is orphaned. It may "
9520 "also occur when there is a low-level I/O error while reading from a disk or "
9525 #: build/C/man2/read.2:162
9526 msgid "I<fd> refers to a directory."
9530 #: build/C/man2/read.2:173
9532 "Other errors may occur, depending on the object connected to I<fd>. POSIX "
9533 "allows a B<read>() that is interrupted after reading some data to return -1 "
9534 "(with I<errno> set to B<EINTR>) or to return the number of bytes already "
9539 #: build/C/man2/read.2:187
9541 "On NFS filesystems, reading small amounts of data will update the timestamp "
9542 "only the first time, subsequent calls may not do so. This is caused by "
9543 "client side attribute caching, because most if not all NFS clients leave "
9544 "st_atime (last file access time) updates to the server and client side "
9545 "reads satisfied from the client's cache will not cause st_atime updates on "
9546 "the server as there are no server side reads. UNIX semantics can be "
9547 "obtained by disabling client side attribute caching, but in most situations "
9548 "this will substantially increase server load and decrease performance."
9552 #: build/C/man2/read.2:190 build/C/man2/write.2:218
9554 "According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 (\"Thread Interactions "
9555 "with Regular File Operations\"):"
9559 #: build/C/man2/read.2:195 build/C/man2/write.2:223
9561 "All of the following functions shall be atomic with respect to each other in "
9562 "the effects specified in POSIX.1-2008 when they operate on regular files or "
9563 "symbolic links: ..."
9566 #. http://thread.gmane.org/gmane.linux.kernel/1649458
9567 #. From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
9568 #. Subject: Update of file offset on write() etc. is non-atomic with I/O
9569 #. Date: 2014-02-17 15:41:37 GMT
9570 #. Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
9571 #. commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
9572 #. Author: Linus Torvalds <torvalds@linux-foundation.org>
9573 #. Date: Mon Mar 3 09:36:58 2014 -0800
9575 #. vfs: atomic f_pos accesses as per POSIX
9577 #: build/C/man2/read.2:226
9579 "Among the APIs subsequently listed are B<read>() and B<readv>(2). And "
9580 "among the effects that should be atomic across threads (and processes) are "
9581 "updates of the file offset. However, on Linux before version 3.14, this was "
9582 "not the case: if two processes that share an open file description (see "
9583 "B<open>(2)) perform a B<read>() (or B<readv>(2)) at the same time, then "
9584 "the I/O operations were not atomic with respect updating the file offset, "
9585 "with the result that the reads in the two processes might (incorrectly) "
9586 "overlap in the blocks of data that they obtained. This problem was fixed in "
9591 #: build/C/man2/read.2:239
9593 "B<close>(2), B<fcntl>(2), B<ioctl>(2), B<lseek>(2), B<open>(2), B<pread>(2), "
9594 "B<readdir>(2), B<readlink>(2), B<readv>(2), B<select>(2), B<write>(2), "
9599 #: build/C/man2/readlink.2:44
9605 #: build/C/man2/readlink.2:44
9611 #: build/C/man2/readlink.2:47
9612 msgid "readlink, readlinkat - read value of a symbolic link"
9616 #: build/C/man2/readlink.2:53
9619 "B<ssize_t readlink(const char *>I<pathname>B<, char *>I<buf>B<, size_t "
9624 #: build/C/man2/readlink.2:59
9627 "B<ssize_t readlinkat(int >I<dirfd>B<, const char *>I<pathname>B<,>\n"
9628 "B< char *>I<buf>B<, size_t >I<bufsiz>B<);>\n"
9632 #: build/C/man2/readlink.2:68
9633 msgid "B<readlink>():"
9637 #: build/C/man2/readlink.2:71 build/C/man2/symlink.2:59
9639 "_BSD_SOURCE || _XOPEN_SOURCE\\ E<gt>=\\ 500 || _XOPEN_SOURCE\\ &&\\ "
9640 "_XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\\ E<gt>=\\ 200112L"
9644 #: build/C/man2/readlink.2:74
9645 msgid "B<readlinkat>():"
9649 #: build/C/man2/readlink.2:100
9651 "B<readlink>() places the contents of the symbolic link I<pathname> in the "
9652 "buffer I<buf>, which has size I<bufsiz>. B<readlink>() does not append a "
9653 "null byte to I<buf>. It will truncate the contents (to a length of "
9654 "I<bufsiz> characters), in case the buffer is too small to hold all of the "
9659 #: build/C/man2/readlink.2:100
9661 msgid "readlinkat()"
9665 #: build/C/man2/readlink.2:106
9667 "The B<readlinkat>() system call operates in exactly the same way as "
9668 "B<readlink>(), except for the differences described here."
9672 #: build/C/man2/readlink.2:116
9674 "If the pathname given in I<pathname> is relative, then it is interpreted "
9675 "relative to the directory referred to by the file descriptor I<dirfd> "
9676 "(rather than relative to the current working directory of the calling "
9677 "process, as is done by B<readlink>() for a relative pathname)."
9681 #: build/C/man2/readlink.2:128
9683 "If I<pathname> is relative and I<dirfd> is the special value B<AT_FDCWD>, "
9684 "then I<pathname> is interpreted relative to the current working directory of "
9685 "the calling process (like B<readlink>())."
9688 #. commit 65cfc6722361570bfe255698d9cd4dccaf47570d
9690 #: build/C/man2/readlink.2:148
9692 "Since Linux 2.6.39, I<pathname> can be an empty string, in which case the "
9693 "call operates on the symbolic link referred to by I<dirfd> (which should "
9694 "have been obtained using B<open>(2) with the B<O_PATH> and B<O_NOFOLLOW> "
9699 #: build/C/man2/readlink.2:153
9700 msgid "See B<openat>(2) for an explanation of the need for B<readlinkat>()."
9704 #: build/C/man2/readlink.2:159
9706 "On success, these calls return the number of bytes placed in I<buf>. On "
9707 "error, -1 is returned and I<errno> is set to indicate the error."
9711 #: build/C/man2/readlink.2:165
9713 "Search permission is denied for a component of the path prefix. (See also "
9714 "B<path_resolution>(7).)"
9718 #: build/C/man2/readlink.2:169
9719 msgid "I<buf> extends outside the process's allocated address space."
9722 #. At the glibc level, bufsiz is unsigned, so this error can only occur
9723 #. if bufsiz==0. However, the in the kernel syscall, bufsiz is signed,
9724 #. and this error can also occur if bufsiz < 0.
9725 #. See: http://thread.gmane.org/gmane.linux.man/380
9726 #. Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
9728 #: build/C/man2/readlink.2:178
9729 msgid "I<bufsiz> is not positive."
9733 #: build/C/man2/readlink.2:181
9734 msgid "The named file is not a symbolic link."
9738 #: build/C/man2/readlink.2:184
9739 msgid "An I/O error occurred while reading from the filesystem."
9743 #: build/C/man2/readlink.2:187
9744 msgid "Too many symbolic links were encountered in translating the pathname."
9748 #: build/C/man2/readlink.2:190
9749 msgid "A pathname, or a component of a pathname, was too long."
9753 #: build/C/man2/readlink.2:193
9754 msgid "The named file does not exist."
9758 #: build/C/man2/readlink.2:199
9759 msgid "A component of the path prefix is not a directory."
9763 #: build/C/man2/readlink.2:202
9764 msgid "The following additional errors can occur for B<readlinkat>():"
9768 #: build/C/man2/readlink.2:212 build/C/man2/unlink.2:269
9770 "I<pathname> is relative and I<dirfd> is a file descriptor referring to a "
9771 "file other than a directory."
9775 #: build/C/man2/readlink.2:216
9777 "B<readlinkat>() was added to Linux in kernel 2.6.16; library support was "
9778 "added to glibc in version 2.4."
9782 #: build/C/man2/readlink.2:222
9784 "B<readlink>(): 4.4BSD (B<readlink>() first appeared in 4.2BSD), "
9785 "POSIX.1-2001, POSIX.1-2008."
9789 #: build/C/man2/readlink.2:225
9790 msgid "B<readlinkat>(): POSIX.1-2008."
9794 #: build/C/man2/readlink.2:233
9796 "In versions of glibc up to and including glibc 2.4, the return type of "
9797 "B<readlink>() was declared as I<int>. Nowadays, the return type is "
9798 "declared as I<ssize_t>, as (newly) required in POSIX.1-2001."
9802 #: build/C/man2/readlink.2:256
9804 "Using a statically sized buffer might not provide enough room for the "
9805 "symbolic link contents. The required size for the buffer can be obtained "
9806 "from the I<stat.st_size> value returned by a call to B<lstat>(2) on the "
9807 "link. However, the number of bytes written by B<readlink>() and "
9808 "B<readlinkat>() should be checked to make sure that the size of the "
9809 "symbolic link did not increase between the calls. Dynamically allocating "
9810 "the buffer for B<readlink>() and B<readlinkat>() also addresses a common "
9811 "portability problem when using I<PATH_MAX> for the buffer size, as this "
9812 "constant is not guaranteed to be defined per POSIX if the system does not "
9817 #: build/C/man2/readlink.2:269
9819 "On older kernels where B<readlinkat>() is unavailable, the glibc wrapper "
9820 "function falls back to the use of B<readlink>(). When I<pathname> is a "
9821 "relative pathname, glibc constructs a pathname based on the symbolic link in "
9822 "I</proc/self/fd> that corresponds to the I<dirfd> argument."
9826 #: build/C/man2/readlink.2:275
9828 "The following program allocates the buffer needed by B<readlink>() "
9829 "dynamically from the information provided by B<lstat>(), making sure there's "
9830 "no race condition between the calls."
9834 #: build/C/man2/readlink.2:282
9837 "#include E<lt>sys/types.hE<gt>\n"
9838 "#include E<lt>sys/stat.hE<gt>\n"
9839 "#include E<lt>stdio.hE<gt>\n"
9840 "#include E<lt>stdlib.hE<gt>\n"
9841 "#include E<lt>unistd.hE<gt>\n"
9845 #: build/C/man2/readlink.2:289
9849 "main(int argc, char *argv[])\n"
9851 " struct stat sb;\n"
9852 " char *linkname;\n"
9857 #: build/C/man2/readlink.2:294
9860 " if (argc != 2) {\n"
9861 " fprintf(stderr, \"Usage: %s E<lt>pathnameE<gt>\\en\", argv[0]);\n"
9862 " exit(EXIT_FAILURE);\n"
9867 #: build/C/man2/readlink.2:299
9870 " if (lstat(argv[1], &sb) == -1) {\n"
9871 " perror(\"lstat\");\n"
9872 " exit(EXIT_FAILURE);\n"
9877 #: build/C/man2/readlink.2:305
9880 " linkname = malloc(sb.st_size + 1);\n"
9881 " if (linkname == NULL) {\n"
9882 " fprintf(stderr, \"insufficient memory\\en\");\n"
9883 " exit(EXIT_FAILURE);\n"
9888 #: build/C/man2/readlink.2:307
9890 msgid " r = readlink(argv[1], linkname, sb.st_size + 1);\n"
9894 #: build/C/man2/readlink.2:312
9898 " perror(\"readlink\");\n"
9899 " exit(EXIT_FAILURE);\n"
9904 #: build/C/man2/readlink.2:318
9907 " if (r E<gt> sb.st_size) {\n"
9908 " fprintf(stderr, \"symlink increased in size \"\n"
9909 " \"between lstat() and readlink()\\en\");\n"
9910 " exit(EXIT_FAILURE);\n"
9915 #: build/C/man2/readlink.2:320
9917 msgid " linkname[r] = \\(aq\\e0\\(aq;\n"
9921 #: build/C/man2/readlink.2:322
9924 " printf(\"\\(aq%s\\(aq points to \\(aq%s\\(aq\\en\", argv[1], "
9929 #: build/C/man2/readlink.2:324
9931 msgid " free(linkname);\n"
9935 #: build/C/man2/readlink.2:336
9937 "B<readlink>(1), B<lstat>(2), B<stat>(2), B<symlink>(2), B<realpath>(3), "
9938 "B<path_resolution>(7), B<symlink>(7)"
9942 #: build/C/man2/readv.2:32
9948 #: build/C/man2/readv.2:35
9949 msgid "readv, writev, preadv, pwritev - read or write data into multiple buffers"
9953 #: build/C/man2/readv.2:38
9955 msgid "B<#include E<lt>sys/uio.hE<gt>>\n"
9959 #: build/C/man2/readv.2:40
9962 "B<ssize_t readv(int >I<fd>B<, const struct iovec *>I<iov>B<, int "
9967 #: build/C/man2/readv.2:42
9970 "B<ssize_t writev(int >I<fd>B<, const struct iovec *>I<iov>B<, int "
9975 #: build/C/man2/readv.2:45
9978 "B<ssize_t preadv(int >I<fd>B<, const struct iovec *>I<iov>B<, int "
9980 "B< off_t >I<offset>B<);>\n"
9984 #: build/C/man2/readv.2:48
9987 "B<ssize_t pwritev(int >I<fd>B<, const struct iovec *>I<iov>B<, int "
9989 "B< off_t >I<offset>B<);>\n"
9993 #: build/C/man2/readv.2:58
9994 msgid "B<preadv>(), B<pwritev>(): _BSD_SOURCE"
9998 #: build/C/man2/readv.2:68
10000 "The B<readv>() system call reads I<iovcnt> buffers from the file associated "
10001 "with the file descriptor I<fd> into the buffers described by I<iov> "
10002 "(\"scatter input\")."
10005 #. type: Plain text
10006 #: build/C/man2/readv.2:78
10008 "The B<writev>() system call writes I<iovcnt> buffers of data described by "
10009 "I<iov> to the file associated with the file descriptor I<fd> (\"gather "
10013 #. type: Plain text
10014 #: build/C/man2/readv.2:87
10016 "The pointer I<iov> points to an array of I<iovec> structures, defined in "
10017 "I<E<lt>sys/uio.hE<gt>> as:"
10020 #. type: Plain text
10021 #: build/C/man2/readv.2:95
10025 " void *iov_base; /* Starting address */\n"
10026 " size_t iov_len; /* Number of bytes to transfer */\n"
10030 #. type: Plain text
10031 #: build/C/man2/readv.2:103
10033 "The B<readv>() system call works just like B<read>(2) except that multiple "
10034 "buffers are filled."
10037 #. type: Plain text
10038 #: build/C/man2/readv.2:109
10040 "The B<writev>() system call works just like B<write>(2) except that "
10041 "multiple buffers are written out."
10044 #. type: Plain text
10045 #: build/C/man2/readv.2:128
10047 "Buffers are processed in array order. This means that B<readv>() "
10048 "completely fills I<iov>[0] before proceeding to I<iov>[1], and so on. (If "
10049 "there is insufficient data, then not all buffers pointed to by I<iov> may be "
10050 "filled.) Similarly, B<writev>() writes out the entire contents of "
10051 "I<iov>[0] before proceeding to I<iov>[1], and so on."
10054 #. type: Plain text
10055 #: build/C/man2/readv.2:146
10057 "The data transfers performed by B<readv>() and B<writev>() are atomic: the "
10058 "data written by B<writev>() is written as a single block that is not "
10059 "intermingled with output from writes in other processes (but see B<pipe>(7) "
10060 "for an exception); analogously, B<readv>() is guaranteed to read a "
10061 "contiguous block of data from the file, regardless of read operations "
10062 "performed in other threads or processes that have file descriptors referring "
10063 "to the same open file description (see B<open>(2))."
10067 #: build/C/man2/readv.2:146
10069 msgid "preadv() and pwritev()"
10072 #. type: Plain text
10073 #: build/C/man2/readv.2:159
10075 "The B<preadv>() system call combines the functionality of B<readv>() and "
10076 "B<pread>(2). It performs the same task as B<readv>(), but adds a fourth "
10077 "argument, I<offset>, which specifies the file offset at which the input "
10078 "operation is to be performed."
10081 #. type: Plain text
10082 #: build/C/man2/readv.2:172
10084 "The B<pwritev>() system call combines the functionality of B<writev>() and "
10085 "B<pwrite>(2). It performs the same task as B<writev>(), but adds a fourth "
10086 "argument, I<offset>, which specifies the file offset at which the output "
10087 "operation is to be performed."
10090 #. type: Plain text
10091 #: build/C/man2/readv.2:177
10093 "The file offset is not changed by these system calls. The file referred to "
10094 "by I<fd> must be capable of seeking."
10097 #. type: Plain text
10098 #: build/C/man2/readv.2:188
10100 "On success, B<readv>() and B<preadv>() return the number of bytes read; "
10101 "B<writev>() and B<pwritev>() return the number of bytes written. On "
10102 "error, -1 is returned, and I<errno> is set appropriately."
10105 #. type: Plain text
10106 #: build/C/man2/readv.2:200
10108 "The errors are as given for B<read>(2) and B<write>(2). Furthermore, "
10109 "B<preadv>() and B<pwritev>() can also fail for the same reasons as "
10110 "B<lseek>(2). Additionally, the following error is defined:"
10113 #. type: Plain text
10114 #: build/C/man2/readv.2:207
10115 msgid "The sum of the I<iov_len> values overflows an I<ssize_t> value."
10118 #. type: Plain text
10119 #: build/C/man2/readv.2:211
10121 "The vector count I<iovcnt> is less than zero or greater than the permitted "
10125 #. type: Plain text
10126 #: build/C/man2/readv.2:216
10128 "B<preadv>() and B<pwritev>() first appeared in Linux 2.6.30; library "
10129 "support was added in glibc 2.10."
10132 #. Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
10133 #. and \fIint\fP as the return type.
10134 #. The readv/writev system calls were buggy before Linux 1.3.40.
10135 #. (Says release.libc.)
10136 #. type: Plain text
10137 #: build/C/man2/readv.2:224
10139 "B<readv>(), B<writev>(): 4.4BSD (these system calls first appeared in "
10140 "4.2BSD), POSIX.1-2001."
10143 #. type: Plain text
10144 #: build/C/man2/readv.2:228
10145 msgid "B<preadv>(), B<pwritev>(): nonstandard, but present also on the modern BSDs."
10148 #. type: Plain text
10149 #: build/C/man2/readv.2:240
10151 "POSIX.1-2001 allows an implementation to place a limit on the number of "
10152 "items that can be passed in I<iov>. An implementation can advertise its "
10153 "limit by defining B<IOV_MAX> in I<E<lt>limits.hE<gt>> or at run time via the "
10154 "return value from I<sysconf(_SC_IOV_MAX)>. On modern Linux systems, the "
10155 "limit is 1024. Back in Linux 2.0 days, this limit was 16."
10159 #: build/C/man2/readv.2:242
10161 msgid "C library/kernel ABI differences"
10164 #. type: Plain text
10165 #: build/C/man2/readv.2:252
10167 "The raw B<preadv>() and B<pwritev>() system calls have call signatures "
10168 "that differ slightly from that of the corresponding GNU C library wrapper "
10169 "functions shown in the SYNOPSIS. The final argument, I<offset>, is unpacked "
10170 "by the wrapper functions into two arguments in the system calls:"
10173 #. type: Plain text
10174 #: build/C/man2/readv.2:254
10175 msgid "B< unsigned long >I<pos_l>B<, unsigned long >I<pos>"
10178 #. type: Plain text
10179 #: build/C/man2/readv.2:257
10181 "These arguments contain, respectively, the low order and high order 32 bits "
10186 #: build/C/man2/readv.2:257
10188 msgid "Historical C library/kernel ABI differences"
10191 #. type: Plain text
10192 #: build/C/man2/readv.2:283
10194 "To deal with the fact that B<IOV_MAX> was so low on early versions of Linux, "
10195 "the glibc wrapper functions for B<readv>() and B<writev>() did some extra "
10196 "work if they detected that the underlying kernel system call failed because "
10197 "this limit was exceeded. In the case of B<readv>(), the wrapper function "
10198 "allocated a temporary buffer large enough for all of the items specified by "
10199 "I<iov>, passed that buffer in a call to B<read>(2), copied data from the "
10200 "buffer to the locations specified by the I<iov_base> fields of the elements "
10201 "of I<iov>, and then freed the buffer. The wrapper function for B<writev>() "
10202 "performed the analogous task using a temporary buffer and a call to "
10206 #. type: Plain text
10207 #: build/C/man2/readv.2:294
10209 "The need for this extra effort in the glibc wrapper functions went away with "
10210 "Linux 2.2 and later. However, glibc continued to provide this behavior "
10211 "until version 2.10. Starting with glibc version 2.9, the wrapper functions "
10212 "provide this behavior only if the library detects that the system is running "
10213 "a Linux kernel older than version 2.6.18 (an arbitrarily selected kernel "
10214 "version). And since glibc 2.20 (which requires a minimum Linux kernel "
10215 "version of 2.6.32), the glibc wrapper functions always just directly invoke "
10216 "the system calls."
10219 #. type: Plain text
10220 #: build/C/man2/readv.2:301
10222 "It is not advisable to mix calls to B<readv>() or B<writev>(), which "
10223 "operate on file descriptors, with the functions from the stdio library; the "
10224 "results will be undefined and probably not what you want."
10227 #. type: Plain text
10228 #: build/C/man2/readv.2:304
10229 msgid "The following code sample demonstrates the use of B<writev>():"
10232 #. type: Plain text
10233 #: build/C/man2/readv.2:311
10236 "char *str0 = \"hello \";\n"
10237 "char *str1 = \"world\\en\";\n"
10238 "struct iovec iov[2];\n"
10239 "ssize_t nwritten;\n"
10242 #. type: Plain text
10243 #: build/C/man2/readv.2:316
10246 "iov[0].iov_base = str0;\n"
10247 "iov[0].iov_len = strlen(str0);\n"
10248 "iov[1].iov_base = str1;\n"
10249 "iov[1].iov_len = strlen(str1);\n"
10252 #. type: Plain text
10253 #: build/C/man2/readv.2:318
10255 msgid "nwritten = writev(STDOUT_FILENO, iov, 2);\n"
10258 #. type: Plain text
10259 #: build/C/man2/readv.2:324
10260 msgid "B<pread>(2), B<read>(2), B<write>(2)"
10264 #: build/C/man3/remove.3:31
10269 #. type: Plain text
10270 #: build/C/man3/remove.3:34
10271 msgid "remove - remove a file or directory"
10274 #. type: Plain text
10275 #: build/C/man3/remove.3:38
10276 msgid "B<int remove(const char *>I<pathname>B<);>"
10279 #. type: Plain text
10280 #: build/C/man3/remove.3:46
10282 "B<remove>() deletes a name from the filesystem. It calls B<unlink>(2) for "
10283 "files, and B<rmdir>(2) for directories."
10286 #. type: Plain text
10287 #: build/C/man3/remove.3:50
10289 "If the removed name was the last link to a file and no processes have the "
10290 "file open, the file is deleted and the space it was using is made available "
10294 #. type: Plain text
10295 #: build/C/man3/remove.3:55
10297 "If the name was the last link to a file, but any processes still have the "
10298 "file open, the file will remain in existence until the last file descriptor "
10299 "referring to it is closed."
10302 #. type: Plain text
10303 #: build/C/man3/remove.3:57 build/C/man2/unlink.2:78
10304 msgid "If the name referred to a symbolic link, the link is removed."
10307 #. type: Plain text
10308 #: build/C/man3/remove.3:60
10310 "If the name referred to a socket, FIFO, or device, the name is removed, but "
10311 "processes which have the object open may continue to use it."
10314 #. type: Plain text
10315 #: build/C/man3/remove.3:70
10316 msgid "The errors that occur are those for B<unlink>(2) and B<rmdir>(2)."
10319 #. type: Plain text
10320 #: build/C/man3/remove.3:75
10321 msgid "The B<remove>() function is thread-safe."
10325 #. Under libc4 and libc5,
10327 #. was an alias for
10329 #. (and hence would not remove directories).
10330 #. type: Plain text
10331 #: build/C/man3/remove.3:83
10332 msgid "C89, C99, 4.3BSD, POSIX.1-2001."
10335 #. type: Plain text
10336 #: build/C/man3/remove.3:86 build/C/man2/unlink.2:300
10338 "Infelicities in the protocol underlying NFS can cause the unexpected "
10339 "disappearance of files which are still being used."
10342 #. type: Plain text
10343 #: build/C/man3/remove.3:97
10345 "B<rm>(1), B<unlink>(1), B<link>(2), B<mknod>(2), B<open>(2), B<rename>(2), "
10346 "B<rmdir>(2), B<unlink>(2), B<mkfifo>(3), B<symlink>(7)"
10350 #: build/C/man2/rename.2:33
10355 #. type: Plain text
10356 #: build/C/man2/rename.2:36
10357 msgid "rename, renameat, renameat2 - change the name or location of a file"
10360 #. type: Plain text
10361 #: build/C/man2/rename.2:41
10363 msgid "B<int rename(const char *>I<oldpath>B<, const char *>I<newpath>B<);>\n"
10366 #. type: Plain text
10367 #: build/C/man2/rename.2:44
10370 "B<#include E<lt>fcntl.hE<gt> >/* Definition of AT_* constants */\n"
10371 "B<#include E<lt>stdio.hE<gt>>\n"
10374 #. type: Plain text
10375 #: build/C/man2/rename.2:47
10378 "B<int renameat(int >I<olddirfd>B<, const char *>I<oldpath>B<,>\n"
10379 "B< int >I<newdirfd>B<, const char *>I<newpath>B<);>\n"
10382 #. type: Plain text
10383 #: build/C/man2/rename.2:51
10386 "B<int renameat2(int >I<olddirfd>B<, const char *>I<oldpath>B<,>\n"
10387 "B< int >I<newdirfd>B<, const char *>I<newpath>B<, unsigned int "
10391 #. type: Plain text
10392 #: build/C/man2/rename.2:59
10393 msgid "B<renameat>():"
10396 #. type: Plain text
10397 #: build/C/man2/rename.2:81
10399 "B<rename>() renames a file, moving it between directories if required. Any "
10400 "other hard links to the file (as created using B<link>(2)) are unaffected. "
10401 "Open file descriptors for I<oldpath> are also unaffected."
10404 #. type: Plain text
10405 #: build/C/man2/rename.2:89
10407 "If I<newpath> already exists, it will be atomically replaced (subject to a "
10408 "few conditions; see ERRORS below), so that there is no point at which "
10409 "another process attempting to access I<newpath> will find it missing."
10412 #. type: Plain text
10413 #: build/C/man2/rename.2:97
10415 "If I<oldpath> and I<newpath> are existing hard links referring to the same "
10416 "file, then B<rename>() does nothing, and returns a success status."
10419 #. type: Plain text
10420 #: build/C/man2/rename.2:105
10422 "If I<newpath> exists but the operation fails for some reason, B<rename>() "
10423 "guarantees to leave an instance of I<newpath> in place."
10426 #. type: Plain text
10427 #: build/C/man2/rename.2:111
10429 "I<oldpath> can specify a directory. In this case, I<newpath> must either "
10430 "not exist, or it must specify an empty directory."
10433 #. type: Plain text
10434 #: build/C/man2/rename.2:118
10436 "However, when overwriting there will probably be a window in which both "
10437 "I<oldpath> and I<newpath> refer to the file being renamed."
10440 #. type: Plain text
10441 #: build/C/man2/rename.2:124
10443 "If I<oldpath> refers to a symbolic link, the link is renamed; if I<newpath> "
10444 "refers to a symbolic link, the link will be overwritten."
10448 #: build/C/man2/rename.2:124
10453 #. type: Plain text
10454 #: build/C/man2/rename.2:130
10456 "The B<renameat>() system call operates in exactly the same way as "
10457 "B<rename>(), except for the differences described here."
10460 #. type: Plain text
10461 #: build/C/man2/rename.2:140
10463 "If the pathname given in I<oldpath> is relative, then it is interpreted "
10464 "relative to the directory referred to by the file descriptor I<olddirfd> "
10465 "(rather than relative to the current working directory of the calling "
10466 "process, as is done by B<rename>() for a relative pathname)."
10469 #. type: Plain text
10470 #: build/C/man2/rename.2:152
10472 "If I<oldpath> is relative and I<olddirfd> is the special value B<AT_FDCWD>, "
10473 "then I<oldpath> is interpreted relative to the current working directory of "
10474 "the calling process (like B<rename>())."
10477 #. type: Plain text
10478 #: build/C/man2/rename.2:171
10479 msgid "See B<openat>(2) for an explanation of the need for B<renameat>()."
10483 #: build/C/man2/rename.2:171
10485 msgid "renameat2()"
10488 #. type: Plain text
10489 #: build/C/man2/rename.2:182
10491 "B<renameat2>() has an additional I<flags> argument. A B<renameat2>() call "
10492 "with a zero I<flags> argument is equivalent to B<renameat>()."
10495 #. type: Plain text
10496 #: build/C/man2/rename.2:186
10498 "The I<flags> argument is a bit mask consisting of zero or more of the "
10503 #: build/C/man2/rename.2:186
10505 msgid "B<RENAME_NOREPLACE>"
10508 #. type: Plain text
10509 #: build/C/man2/rename.2:194
10511 "Don't overwrite I<newpath> of the rename. Return an error if I<newpath> "
10516 #: build/C/man2/rename.2:194
10518 msgid "B<RENAME_EXCHANGE>"
10521 #. type: Plain text
10522 #: build/C/man2/rename.2:203
10524 "Atomically exchange I<oldpath> and I<newpath>. Both pathnames must exist "
10525 "but may be of different types (e.g., one could be a non-empty directory and "
10526 "the other a symbolic link)."
10529 #. type: Plain text
10530 #: build/C/man2/rename.2:228
10532 "Write permission is denied for the directory containing I<oldpath> or "
10533 "I<newpath>, or, search permission is denied for one of the directories in "
10534 "the path prefix of I<oldpath> or I<newpath>, or I<oldpath> is a directory "
10535 "and does not allow write permission (needed to update the I<..> entry). "
10536 "(See also B<path_resolution>(7).)"
10540 #: build/C/man2/rename.2:228 build/C/man2/rmdir.2:55 build/C/man2/unlink.2:169
10545 #. type: Plain text
10546 #: build/C/man2/rename.2:245
10548 "The rename fails because I<oldpath> or I<newpath> is a directory that is in "
10549 "use by some process (perhaps as current working directory, or as root "
10550 "directory, or because it was open for reading) or is in use by the system "
10551 "(for example as mount point), while the system considers this an error. "
10552 "(Note that there is no requirement to return B<EBUSY> in such "
10553 "cases\\(emthere is nothing wrong with doing the rename anyway\\(embut it is "
10554 "allowed to return B<EBUSY> if the system cannot otherwise handle such "
10558 #. type: Plain text
10559 #: build/C/man2/rename.2:255
10561 "The new pathname contained a path prefix of the old, or, more generally, an "
10562 "attempt was made to make a directory a subdirectory of itself."
10565 #. type: Plain text
10566 #: build/C/man2/rename.2:261
10567 msgid "I<newpath> is an existing directory, but I<oldpath> is not a directory."
10570 #. type: Plain text
10571 #: build/C/man2/rename.2:272
10573 "I<oldpath> already has the maximum number of links to it, or it was a "
10574 "directory and the directory containing I<newpath> has the maximum number of "
10578 #. type: Plain text
10579 #: build/C/man2/rename.2:288
10581 "The link named by I<oldpath> does not exist; or, a directory component in "
10582 "I<newpath> does not exist; or, I<oldpath> or I<newpath> is an empty string."
10585 #. type: Plain text
10586 #: build/C/man2/rename.2:305
10588 "A component used as a directory in I<oldpath> or I<newpath> is not, in fact, "
10589 "a directory. Or, I<oldpath> is a directory, and I<newpath> exists but is "
10594 #: build/C/man2/rename.2:305
10596 msgid "B<ENOTEMPTY> or B<EEXIST>"
10599 #. type: Plain text
10600 #: build/C/man2/rename.2:309
10602 "I<newpath> is a nonempty directory, that is, contains entries other than "
10603 "\".\" and \"..\"."
10607 #: build/C/man2/rename.2:309 build/C/man2/unlink.2:224
10609 msgid "B<EPERM> or B<EACCES>"
10612 #. type: Plain text
10613 #: build/C/man2/rename.2:333
10615 "The directory containing I<oldpath> has the sticky bit (B<S_ISVTX>) set and "
10616 "the process's effective user ID is neither the user ID of the file to be "
10617 "deleted nor that of the directory containing it, and the process is not "
10618 "privileged (Linux: does not have the B<CAP_FOWNER> capability); or "
10619 "I<newpath> is an existing file and the directory containing it has the "
10620 "sticky bit set and the process's effective user ID is neither the user ID of "
10621 "the file to be replaced nor that of the directory containing it, and the "
10622 "process is not privileged (Linux: does not have the B<CAP_FOWNER> "
10623 "capability); or the filesystem containing I<pathname> does not support "
10624 "renaming of the type requested."
10627 #. type: Plain text
10628 #: build/C/man2/rename.2:344
10630 "I<oldpath> and I<newpath> are not on the same mounted filesystem. (Linux "
10631 "permits a filesystem to be mounted at multiple points, but B<rename>() does "
10632 "not work across different mount points, even if the same filesystem is "
10633 "mounted on both.)"
10636 #. type: Plain text
10637 #: build/C/man2/rename.2:349
10639 "The following additional errors can occur for B<renameat>() and "
10643 #. type: Plain text
10644 #: build/C/man2/rename.2:368
10645 msgid "The following additional errors can occur for B<renameat2>():"
10648 #. type: Plain text
10649 #: build/C/man2/rename.2:376
10650 msgid "I<flags> contains B<RENAME_NOREPLACE> and I<newpath> already exists."
10653 #. type: Plain text
10654 #: build/C/man2/rename.2:385
10656 "An invalid flag was specified in I<flags>, or both B<RENAME_NOREPLACE> and "
10657 "B<RENAME_EXCHANGE> were specified."
10660 #. type: Plain text
10661 #: build/C/man2/rename.2:389
10662 msgid "The filesystem does not support one of the flags in I<flags>."
10665 #. type: Plain text
10666 #: build/C/man2/rename.2:397
10667 msgid "I<flags> contains B<RENAME_EXCHANGE> and I<newpath> does not exist."
10670 #. type: Plain text
10671 #: build/C/man2/rename.2:401
10673 "B<renameat>() was added to Linux in kernel 2.6.16; library support was "
10674 "added to glibc in version 2.4."
10677 #. FIXME . glibc support is pending.
10678 #. type: Plain text
10679 #: build/C/man2/rename.2:405
10680 msgid "B<renameat2>() was added to Linux in kernel 3.15."
10683 #. type: Plain text
10684 #: build/C/man2/rename.2:408
10685 msgid "B<rename>(): 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008."
10688 #. type: Plain text
10689 #: build/C/man2/rename.2:411
10690 msgid "B<renameat>(): POSIX.1-2008."
10693 #. type: Plain text
10694 #: build/C/man2/rename.2:414
10695 msgid "B<renameat2>() is Linux-specific."
10698 #. type: Plain text
10699 #: build/C/man2/rename.2:432
10701 "On older kernels where B<renameat>() is unavailable, the glibc wrapper "
10702 "function falls back to the use of B<rename>(). When I<oldpath> and "
10703 "I<newpath> are relative pathnames, glibc constructs pathnames based on the "
10704 "symbolic links in I</proc/self/fd> that correspond to the I<olddirfd> and "
10705 "I<newdirfd> arguments."
10708 #. type: Plain text
10709 #: build/C/man2/rename.2:443
10711 "On NFS filesystems, you can not assume that if the operation failed, the "
10712 "file was not renamed. If the server does the rename operation and then "
10713 "crashes, the retransmitted RPC which will be processed when the server is up "
10714 "again causes a failure. The application is expected to deal with this. See "
10715 "B<link>(2) for a similar problem."
10718 #. type: Plain text
10719 #: build/C/man2/rename.2:451
10721 "B<mv>(1), B<chmod>(2), B<link>(2), B<symlink>(2), B<unlink>(2), "
10722 "B<path_resolution>(7), B<symlink>(7)"
10726 #: build/C/man2/rmdir.2:30
10732 #: build/C/man2/rmdir.2:30
10737 #. type: Plain text
10738 #: build/C/man2/rmdir.2:33
10739 msgid "rmdir - delete a directory"
10742 #. type: Plain text
10743 #: build/C/man2/rmdir.2:37
10744 msgid "B<int rmdir(const char *>I<pathname>B<);>"
10747 #. type: Plain text
10748 #: build/C/man2/rmdir.2:40
10749 msgid "B<rmdir>() deletes a directory, which must be empty."
10752 #. type: Plain text
10753 #: build/C/man2/rmdir.2:55
10755 "Write access to the directory containing I<pathname> was not allowed, or one "
10756 "of the directories in the path prefix of I<pathname> did not allow search "
10757 "permission. (See also B<path_resolution>(7)."
10760 #. type: Plain text
10761 #: build/C/man2/rmdir.2:64
10763 "I<pathname> is currently in use by the system or some process that prevents "
10764 "its removal. On Linux this means I<pathname> is currently used as a mount "
10765 "point or is the root directory of the calling process."
10768 #. type: Plain text
10769 #: build/C/man2/rmdir.2:73
10770 msgid "I<pathname> has I<.> as last component."
10773 #. type: Plain text
10774 #: build/C/man2/rmdir.2:85
10776 "A directory component in I<pathname> does not exist or is a dangling "
10780 #. type: Plain text
10781 #: build/C/man2/rmdir.2:94
10783 "I<pathname>, or a component used as a directory in I<pathname>, is not, in "
10784 "fact, a directory."
10788 #: build/C/man2/rmdir.2:94
10790 msgid "B<ENOTEMPTY>"
10793 #. type: Plain text
10794 #: build/C/man2/rmdir.2:107
10796 "I<pathname> contains entries other than I<.> and I<..> ; or, I<pathname> has "
10797 "I<..> as its final component. POSIX.1-2001 also allows B<EEXIST> for this "
10801 #. type: Plain text
10802 #: build/C/man2/rmdir.2:118
10804 "The directory containing I<pathname> has the sticky bit (B<S_ISVTX>) set "
10805 "and the process's effective user ID is neither the user ID of the file to be "
10806 "deleted nor that of the directory containing it, and the process is not "
10807 "privileged (Linux: does not have the B<CAP_FOWNER> capability)."
10810 #. type: Plain text
10811 #: build/C/man2/rmdir.2:123
10813 "The filesystem containing I<pathname> does not support the removal of "
10817 #. type: Plain text
10818 #: build/C/man2/rmdir.2:127
10819 msgid "I<pathname> refers to a directory on a read-only filesystem."
10822 #. type: Plain text
10823 #: build/C/man2/rmdir.2:132
10825 "Infelicities in the protocol underlying NFS can cause the unexpected "
10826 "disappearance of directories which are still being used."
10829 #. type: Plain text
10830 #: build/C/man2/rmdir.2:141
10832 "B<rm>(1), B<rmdir>(1), B<chdir>(2), B<chmod>(2), B<mkdir>(2), B<rename>(2), "
10833 "B<unlink>(2), B<unlinkat>(2)"
10837 #: build/C/man3/scanf.3:52
10842 #. type: Plain text
10843 #: build/C/man3/scanf.3:55
10844 msgid "scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - input format conversion"
10847 #. type: Plain text
10848 #: build/C/man3/scanf.3:62
10851 "B<int scanf(const char *>I<format>B<, ...);>\n"
10852 "B<int fscanf(FILE *>I<stream>B<, const char *>I<format>B<, ...);>\n"
10853 "B<int sscanf(const char *>I<str>B<, const char *>I<format>B<, ...);>\n"
10856 #. type: Plain text
10857 #: build/C/man3/scanf.3:64
10859 msgid "B<#include E<lt>stdarg.hE<gt>>\n"
10862 #. type: Plain text
10863 #: build/C/man3/scanf.3:68
10866 "B<int vscanf(const char *>I<format>B<, va_list >I<ap>B<);>\n"
10867 "B<int vsscanf(const char *>I<str>B<, const char *>I<format>B<, va_list "
10869 "B<int vfscanf(FILE *>I<stream>B<, const char *>I<format>B<, va_list "
10873 #. type: Plain text
10874 #: build/C/man3/scanf.3:79
10875 msgid "B<vscanf>(), B<vsscanf>(), B<vfscanf>():"
10878 #. type: Plain text
10879 #: build/C/man3/scanf.3:82
10881 "_XOPEN_SOURCE\\ E<gt>=\\ 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE\\ E<gt>=\\ "
10885 #. type: Plain text
10886 #: build/C/man3/scanf.3:104
10888 "The B<scanf>() family of functions scans input according to I<format> as "
10889 "described below. This format may contain I<conversion specifications>; the "
10890 "results from such conversions, if any, are stored in the locations pointed "
10891 "to by the I<pointer> arguments that follow I<format>. Each I<pointer> "
10892 "argument must be of a type that is appropriate for the value returned by the "
10893 "corresponding conversion specification."
10896 #. type: Plain text
10897 #: build/C/man3/scanf.3:115
10899 "If the number of conversion specifications in I<format> exceeds the number "
10900 "of I<pointer> arguments, the results are undefined. If the number of "
10901 "I<pointer> arguments exceeds the number of conversion specifications, then "
10902 "the excess I<pointer> arguments are evaluated, but are otherwise ignored."
10905 #. type: Plain text
10906 #: build/C/man3/scanf.3:127
10908 "The B<scanf>() function reads input from the standard input stream "
10909 "I<stdin>, B<fscanf>() reads input from the stream pointer I<stream>, and "
10910 "B<sscanf>() reads its input from the character string pointed to by I<str>."
10913 #. type: Plain text
10914 #: build/C/man3/scanf.3:145
10916 "The B<vfscanf>() function is analogous to B<vfprintf>(3) and reads input "
10917 "from the stream pointer I<stream> using a variable argument list of pointers "
10918 "(see B<stdarg>(3). The B<vscanf>() function scans a variable argument list "
10919 "from the standard input and the B<vsscanf>() function scans it from a "
10920 "string; these are analogous to the B<vprintf>(3) and B<vsprintf>(3) "
10921 "functions respectively."
10924 #. type: Plain text
10925 #: build/C/man3/scanf.3:159
10927 "The I<format> string consists of a sequence of I<directives> which describe "
10928 "how to process the sequence of input characters. If processing of a "
10929 "directive fails, no further input is read, and B<scanf>() returns. A "
10930 "\"failure\" can be either of the following: I<input failure>, meaning that "
10931 "input characters were unavailable, or I<matching failure>, meaning that the "
10932 "input was inappropriate (see below)."
10935 #. type: Plain text
10936 #: build/C/man3/scanf.3:161
10937 msgid "A directive is one of the following:"
10941 #: build/C/man3/scanf.3:161 build/C/man3/scanf.3:167 build/C/man3/scanf.3:171 build/C/man3/scanf.3:190 build/C/man3/scanf.3:201 build/C/man3/scanf.3:220 build/C/man3/scanf.3:232 build/C/man3/scanf.3:246
10946 #. type: Plain text
10947 #: build/C/man3/scanf.3:167
10949 "A sequence of white-space characters (space, tab, newline, etc.; see "
10950 "B<isspace>(3)). This directive matches any amount of white space, including "
10951 "none, in the input."
10954 #. type: Plain text
10955 #: build/C/man3/scanf.3:171
10957 "An ordinary character (i.e., one other than white space or \\(aq%\\(aq). "
10958 "This character must exactly match the next character of input."
10961 #. type: Plain text
10962 #: build/C/man3/scanf.3:182
10964 "A conversion specification, which commences with a \\(aq%\\(aq (percent) "
10965 "character. A sequence of characters from the input is converted according "
10966 "to this specification, and the result is placed in the corresponding "
10967 "I<pointer> argument. If the next item of input does not match the "
10968 "conversion specification, the conversion fails\\(emthis is a I<matching "
10972 #. type: Plain text
10973 #: build/C/man3/scanf.3:190
10975 "Each I<conversion specification> in I<format> begins with either the "
10976 "character \\(aq%\\(aq or the character sequence \"B<%>I<n>B<$>\" (see below "
10977 "for the distinction) followed by:"
10980 #. type: Plain text
10981 #: build/C/man3/scanf.3:201
10983 "An optional \\(aq*\\(aq assignment-suppression character: B<scanf>() reads "
10984 "input as directed by the conversion specification, but discards the input. "
10985 "No corresponding I<pointer> argument is required, and this specification is "
10986 "not included in the count of successful assignments returned by B<scanf>()."
10989 #. type: Plain text
10990 #: build/C/man3/scanf.3:220
10992 "An optional \\(aqm\\(aq character. This is used with string conversions "
10993 "(I<%s>, I<%c>, I<%[>), and relieves the caller of the need to allocate a "
10994 "corresponding buffer to hold the input: instead, B<scanf>() allocates a "
10995 "buffer of sufficient size, and assigns the address of this buffer to the "
10996 "corresponding I<pointer> argument, which should be a pointer to a I<char\\ "
10997 "*> variable (this variable does not need to be initialized before the "
10998 "call). The caller should subsequently B<free>(3) this buffer when it is no "
11002 #. type: Plain text
11003 #: build/C/man3/scanf.3:232
11005 "An optional decimal integer which specifies the I<maximum field width>. "
11006 "Reading of characters stops either when this maximum is reached or when a "
11007 "nonmatching character is found, whichever happens first. Most conversions "
11008 "discard initial white space characters (the exceptions are noted below), and "
11009 "these discarded characters don't count toward the maximum field width. "
11010 "String input conversions store a terminating null byte (\\(aq\\e0\\(aq) to "
11011 "mark the end of the input; the maximum field width does not include this "
11015 #. type: Plain text
11016 #: build/C/man3/scanf.3:246
11018 "An optional I<type modifier character>. For example, the B<l> type modifier "
11019 "is used with integer conversions such as B<%d> to specify that the "
11020 "corresponding I<pointer> argument refers to a I<long int> rather than a "
11021 "pointer to an I<int>."
11024 #. type: Plain text
11025 #: build/C/man3/scanf.3:251
11027 "A I<conversion specifier> that specifies the type of input conversion to be "
11031 #. type: Plain text
11032 #: build/C/man3/scanf.3:280
11034 "The conversion specifications in I<format> are of two forms, either "
11035 "beginning with \\(aq%\\(aq or beginning with \"B<%>I<n>B<$>\". The two "
11036 "forms should not be mixed in the same I<format> string, except that a string "
11037 "containing \"B<%>I<n>B<$>\" specifications can include B<%%> and B<%*>. If "
11038 "I<format> contains \\(aq%\\(aq specifications, then these correspond in "
11039 "order with successive I<pointer> arguments. In the \"B<%>I<n>B<$>\" form "
11040 "(which is specified in POSIX.1-2001, but not C99), I<n> is a decimal integer "
11041 "that specifies that the converted input should be placed in the location "
11042 "referred to by the I<n>-th I<pointer> argument following I<format>."
11046 #: build/C/man3/scanf.3:280
11048 msgid "Conversions"
11051 #. type: Plain text
11052 #: build/C/man3/scanf.3:284
11054 "The following I<type modifier characters> can appear in a conversion "
11058 #. type: Plain text
11059 #: build/C/man3/scanf.3:294
11061 "Indicates that the conversion will be one of B<d>, B<i>, B<o>, B<u>, B<x>, "
11062 "B<X>, or B<n> and the next pointer is a pointer to a I<short int> or "
11063 "I<unsigned short int> (rather than I<int>)."
11066 #. type: Plain text
11067 #: build/C/man3/scanf.3:302
11069 "As for B<h>, but the next pointer is a pointer to a I<signed char> or "
11070 "I<unsigned char>."
11073 #. type: Plain text
11074 #: build/C/man3/scanf.3:311
11076 "As for B<h>, but the next pointer is a pointer to an I<intmax_t> or a "
11077 "I<uintmax_t>. This modifier was introduced in C99."
11080 #. This use of l was introduced in Amendment 1 to ISO C90.
11081 #. type: Plain text
11082 #: build/C/man3/scanf.3:338
11084 "Indicates either that the conversion will be one of B<d>, B<i>, B<o>, B<u>, "
11085 "B<x>, B<X>, or B<n> and the next pointer is a pointer to a I<long int> or "
11086 "I<unsigned long int> (rather than I<int>), or that the conversion will be "
11087 "one of B<e>, B<f>, or B<g> and the next pointer is a pointer to I<double> "
11088 "(rather than I<float>). Specifying two B<l> characters is equivalent to "
11089 "B<L>. If used with B<%c> or B<%s>, the corresponding parameter is "
11090 "considered as a pointer to a wide character or wide-character string "
11094 #. MTK, Jul 05: The following is no longer true for modern
11095 #. ANSI C (i.e., C99):
11096 #. (Note that long long is not an
11098 #. type. Any program using this will not be portable to all
11100 #. type: Plain text
11101 #: build/C/man3/scanf.3:354
11103 "Indicates that the conversion will be either B<e>, B<f>, or B<g> and the "
11104 "next pointer is a pointer to I<long double> or the conversion will be B<d>, "
11105 "B<i>, B<o>, B<u>, or B<x> and the next pointer is a pointer to I<long long>."
11109 #: build/C/man3/scanf.3:354
11114 #. type: Plain text
11115 #: build/C/man3/scanf.3:359
11116 msgid "equivalent to B<L>. This specifier does not exist in ANSI C."
11119 #. type: Plain text
11120 #: build/C/man3/scanf.3:366
11122 "As for B<h>, but the next pointer is a pointer to a I<ptrdiff_t>. This "
11123 "modifier was introduced in C99."
11126 #. type: Plain text
11127 #: build/C/man3/scanf.3:373
11129 "As for B<h>, but the next pointer is a pointer to a I<size_t>. This "
11130 "modifier was introduced in C99."
11133 #. type: Plain text
11134 #: build/C/man3/scanf.3:377
11135 msgid "The following I<conversion specifiers> are available:"
11138 #. type: Plain text
11139 #: build/C/man3/scanf.3:386
11141 "Matches a literal \\(aq%\\(aq. That is, B<%\\&%> in the format string "
11142 "matches a single input \\(aq%\\(aq character. No conversion is done (but "
11143 "initial white space characters are discarded), and assignment does not "
11148 #: build/C/man3/scanf.3:386
11153 #. type: Plain text
11154 #: build/C/man3/scanf.3:391
11156 "Matches an optionally signed decimal integer; the next pointer must be a "
11157 "pointer to I<int>."
11161 #: build/C/man3/scanf.3:391
11166 #. type: Plain text
11167 #: build/C/man3/scanf.3:400
11169 "Equivalent to I<ld>; this exists only for backward compatibility. (Note: "
11170 "thus only in libc4. In libc5 and glibc the B<%D> is silently ignored, "
11171 "causing old programs to fail mysteriously.)"
11175 #: build/C/man3/scanf.3:400
11180 #. type: Plain text
11181 #: build/C/man3/scanf.3:412
11183 "Matches an optionally signed integer; the next pointer must be a pointer to "
11184 "I<int>. The integer is read in base 16 if it begins with I<0x> or I<0X>, in "
11185 "base 8 if it begins with I<0>, and in base 10 otherwise. Only characters "
11186 "that correspond to the base are used."
11190 #: build/C/man3/scanf.3:412
11195 #. type: Plain text
11196 #: build/C/man3/scanf.3:416
11198 "Matches an unsigned octal integer; the next pointer must be a pointer to "
11203 #: build/C/man3/scanf.3:416
11208 #. type: Plain text
11209 #: build/C/man3/scanf.3:421
11211 "Matches an unsigned decimal integer; the next pointer must be a pointer to "
11215 #. type: Plain text
11216 #: build/C/man3/scanf.3:426
11218 "Matches an unsigned hexadecimal integer; the next pointer must be a pointer "
11219 "to I<unsigned int>."
11223 #: build/C/man3/scanf.3:426
11228 #. type: Plain text
11229 #: build/C/man3/scanf.3:430
11230 msgid "Equivalent to B<x>."
11234 #: build/C/man3/scanf.3:430
11239 #. type: Plain text
11240 #: build/C/man3/scanf.3:435
11242 "Matches an optionally signed floating-point number; the next pointer must be "
11243 "a pointer to I<float>."
11247 #: build/C/man3/scanf.3:435
11252 #. type: Plain text
11253 #: build/C/man3/scanf.3:439 build/C/man3/scanf.3:443 build/C/man3/scanf.3:447
11254 msgid "Equivalent to B<f>."
11258 #: build/C/man3/scanf.3:439
11264 #: build/C/man3/scanf.3:443
11269 #. type: Plain text
11270 #: build/C/man3/scanf.3:451
11271 msgid "(C99) Equivalent to B<f>."
11274 #. type: Plain text
11275 #: build/C/man3/scanf.3:459
11277 "Matches a sequence of non-white-space characters; the next pointer must be a "
11278 "pointer to character array that is long enough to hold the input sequence "
11279 "and the terminating null byte (\\(aq\\e0\\(aq), which is added "
11280 "automatically. The input string stops at white space or at the maximum "
11281 "field width, whichever occurs first."
11284 #. type: Plain text
11285 #: build/C/man3/scanf.3:469
11287 "Matches a sequence of characters whose length is specified by the I<maximum "
11288 "field width> (default 1); the next pointer must be a pointer to I<char>, and "
11289 "there must be enough room for all the characters (no terminating null byte "
11290 "is added). The usual skip of leading white space is suppressed. To skip "
11291 "white space first, use an explicit space in the format."
11295 #: build/C/man3/scanf.3:469
11300 #. type: Plain text
11301 #: build/C/man3/scanf.3:502
11303 "Matches a nonempty sequence of characters from the specified set of accepted "
11304 "characters; the next pointer must be a pointer to I<char>, and there must be "
11305 "enough room for all the characters in the string, plus a terminating null "
11306 "byte. The usual skip of leading white space is suppressed. The string is "
11307 "to be made up of characters in (or not in) a particular set; the set is "
11308 "defined by the characters between the open bracket B<[> character and a "
11309 "close bracket B<]> character. The set I<excludes> those characters if the "
11310 "first character after the open bracket is a circumflex (B<^>). To include a "
11311 "close bracket in the set, make it the first character after the open bracket "
11312 "or the circumflex; any other position will end the set. The hyphen "
11313 "character B<-> is also special; when placed between two other characters, it "
11314 "adds all intervening characters to the set. To include a hyphen, make it "
11315 "the last character before the final close bracket. For instance, "
11316 "B<[^]0-9-]> means the set \"everything except close bracket, zero through "
11317 "nine, and hyphen\". The string ends with the appearance of a character not "
11318 "in the (or, with a circumflex, in) set or when the field width runs out."
11321 #. type: Plain text
11322 #: build/C/man3/scanf.3:510
11324 "Matches a pointer value (as printed by B<%p> in B<printf>(3); the next "
11325 "pointer must be a pointer to a pointer to I<void>."
11328 #. type: Plain text
11329 #: build/C/man3/scanf.3:530
11331 "Nothing is expected; instead, the number of characters consumed thus far "
11332 "from the input is stored through the next pointer, which must be a pointer "
11333 "to I<int>. This is I<not> a conversion, although it can be suppressed with "
11334 "the B<*> assignment-suppression character. The C standard says: \"Execution "
11335 "of a B<%n> directive does not increment the assignment count returned at the "
11336 "completion of execution\" but the Corrigendum seems to contradict this. "
11337 "Probably it is wise not to make any assumptions on the effect of B<%n> "
11338 "conversions on the return value."
11341 #. type: Plain text
11342 #: build/C/man3/scanf.3:535
11344 "These functions return the number of input items successfully matched and "
11345 "assigned, which can be fewer than provided for, or even zero in the event of "
11346 "an early matching failure."
11349 #. type: Plain text
11350 #: build/C/man3/scanf.3:547
11352 "The value B<EOF> is returned if the end of input is reached before either "
11353 "the first successful conversion or a matching failure occurs. B<EOF> is "
11354 "also returned if a read error occurs, in which case the error indicator for "
11355 "the stream (see B<ferror>(3)) is set, and I<errno> is set indicate the "
11359 #. type: Plain text
11360 #: build/C/man3/scanf.3:553
11362 "The file descriptor underlying I<stream> is marked nonblocking, and the read "
11363 "operation would block."
11366 #. type: Plain text
11367 #: build/C/man3/scanf.3:558
11369 "The file descriptor underlying I<stream> is invalid, or not open for "
11373 #. type: Plain text
11374 #: build/C/man3/scanf.3:561
11375 msgid "Input byte sequence does not form a valid character."
11378 #. type: Plain text
11379 #: build/C/man3/scanf.3:565
11380 msgid "The read operation was interrupted by a signal; see B<signal>(7)."
11383 #. type: Plain text
11384 #: build/C/man3/scanf.3:570
11385 msgid "Not enough arguments; or I<format> is NULL."
11388 #. type: Plain text
11389 #: build/C/man3/scanf.3:573
11390 msgid "Out of memory."
11394 #: build/C/man3/scanf.3:573
11399 #. type: Plain text
11400 #: build/C/man3/scanf.3:577
11402 "The result of an integer conversion would exceed the size that can be stored "
11403 "in the corresponding integer type."
11406 #. type: Plain text
11407 #: build/C/man3/scanf.3:587
11409 "The functions B<fscanf>(), B<scanf>(), and B<sscanf>() conform to C89 and "
11410 "C99 and POSIX.1-2001. These standards do not specify the B<ERANGE> error."
11413 #. type: Plain text
11414 #: build/C/man3/scanf.3:597
11416 "The B<q> specifier is the 4.4BSD notation for I<long long>, while B<ll> or "
11417 "the usage of B<L> in integer conversions is the GNU notation."
11420 #. type: Plain text
11421 #: build/C/man3/scanf.3:608
11423 "The Linux version of these functions is based on the I<GNU> I<libio> "
11424 "library. Take a look at the I<info> documentation of I<GNU> I<libc "
11425 "(glibc-1.08)> for a more concise description."
11429 #: build/C/man3/scanf.3:609
11431 msgid "The 'a' assignment-allocation modifier"
11434 #. type: Plain text
11435 #: build/C/man3/scanf.3:620
11437 "Originally, the GNU C library supported dynamic allocation for string inputs "
11438 "(as a nonstandard extension) via the B<a> character. (This feature is "
11439 "present at least as far back as glibc 2.0.) Thus, one could write the "
11440 "following to have B<scanf>() allocate a buffer for an input string, with a "
11441 "pointer to that buffer being returned in I<*buf>:"
11444 #. type: Plain text
11445 #: build/C/man3/scanf.3:623
11449 " scanf(\"%as\", &buf);\n"
11452 #. type: Plain text
11453 #: build/C/man3/scanf.3:634
11455 "The use of the letter B<a> for this purpose was problematic, since B<a> is "
11456 "also specified by the ISO C standard as a synonym for B<f> (floating-point "
11457 "input). POSIX.1-2008 instead specifies the B<m> modifier for assignment "
11458 "allocation (as documented in DESCRIPTION, above)."
11461 #. type: Plain text
11462 #: build/C/man3/scanf.3:646
11464 "Note that the B<a> modifier is not available if the program is compiled with "
11465 "I<gcc -std=c99> or I<gcc -D_ISOC99_SOURCE> (unless B<_GNU_SOURCE> is also "
11466 "specified), in which case the B<a> is interpreted as a specifier for "
11467 "floating-point numbers (see above)."
11470 #. type: Plain text
11471 #: build/C/man3/scanf.3:652
11473 "Support for the B<m> modifier was added to glibc starting with version 2.7, "
11474 "and new programs should use that modifier instead of B<a>."
11477 #. type: Plain text
11478 #: build/C/man3/scanf.3:658
11480 "As well as being standardized by POSIX, the B<m> modifier has the following "
11481 "further advantages over the use of B<a:>"
11484 #. type: Plain text
11485 #: build/C/man3/scanf.3:663
11486 msgid "It may also be applied to B<%c> conversion specifiers (e.g., B<%3mc>)."
11489 #. type: Plain text
11490 #: build/C/man3/scanf.3:669
11492 "It avoids ambiguity with respect to the B<%a> floating-point conversion "
11493 "specifier (and is unaffected by I<gcc -std=c99> etc.)."
11496 #. type: Plain text
11497 #: build/C/man3/scanf.3:682
11499 "All functions are fully C89 conformant, but provide the additional "
11500 "specifiers B<q> and B<a> as well as an additional behavior of the B<L> and "
11501 "B<l> specifiers. The latter may be considered to be a bug, as it changes "
11502 "the behavior of specifiers defined in C89."
11505 #. type: Plain text
11506 #: build/C/man3/scanf.3:698
11508 "Some combinations of the type modifiers and conversion specifiers defined by "
11509 "ANSI C do not make sense (e.g., B<%Ld>). While they may have a well-defined "
11510 "behavior on Linux, this need not to be so on other architectures. Therefore "
11511 "it usually is better to use modifiers that are not defined by ANSI C at all, "
11512 "that is, use B<q> instead of B<L> in combination with B<d>, B<i>, B<o>, "
11513 "B<u>, B<x>, and B<X> conversions or B<ll>."
11516 #. type: Plain text
11517 #: build/C/man3/scanf.3:704
11519 "The usage of B<q> is not the same as on 4.4BSD, as it may be used in float "
11520 "conversions equivalently to B<L>."
11523 #. type: Plain text
11524 #: build/C/man3/scanf.3:714
11526 "To use the dynamic allocation conversion specifier, specify B<m> as a length "
11527 "modifier (thus B<%ms> or B<%m[>I<range>B<]>). The caller must B<free>(3) "
11528 "the returned string, as in the following example:"
11531 #. type: Plain text
11532 #: build/C/man3/scanf.3:719
11539 #. type: Plain text
11540 #: build/C/man3/scanf.3:730
11544 "n = scanf(\"%m[a-z]\", &p);\n"
11546 " printf(\"read: %s\\en\", p);\n"
11548 "} else if (errno != 0) {\n"
11549 " perror(\"scanf\");\n"
11551 " fprintf(stderr, \"No matching characters\\en\");\n"
11555 #. type: Plain text
11556 #: build/C/man3/scanf.3:738
11558 "As shown in the above example, it is necessary to call B<free>(3) only if "
11559 "the B<scanf>() call successfully read a string."
11562 #. type: Plain text
11563 #: build/C/man3/scanf.3:745
11565 "B<getc>(3), B<printf>(3), B<setlocale>(3), B<strtod>(3), B<strtol>(3), "
11570 #: build/C/man3/setbuf.3:48
11575 #. type: Plain text
11576 #: build/C/man3/setbuf.3:51
11577 msgid "setbuf, setbuffer, setlinebuf, setvbuf - stream buffering operations"
11580 #. type: Plain text
11581 #: build/C/man3/setbuf.3:56
11583 msgid "B<void setbuf(FILE *>I<stream>B<, char *>I<buf>B<);>\n"
11586 #. type: Plain text
11587 #: build/C/man3/setbuf.3:58
11589 msgid "B<void setbuffer(FILE *>I<stream>B<, char *>I<buf>B<, size_t >I<size>B<);>\n"
11592 #. type: Plain text
11593 #: build/C/man3/setbuf.3:60
11595 msgid "B<void setlinebuf(FILE *>I<stream>B<);>\n"
11598 #. type: Plain text
11599 #: build/C/man3/setbuf.3:63
11602 "B<int setvbuf(FILE *>I<stream>B<, char *>I<buf>B<, int >I<mode>B<, size_t "
11606 #. type: Plain text
11607 #: build/C/man3/setbuf.3:73
11608 msgid "B<setbuffer>(), B<setlinebuf>(): _BSD_SOURCE"
11611 #. type: Plain text
11612 #: build/C/man3/setbuf.3:96
11614 "The three types of buffering available are unbuffered, block buffered, and "
11615 "line buffered. When an output stream is unbuffered, information appears on "
11616 "the destination file or terminal as soon as written; when it is block "
11617 "buffered many characters are saved up and written as a block; when it is "
11618 "line buffered characters are saved up until a newline is output or input is "
11619 "read from any stream attached to a terminal device (typically I<stdin>). "
11620 "The function B<fflush>(3) may be used to force the block out early. (See "
11621 "B<fclose>(3).) Normally all files are block buffered. When the first I/O "
11622 "operation occurs on a file, B<malloc>(3) is called, and a buffer is "
11623 "obtained. If a stream refers to a terminal (as I<stdout> normally does), it "
11624 "is line buffered. The standard error stream I<stderr> is always unbuffered "
11628 #. type: Plain text
11629 #: build/C/man3/setbuf.3:103
11631 "The B<setvbuf>() function may be used on any open stream to change its "
11632 "buffer. The I<mode> argument must be one of the following three macros:"
11636 #: build/C/man3/setbuf.3:104
11641 #. type: Plain text
11642 #: build/C/man3/setbuf.3:107
11647 #: build/C/man3/setbuf.3:107
11652 #. type: Plain text
11653 #: build/C/man3/setbuf.3:110
11654 msgid "line buffered"
11658 #: build/C/man3/setbuf.3:110
11663 #. type: Plain text
11664 #: build/C/man3/setbuf.3:113
11665 msgid "fully buffered"
11668 #. type: Plain text
11669 #: build/C/man3/setbuf.3:129
11671 "Except for unbuffered files, the I<buf> argument should point to a buffer at "
11672 "least I<size> bytes long; this buffer will be used instead of the current "
11673 "buffer. If the argument I<buf> is NULL, only the mode is affected; a new "
11674 "buffer will be allocated on the next read or write operation. The "
11675 "B<setvbuf>() function may be used only after opening a stream and before "
11676 "any other operations have been performed on it."
11679 #. type: Plain text
11680 #: build/C/man3/setbuf.3:135
11682 "The other three calls are, in effect, simply aliases for calls to "
11683 "B<setvbuf>(). The B<setbuf>() function is exactly equivalent to the call"
11686 #. type: Plain text
11687 #: build/C/man3/setbuf.3:138
11688 msgid "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);"
11691 #. type: Plain text
11692 #: build/C/man3/setbuf.3:148
11694 "The B<setbuffer>() function is the same, except that the size of the buffer "
11695 "is up to the caller, rather than being determined by the default B<BUFSIZ>. "
11696 "The B<setlinebuf>() function is exactly equivalent to the call:"
11699 #. type: Plain text
11700 #: build/C/man3/setbuf.3:151
11701 msgid "setvbuf(stream, NULL, _IOLBF, 0);"
11704 #. type: Plain text
11705 #: build/C/man3/setbuf.3:162
11707 "The function B<setvbuf>() returns 0 on success. It returns nonzero on "
11708 "failure (I<mode> is invalid or the request cannot be honored). It may set "
11709 "I<errno> on failure."
11712 #. type: Plain text
11713 #: build/C/man3/setbuf.3:164
11714 msgid "The other functions do not return a value."
11717 #. type: Plain text
11718 #: build/C/man3/setbuf.3:173
11720 "The B<setbuf>(), B<setbuffer>(), B<setlinebuf>(), and B<setvbuf>() "
11721 "functions are thread-safe."
11724 #. type: Plain text
11725 #: build/C/man3/setbuf.3:179
11726 msgid "The B<setbuf>() and B<setvbuf>() functions conform to C89 and C99."
11729 #. type: Plain text
11730 #: build/C/man3/setbuf.3:196
11732 "You must make sure that the space that I<buf> points to still exists by the "
11733 "time I<stream> is closed, which also happens at program termination. For "
11734 "example, the following is invalid:"
11737 #. type: Plain text
11738 #: build/C/man3/setbuf.3:199
11740 msgid "#include E<lt>stdio.hE<gt>\n"
11743 #. type: Plain text
11744 #: build/C/man3/setbuf.3:208
11750 " char buf[BUFSIZ];\n"
11751 " setbuf(stdin, buf);\n"
11752 " printf(\"Hello, world!\\en\");\n"
11757 #. type: Plain text
11758 #: build/C/man3/setbuf.3:217
11760 "B<fclose>(3), B<fflush>(3), B<fopen>(3), B<fread>(3), B<malloc>(3), "
11761 "B<printf>(3), B<puts>(3)"
11765 #: build/C/man3/stdin.3:13
11771 #: build/C/man3/stdin.3:13 build/C/man3/tmpfile.3:31
11776 #. type: Plain text
11777 #: build/C/man3/stdin.3:16
11778 msgid "stdin, stdout, stderr - standard I/O streams"
11781 #. type: Plain text
11782 #: build/C/man3/stdin.3:23
11785 "B<extern FILE *>I<stdin>B<;>\n"
11786 "B<extern FILE *>I<stdout>B<;>\n"
11787 "B<extern FILE *>I<stderr>B<;>\n"
11790 #. type: Plain text
11791 #: build/C/man3/stdin.3:35
11793 "Under normal circumstances every UNIX program has three streams opened for "
11794 "it when it starts up, one for input, one for output, and one for printing "
11795 "diagnostic or error messages. These are typically attached to the user's "
11796 "terminal (see B<tty>(4) but might instead refer to files or other devices, "
11797 "depending on what the parent process chose to set up. (See also the "
11798 "\"Redirection\" section of B<sh>(1).)"
11801 #. type: Plain text
11802 #: build/C/man3/stdin.3:45
11804 "The input stream is referred to as \"standard input\"; the output stream is "
11805 "referred to as \"standard output\"; and the error stream is referred to as "
11806 "\"standard error\". These terms are abbreviated to form the symbols used to "
11807 "refer to these files, namely I<stdin>, I<stdout>, and I<stderr>."
11810 #. type: Plain text
11811 #: build/C/man3/stdin.3:54
11813 "Each of these symbols is a B<stdio>(3) macro of type pointer to I<FILE>, "
11814 "and can be used with functions like B<fprintf>(3) or B<fread>(3)."
11817 #. type: Plain text
11818 #: build/C/man3/stdin.3:63
11820 "Since I<FILE>s are a buffering wrapper around UNIX file descriptors, the "
11821 "same underlying files may also be accessed using the raw UNIX file "
11822 "interface, that is, the functions like B<read>(2) and B<lseek>(2)."
11825 #. type: Plain text
11826 #: build/C/man3/stdin.3:82
11828 "On program startup, the integer file descriptors associated with the streams "
11829 "I<stdin>, I<stdout>, and I<stderr> are 0, 1, and 2, respectively. The "
11830 "preprocessor symbols B<STDIN_FILENO>, B<STDOUT_FILENO>, and B<STDERR_FILENO> "
11831 "are defined with these values in I<E<lt>unistd.hE<gt>>. (Applying "
11832 "B<freopen>(3) to one of these streams can change the file descriptor number "
11833 "associated with the stream.)"
11836 #. type: Plain text
11837 #: build/C/man3/stdin.3:95
11839 "Note that mixing use of I<FILE>s and raw file descriptors can produce "
11840 "unexpected results and should generally be avoided. (For the masochistic "
11841 "among you: POSIX.1, section 8.2.3, describes in detail how this interaction "
11842 "is supposed to work.) A general rule is that file descriptors are handled "
11843 "in the kernel, while stdio is just a library. This means for example, that "
11844 "after an B<exec>(3), the child inherits all open file descriptors, but all "
11845 "old streams have become inaccessible."
11848 #. type: Plain text
11849 #: build/C/man3/stdin.3:113
11851 "Since the symbols I<stdin>, I<stdout>, and I<stderr> are specified to be "
11852 "macros, assigning to them is nonportable. The standard streams can be made "
11853 "to refer to different files with help of the library function B<freopen>(3), "
11854 "specially introduced to make it possible to reassign I<stdin>, I<stdout>, "
11855 "and I<stderr>. The standard streams are closed by a call to B<exit>(3) and "
11856 "by normal program termination."
11859 #. type: Plain text
11860 #: build/C/man3/stdin.3:122
11862 "The I<stdin>, I<stdout>, and I<stderr> macros conform to C89 and this "
11863 "standard also stipulates that these three streams shall be open at program "
11867 #. type: Plain text
11868 #: build/C/man3/stdin.3:154
11870 "The stream I<stderr> is unbuffered. The stream I<stdout> is line-buffered "
11871 "when it points to a terminal. Partial lines will not appear until "
11872 "B<fflush>(3) or B<exit>(3) is called, or a newline is printed. This can "
11873 "produce unexpected results, especially with debugging output. The buffering "
11874 "mode of the standard streams (or any other stream) can be changed using the "
11875 "B<setbuf>(3) or B<setvbuf>(3) call. Note that in case I<stdin> is "
11876 "associated with a terminal, there may also be input buffering in the "
11877 "terminal driver, entirely unrelated to stdio buffering. (Indeed, normally "
11878 "terminal input is line buffered in the kernel.) This kernel input handling "
11879 "can be modified using calls like B<tcsetattr>(3); see also B<stty>(1), and "
11883 #. type: Plain text
11884 #: build/C/man3/stdin.3:160
11885 msgid "B<csh>(1), B<sh>(1), B<open>(2), B<fopen>(3), B<stdio>(3)"
11889 #: build/C/man3/stdio.3:39
11895 #: build/C/man3/stdio.3:39
11900 #. type: Plain text
11901 #: build/C/man3/stdio.3:42
11902 msgid "stdio - standard input/output library functions"
11905 #. type: Plain text
11906 #: build/C/man3/stdio.3:46
11907 msgid "B<FILE *>I<stdin>B<;>"
11910 #. type: Plain text
11911 #: build/C/man3/stdio.3:48
11912 msgid "B<FILE *>I<stdout>B<;>"
11915 #. type: Plain text
11916 #: build/C/man3/stdio.3:50
11917 msgid "B<FILE *>I<stderr>B<;>"
11920 #. type: Plain text
11921 #: build/C/man3/stdio.3:57
11923 "The standard I/O library provides a simple and efficient buffered stream I/O "
11924 "interface. Input and output is mapped into logical data streams and the "
11925 "physical I/O characteristics are concealed. The functions and macros are "
11926 "listed below; more information is available from the individual man pages."
11929 #. type: Plain text
11930 #: build/C/man3/stdio.3:80
11932 "A stream is associated with an external file (which may be a physical "
11933 "device) by I<opening> a file, which may involve creating a new file. "
11934 "Creating an existing file causes its former contents to be discarded. If a "
11935 "file can support positioning requests (such as a disk file, as opposed to a "
11936 "terminal), then a I<file position indicator> associated with the stream is "
11937 "positioned at the start of the file (byte zero), unless the file is opened "
11938 "with append mode. If append mode is used, it is unspecified whether the "
11939 "position indicator will be placed at the start or the end of the file. The "
11940 "position indicator is maintained by subsequent reads, writes and positioning "
11941 "requests. All input occurs as if the characters were read by successive "
11942 "calls to the B<fgetc>(3) function; all output takes place as if all "
11943 "characters were written by successive calls to the B<fputc>(3) function."
11946 #. type: Plain text
11947 #: build/C/man3/stdio.3:90
11949 "A file is disassociated from a stream by I<closing> the file. Output "
11950 "streams are flushed (any unwritten buffer contents are transferred to the "
11951 "host environment) before the stream is disassociated from the file. The "
11952 "value of a pointer to a I<FILE> object is indeterminate after a file is "
11953 "closed (garbage)."
11956 #. type: Plain text
11957 #: build/C/man3/stdio.3:103
11959 "A file may be subsequently reopened, by the same or another program "
11960 "execution, and its contents reclaimed or modified (if it can be repositioned "
11961 "at the start). If the main function returns to its original caller, or the "
11962 "B<exit>(3) function is called, all open files are closed (hence all output "
11963 "streams are flushed) before program termination. Other methods of program "
11964 "termination, such as B<abort>(3) do not bother about closing files "
11968 #. type: Plain text
11969 #: build/C/man3/stdio.3:119
11971 "At program startup, three text streams are predefined and need not be opened "
11972 "explicitly: I<standard input> (for reading conventional input), I<standard "
11973 "output> (for writing conventional output), and I<standard error> (for "
11974 "writing diagnostic output). These streams are abbreviated "
11975 "I<stdin>,I<stdout> and I<stderr>. When opened, the standard error stream is "
11976 "not fully buffered; the standard input and output streams are fully buffered "
11977 "if and only if the streams do not refer to an interactive device."
11980 #. type: Plain text
11981 #: build/C/man3/stdio.3:129
11983 "Output streams that refer to terminal devices are always line buffered by "
11984 "default; pending output to such streams is written automatically whenever an "
11985 "input stream that refers to a terminal device is read. In cases where a "
11986 "large amount of computation is done after printing part of a line on an "
11987 "output terminal, it is necessary to B<fflush>(3) the standard output before "
11988 "going off and computing so that the output will appear."
11991 #. type: Plain text
11992 #: build/C/man3/stdio.3:143
11994 "The I<stdio> library is a part of the library B<libc> and routines are "
11995 "automatically loaded as needed by the compilers B<cc>(1) and B<pc>(1). The "
11996 "SYNOPSIS sections of the following manual pages indicate which include files "
11997 "are to be used, what the compiler declaration for the function looks like "
11998 "and which external variables are of interest."
12001 #. Not on Linux: .BR fropen ,
12002 #. Not on Linux: .BR fwopen ,
12003 #. type: Plain text
12004 #: build/C/man3/stdio.3:183
12006 "The following are defined as macros; these names may not be reused without "
12007 "first removing their current definitions with B<#undef>: B<BUFSIZ>, B<EOF>, "
12008 "B<FILENAME_MAX>, B<FOPEN_MAX>, B<L_cuserid>, B<L_ctermid>, B<L_tmpnam>, "
12009 "B<NULL>, B<SEEK_END>, B<SEEK_SET>, B<SEEK_CUR>, B<TMP_MAX>, B<clearerr>, "
12010 "B<feof>, B<ferror>, B<fileno>, B<getc>, B<getchar>, B<putc>, B<putchar>, "
12011 "B<stderr>, B<stdin>, B<stdout>. Function versions of the macro functions "
12012 "B<feof>, B<ferror>, B<clearerr>, B<fileno>, B<getc>, B<getchar>, B<putc>, "
12013 "and B<putchar> exist and will be used if the macros definitions are "
12014 "explicitly removed."
12018 #: build/C/man3/stdio.3:183
12020 msgid "List of functions"
12024 #: build/C/man3/stdio.3:188
12026 msgid "Function\tDescription\n"
12030 #: build/C/man3/stdio.3:189
12036 #: build/C/man3/stdio.3:190
12038 msgid "clearerr\tcheck and reset stream status\n"
12042 #: build/C/man3/stdio.3:191
12044 msgid "fclose\tclose a stream\n"
12048 #: build/C/man3/stdio.3:192
12050 msgid "fdopen\tstream open functions\n"
12054 #: build/C/man3/stdio.3:193
12056 msgid "feof\tcheck and reset stream status\n"
12060 #: build/C/man3/stdio.3:194
12062 msgid "ferror\tcheck and reset stream status\n"
12066 #: build/C/man3/stdio.3:195
12068 msgid "fflush\tflush a stream\n"
12072 #: build/C/man3/stdio.3:196
12074 msgid "fgetc\tget next character or word from input stream\n"
12078 #: build/C/man3/stdio.3:197
12080 msgid "fgetpos\treposition a stream\n"
12084 #: build/C/man3/stdio.3:198
12086 msgid "fgets\tget a line from a stream\n"
12090 #: build/C/man3/stdio.3:199
12092 msgid "fileno\treturn the integer descriptor of the argument stream\n"
12096 #: build/C/man3/stdio.3:200
12098 msgid "fopen\tstream open functions\n"
12102 #: build/C/man3/stdio.3:201
12104 msgid "fprintf\tformatted output conversion\n"
12108 #: build/C/man3/stdio.3:202
12110 msgid "fpurge\tflush a stream\n"
12114 #: build/C/man3/stdio.3:203
12116 msgid "fputc\toutput a character or word to a stream\n"
12120 #: build/C/man3/stdio.3:204
12122 msgid "fputs\toutput a line to a stream\n"
12126 #: build/C/man3/stdio.3:205
12128 msgid "fread\tbinary stream input/output\n"
12132 #: build/C/man3/stdio.3:206
12134 msgid "freopen\tstream open functions\n"
12138 #: build/C/man3/stdio.3:207
12140 msgid "fscanf\tinput format conversion\n"
12144 #: build/C/man3/stdio.3:208
12146 msgid "fseek\treposition a stream\n"
12150 #: build/C/man3/stdio.3:209
12152 msgid "fsetpos\treposition a stream\n"
12156 #: build/C/man3/stdio.3:210
12158 msgid "ftell\treposition a stream\n"
12162 #: build/C/man3/stdio.3:211
12164 msgid "fwrite\tbinary stream input/output\n"
12168 #: build/C/man3/stdio.3:212
12170 msgid "getc\tget next character or word from input stream\n"
12174 #: build/C/man3/stdio.3:213
12176 msgid "getchar\tget next character or word from input stream\n"
12180 #: build/C/man3/stdio.3:214
12182 msgid "gets\tget a line from a stream\n"
12186 #: build/C/man3/stdio.3:215
12188 msgid "getw\tget next character or word from input stream\n"
12192 #: build/C/man3/stdio.3:216
12194 msgid "mktemp\tmake temporary filename (unique)\n"
12198 #: build/C/man3/stdio.3:217
12200 msgid "perror\tsystem error messages\n"
12204 #: build/C/man3/stdio.3:218
12206 msgid "printf\tformatted output conversion\n"
12210 #: build/C/man3/stdio.3:219
12212 msgid "putc\toutput a character or word to a stream\n"
12216 #: build/C/man3/stdio.3:220
12218 msgid "putchar\toutput a character or word to a stream\n"
12222 #: build/C/man3/stdio.3:221
12224 msgid "puts\toutput a line to a stream\n"
12228 #: build/C/man3/stdio.3:222
12230 msgid "putw\toutput a character or word to a stream\n"
12234 #: build/C/man3/stdio.3:223
12236 msgid "remove\tremove directory entry\n"
12240 #: build/C/man3/stdio.3:224
12242 msgid "rewind\treposition a stream\n"
12246 #: build/C/man3/stdio.3:225
12248 msgid "scanf\tinput format conversion\n"
12252 #: build/C/man3/stdio.3:226
12254 msgid "setbuf\tstream buffering operations\n"
12258 #: build/C/man3/stdio.3:227
12260 msgid "setbuffer\tstream buffering operations\n"
12264 #: build/C/man3/stdio.3:228
12266 msgid "setlinebuf\tstream buffering operations\n"
12270 #: build/C/man3/stdio.3:229
12272 msgid "setvbuf\tstream buffering operations\n"
12276 #: build/C/man3/stdio.3:230
12278 msgid "sprintf\tformatted output conversion\n"
12282 #: build/C/man3/stdio.3:231
12284 msgid "sscanf\tinput format conversion\n"
12288 #: build/C/man3/stdio.3:232
12290 msgid "strerror\tsystem error messages\n"
12294 #: build/C/man3/stdio.3:233
12296 msgid "sys_errlist\tsystem error messages\n"
12300 #: build/C/man3/stdio.3:234
12302 msgid "sys_nerr\tsystem error messages\n"
12306 #: build/C/man3/stdio.3:235
12308 msgid "tempnam\ttemporary file routines\n"
12312 #: build/C/man3/stdio.3:236
12314 msgid "tmpfile\ttemporary file routines\n"
12318 #: build/C/man3/stdio.3:237
12320 msgid "tmpnam\ttemporary file routines\n"
12324 #: build/C/man3/stdio.3:238
12326 msgid "ungetc\tun-get character from input stream\n"
12330 #: build/C/man3/stdio.3:239
12332 msgid "vfprintf\tformatted output conversion\n"
12336 #: build/C/man3/stdio.3:240
12338 msgid "vfscanf\tinput format conversion\n"
12342 #: build/C/man3/stdio.3:241
12344 msgid "vprintf\tformatted output conversion\n"
12348 #: build/C/man3/stdio.3:242
12350 msgid "vscanf\tinput format conversion\n"
12354 #: build/C/man3/stdio.3:243
12356 msgid "vsprintf\tformatted output conversion\n"
12360 #: build/C/man3/stdio.3:244
12362 msgid "vsscanf\tinput format conversion\n"
12365 #. type: Plain text
12366 #: build/C/man3/stdio.3:250
12367 msgid "The I<stdio> library conforms to C89."
12370 #. type: Plain text
12371 #: build/C/man3/stdio.3:257
12373 "B<close>(2), B<open>(2), B<read>(2), B<write>(2), B<stdout>(3), "
12374 "B<unlocked_stdio>(3)"
12378 #: build/C/man3/stdio_ext.3:25
12383 #. type: Plain text
12384 #: build/C/man3/stdio_ext.3:30
12386 "__fbufsize, __flbf, __fpending, __fpurge, __freadable, __freading, "
12387 "__fsetlocking, __fwritable, __fwriting, _flushlbf - interfaces to stdio FILE "
12391 #. type: Plain text
12392 #: build/C/man3/stdio_ext.3:34
12393 msgid "B<#include E<lt>stdio_ext.hE<gt>>"
12396 #. type: Plain text
12397 #: build/C/man3/stdio_ext.3:36
12398 msgid "B<size_t __fbufsize(FILE *>I<stream>B<);>"
12401 #. type: Plain text
12402 #: build/C/man3/stdio_ext.3:38
12403 msgid "B<size_t __fpending(FILE *>I<stream>B<);>"
12406 #. type: Plain text
12407 #: build/C/man3/stdio_ext.3:40
12408 msgid "B<int __flbf(FILE *>I<stream>B<);>"
12411 #. type: Plain text
12412 #: build/C/man3/stdio_ext.3:42
12413 msgid "B<int __freadable(FILE *>I<stream>B<);>"
12416 #. type: Plain text
12417 #: build/C/man3/stdio_ext.3:44
12418 msgid "B<int __fwritable(FILE *>I<stream>B<);>"
12421 #. type: Plain text
12422 #: build/C/man3/stdio_ext.3:46
12423 msgid "B<int __freading(FILE *>I<stream>B<);>"
12426 #. type: Plain text
12427 #: build/C/man3/stdio_ext.3:48
12428 msgid "B<int __fwriting(FILE *>I<stream>B<);>"
12431 #. type: Plain text
12432 #: build/C/man3/stdio_ext.3:50
12433 msgid "B<int __fsetlocking(FILE *>I<stream>B<, int >I<type>B<);>"
12436 #. type: Plain text
12437 #: build/C/man3/stdio_ext.3:52
12438 msgid "B<void _flushlbf(void);>"
12441 #. type: Plain text
12442 #: build/C/man3/stdio_ext.3:54
12443 msgid "B<void __fpurge(FILE *>I<stream>B<);>"
12446 #. type: Plain text
12447 #: build/C/man3/stdio_ext.3:59
12449 "Solaris introduced routines to allow portable access to the internals of the "
12450 "I<FILE> structure, and glibc also implemented these."
12453 #. type: Plain text
12454 #: build/C/man3/stdio_ext.3:64
12456 "The B<__fbufsize>() function returns the size of the buffer currently used "
12457 "by the given stream."
12460 #. type: Plain text
12461 #: build/C/man3/stdio_ext.3:71
12463 "The B<__fpending>() function returns the number of bytes in the output "
12464 "buffer. For wide-oriented streams the unit is wide characters. This "
12465 "function is undefined on buffers in reading mode, or opened read-only."
12468 #. type: Plain text
12469 #: build/C/man3/stdio_ext.3:76
12471 "The B<__flbf>() function returns a nonzero value if the stream is "
12472 "line-buffered, and zero otherwise."
12475 #. type: Plain text
12476 #: build/C/man3/stdio_ext.3:81
12478 "The B<__freadable>() function returns a nonzero value if the stream allows "
12479 "reading, and zero otherwise."
12482 #. type: Plain text
12483 #: build/C/man3/stdio_ext.3:86
12485 "The B<__fwritable>() function returns a nonzero value if the stream allows "
12486 "writing, and zero otherwise."
12489 #. type: Plain text
12490 #: build/C/man3/stdio_ext.3:92
12492 "The B<__freading>() function returns a nonzero value if the stream is "
12493 "read-only, or if the last operation on the stream was a read operation, and "
12497 #. type: Plain text
12498 #: build/C/man3/stdio_ext.3:98
12500 "The B<__fwriting>() function returns a nonzero value if the stream is "
12501 "write-only (or append-only), or if the last operation on the stream was a "
12502 "write operation, and zero otherwise."
12505 #. type: Plain text
12506 #: build/C/man3/stdio_ext.3:106
12508 "The B<__fsetlocking>() function can be used to select the desired type of "
12509 "locking on the stream. It returns the current type. The I<type> argument "
12510 "can take the following three values:"
12514 #: build/C/man3/stdio_ext.3:106
12516 msgid "B<FSETLOCKING_INTERNAL>"
12519 #. type: Plain text
12520 #: build/C/man3/stdio_ext.3:111
12522 "Perform implicit locking around every operation on the given stream (except "
12523 "for the *_unlocked ones). This is the default."
12527 #: build/C/man3/stdio_ext.3:111
12529 msgid "B<FSETLOCKING_BYCALLER>"
12532 #. type: Plain text
12533 #: build/C/man3/stdio_ext.3:118
12535 "The caller will take care of the locking (possibly using B<flockfile>(3) in "
12536 "case there is more than one thread), and the stdio routines will not do "
12537 "locking until the state is reset to B<FSETLOCKING_INTERNAL>."
12541 #: build/C/man3/stdio_ext.3:118
12543 msgid "B<FSETLOCKING_QUERY>"
12546 #. type: Plain text
12547 #: build/C/man3/stdio_ext.3:122
12548 msgid "Don't change the type of locking. (Only return it.)"
12551 #. type: Plain text
12552 #: build/C/man3/stdio_ext.3:128
12554 "The B<_flushlbf>() function flushes all line-buffered streams. (Presumably "
12555 "so that output to a terminal is forced out, say before reading keyboard "
12559 #. type: Plain text
12560 #: build/C/man3/stdio_ext.3:132
12561 msgid "The B<__fpurge>() function discards the contents of the stream's buffer."
12564 #. type: Plain text
12565 #: build/C/man3/stdio_ext.3:141
12567 "The B<__fbufsize>(), B<__fpending>(), B<__fpurge>() and B<__fsetlocking>() "
12568 "functions do not lock the stream, so they are not thread-safe."
12571 #. type: Plain text
12572 #: build/C/man3/stdio_ext.3:151
12574 "The B<__flbf>(), B<__freadable>(), B<__freading>(), B<__fwritable>(), "
12575 "B<__fwriting>() and B<_flushlbf>() functions are thread-safe."
12578 #. type: Plain text
12579 #: build/C/man3/stdio_ext.3:154
12580 msgid "B<flockfile>(3), B<fpurge>(3)"
12584 #: build/C/man2/symlink.2:33 build/C/man7/symlink.7:37
12589 #. type: Plain text
12590 #: build/C/man2/symlink.2:36
12591 msgid "symlink, symlinkat - make a new name for a file"
12594 #. type: Plain text
12595 #: build/C/man2/symlink.2:41
12597 msgid "B<int symlink(const char *>I<target>B<, const char *>I<linkpath>B<);>\n"
12600 #. type: Plain text
12601 #: build/C/man2/symlink.2:47
12604 "B<int symlinkat(const char *>I<target>B<, int >I<newdirfd>B<, const char "
12605 "*>I<linkpath>B<);>\n"
12608 #. type: Plain text
12609 #: build/C/man2/symlink.2:56
12610 msgid "B<symlink>():"
12613 #. type: Plain text
12614 #: build/C/man2/symlink.2:62
12615 msgid "B<symlinkat>():"
12618 #. type: Plain text
12619 #: build/C/man2/symlink.2:80
12621 "B<symlink>() creates a symbolic link named I<linkpath> which contains the "
12622 "string I<target>."
12625 #. type: Plain text
12626 #: build/C/man2/symlink.2:84
12628 "Symbolic links are interpreted at run time as if the contents of the link "
12629 "had been substituted into the path being followed to find a file or "
12633 #. type: Plain text
12634 #: build/C/man2/symlink.2:89
12636 "Symbolic links may contain I<..> path components, which (if used at the "
12637 "start of the link) refer to the parent directories of that in which the link "
12641 #. type: Plain text
12642 #: build/C/man2/symlink.2:93
12644 "A symbolic link (also known as a soft link) may point to an existing file or "
12645 "to a nonexistent one; the latter case is known as a dangling link."
12648 #. type: Plain text
12649 #: build/C/man2/symlink.2:100
12651 "The permissions of a symbolic link are irrelevant; the ownership is ignored "
12652 "when following the link, but is checked when removal or renaming of the link "
12653 "is requested and the link is in a directory with the sticky bit (B<S_ISVTX>) "
12657 #. type: Plain text
12658 #: build/C/man2/symlink.2:106
12659 msgid "If I<linkpath> exists, it will I<not> be overwritten."
12663 #: build/C/man2/symlink.2:106
12665 msgid "symlinkat()"
12668 #. type: Plain text
12669 #: build/C/man2/symlink.2:112
12671 "The B<symlinkat>() system call operates in exactly the same way as "
12672 "B<symlink>(), except for the differences described here."
12675 #. type: Plain text
12676 #: build/C/man2/symlink.2:122
12678 "If the pathname given in I<linkpath> is relative, then it is interpreted "
12679 "relative to the directory referred to by the file descriptor I<newdirfd> "
12680 "(rather than relative to the current working directory of the calling "
12681 "process, as is done by B<symlink>() for a relative pathname)."
12684 #. type: Plain text
12685 #: build/C/man2/symlink.2:134
12687 "If I<linkpath> is relative and I<newdirfd> is the special value B<AT_FDCWD>, "
12688 "then I<linkpath> is interpreted relative to the current working directory of "
12689 "the calling process (like B<symlink>())."
12692 #. type: Plain text
12693 #: build/C/man2/symlink.2:140
12694 msgid "If I<linkpath> is absolute, then I<newdirfd> is ignored."
12697 #. type: Plain text
12698 #: build/C/man2/symlink.2:155
12700 "Write access to the directory containing I<linkpath> is denied, or one of "
12701 "the directories in the path prefix of I<linkpath> did not allow search "
12702 "permission. (See also B<path_resolution>(7).)"
12705 #. type: Plain text
12706 #: build/C/man2/symlink.2:160
12708 "The user's quota of resources on the filesystem has been exhausted. The "
12709 "resources could be inodes or disk blocks, depending on the filesystem "
12713 #. type: Plain text
12714 #: build/C/man2/symlink.2:164
12715 msgid "I<linkpath> already exists."
12718 #. type: Plain text
12719 #: build/C/man2/symlink.2:167
12720 msgid "I<target> or I<linkpath> points outside your accessible address space."
12723 #. type: Plain text
12724 #: build/C/man2/symlink.2:174
12725 msgid "Too many symbolic links were encountered in resolving I<linkpath>."
12728 #. type: Plain text
12729 #: build/C/man2/symlink.2:177
12730 msgid "I<target> or I<linkpath> was too long."
12733 #. type: Plain text
12734 #: build/C/man2/symlink.2:184
12736 "A directory component in I<linkpath> does not exist or is a dangling "
12737 "symbolic link, or I<target> is the empty string."
12740 #. type: Plain text
12741 #: build/C/man2/symlink.2:196
12742 msgid "A component used as a directory in I<linkpath> is not, in fact, a directory."
12745 #. type: Plain text
12746 #: build/C/man2/symlink.2:201
12748 "The filesystem containing I<linkpath> does not support the creation of "
12752 #. type: Plain text
12753 #: build/C/man2/symlink.2:205
12754 msgid "I<linkpath> is on a read-only filesystem."
12757 #. type: Plain text
12758 #: build/C/man2/symlink.2:208
12759 msgid "The following additional errors can occur for B<symlinkat>():"
12762 #. type: Plain text
12763 #: build/C/man2/symlink.2:212
12764 msgid "I<newdirfd> is not a valid file descriptor."
12767 #. type: Plain text
12768 #: build/C/man2/symlink.2:218
12770 "I<linkpath> is a relative pathname and I<newdirfd> refers to a directory "
12771 "that has been deleted."
12774 #. type: Plain text
12775 #: build/C/man2/symlink.2:224
12777 "I<linkpath> is relative and I<newdirfd> is a file descriptor referring to a "
12778 "file other than a directory."
12781 #. type: Plain text
12782 #: build/C/man2/symlink.2:228
12784 "B<symlinkat>() was added to Linux in kernel 2.6.16; library support was "
12785 "added to glibc in version 2.4."
12788 #. SVr4 documents additional error codes EDQUOT and ENOSYS.
12791 #. re multiple files with the same name, and NFS.
12792 #. type: Plain text
12793 #: build/C/man2/symlink.2:235
12794 msgid "B<symlink>(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008."
12797 #. type: Plain text
12798 #: build/C/man2/symlink.2:238
12799 msgid "B<symlinkat>(): POSIX.1-2008."
12802 #. type: Plain text
12803 #: build/C/man2/symlink.2:242
12804 msgid "No checking of I<target> is done."
12807 #. type: Plain text
12808 #: build/C/man2/symlink.2:247
12810 "Deleting the name referred to by a symbolic link will actually delete the "
12811 "file (unless it also has other hard links). If this behavior is not "
12812 "desired, use B<link>(2)."
12815 #. type: Plain text
12816 #: build/C/man2/symlink.2:260
12818 "On older kernels where B<symlinkat>() is unavailable, the glibc wrapper "
12819 "function falls back to the use of B<symlink>(2). When I<linkpath> is a "
12820 "relative pathname, glibc constructs a pathname based on the symbolic link in "
12821 "I</proc/self/fd> that corresponds to the I<newdirfd> argument."
12824 #. type: Plain text
12825 #: build/C/man2/symlink.2:271
12827 "B<ln>(1), B<lchown>(2), B<link>(2), B<lstat>(2), B<open>(2), B<readlink>(2), "
12828 "B<rename>(2), B<unlink>(2), B<path_resolution>(7), B<symlink>(7)"
12832 #: build/C/man7/symlink.7:37
12837 #. type: Plain text
12838 #: build/C/man7/symlink.7:40
12839 msgid "symlink - symbolic link handling"
12842 #. type: Plain text
12843 #: build/C/man7/symlink.7:44
12845 "Symbolic links are files that act as pointers to other files. To understand "
12846 "their behavior, you must first understand how hard links work."
12849 #. type: Plain text
12850 #: build/C/man7/symlink.7:60
12852 "A hard link to a file is indistinguishable from the original file because it "
12853 "is a reference to the object underlying the original filename. (To be "
12854 "precise: each of the hard links to a file is a reference to the same I<inode "
12855 "number>, where an inode number is an index into the inode table, which "
12856 "contains metadata about all files on a filesystem. See B<stat>(2).) "
12857 "Changes to a file are independent of the name used to reference the file. "
12858 "Hard links may not refer to directories (to prevent the possibility of loops "
12859 "within the filesystem tree, which would confuse many programs) and may not "
12860 "refer to files on different filesystems (because inode numbers are not "
12861 "unique across filesystems)."
12864 #. type: Plain text
12865 #: build/C/man7/symlink.7:69
12867 "A symbolic link is a special type of file whose contents are a string that "
12868 "is the pathname of another file, the file to which the link refers. (The "
12869 "contents of a symbolic link can be read using B<readlink>(2).) In other "
12870 "words, a symbolic link is a pointer to another name, and not to an "
12871 "underlying object. For this reason, symbolic links may refer to directories "
12872 "and may cross filesystem boundaries."
12875 #. type: Plain text
12876 #: build/C/man7/symlink.7:75
12878 "There is no requirement that the pathname referred to by a symbolic link "
12879 "should exist. A symbolic link that refers to a pathname that does not exist "
12880 "is said to be a I<dangling link>."
12883 #. type: Plain text
12884 #: build/C/man7/symlink.7:87
12886 "Because a symbolic link and its referenced object coexist in the filesystem "
12887 "name space, confusion can arise in distinguishing between the link itself "
12888 "and the referenced object. On historical systems, commands and system calls "
12889 "adopted their own link-following conventions in a somewhat ad-hoc fashion. "
12890 "Rules for a more uniform approach, as they are implemented on Linux and "
12891 "other systems, are outlined here. It is important that site-local "
12892 "applications also conform to these rules, so that the user interface can be "
12893 "as consistent as possible."
12897 #: build/C/man7/symlink.7:87
12899 msgid "Symbolic link ownership, permissions, and timestamps"
12902 #. type: Plain text
12903 #: build/C/man7/symlink.7:95
12905 "The owner and group of an existing symbolic link can be changed using "
12906 "B<lchown>(2). The only time that the ownership of a symbolic link matters "
12907 "is when the link is being removed or renamed in a directory that has the "
12908 "sticky bit set (see B<stat>(2))."
12911 #. type: Plain text
12912 #: build/C/man7/symlink.7:101
12914 "The last access and last modification timestamps of a symbolic link can be "
12915 "changed using B<utimensat>(2) or B<lutimes>(3)."
12918 #. Linux does not currently implement an lchmod(2).
12922 #. system differs from historical
12924 #. systems in that the system call
12926 #. has been changed to follow symbolic links.
12929 #. system call was added later when the limitations of the new
12931 #. became apparent.
12932 #. type: Plain text
12933 #: build/C/man7/symlink.7:120
12935 "On Linux, the permissions of a symbolic link are not used in any operations; "
12936 "the permissions are always 0777 (read, write, and execute for all user "
12937 "categories), and can't be changed."
12941 #: build/C/man7/symlink.7:120
12943 msgid "Obtaining a file descriptor that refers to a symbolic link"
12946 #. type: Plain text
12947 #: build/C/man7/symlink.7:138
12949 "Using the combination of the B<O_PATH> and B<O_NOFOLLOW> flags to B<open>(2) "
12950 "yields a file descriptor that can be passed as the I<dirfd> argument in "
12951 "system calls such as B<fstatat>(2), B<fchownat>(2), B<fchmodat>(2), "
12952 "B<linkat>(2), and B<readlinkat>(2), in order to operate on the symbolic link "
12953 "itself (rather than the file to which it refers)."
12956 #. type: Plain text
12957 #: build/C/man7/symlink.7:154
12959 "By default (i.e., if the B<AT_SYMLINK_FOLLOW> flag is not specified), if "
12960 "B<name_to_handle_at>(2) is applied to a symbolic link, it yields a handle "
12961 "for the symbolic link (rather than the file to which it refers). One can "
12962 "then obtain a file descriptor for the symbolic link (rather than the file to "
12963 "which it refers) by specifying the B<O_PATH> flag in a subsequent call to "
12964 "B<open_by_handle_at>(2). Again, that file descriptor can be used in the "
12965 "aforementioned system calls to operate on the symbolic link itself."
12969 #: build/C/man7/symlink.7:154
12971 msgid "Handling of symbolic links by system calls and commands"
12974 #. type: Plain text
12975 #: build/C/man7/symlink.7:169
12977 "Symbolic links are handled either by operating on the link itself, or by "
12978 "operating on the object referred to by the link. In the latter case, an "
12979 "application or system call is said to I<follow> the link. Symbolic links "
12980 "may refer to other symbolic links, in which case the links are dereferenced "
12981 "until an object that is not a symbolic link is found, a symbolic link that "
12982 "refers to a file which does not exist is found, or a loop is detected. "
12983 "(Loop detection is done by placing an upper limit on the number of links "
12984 "that may be followed, and an error results if this limit is exceeded.)"
12987 #. type: Plain text
12988 #: build/C/man7/symlink.7:172
12990 "There are three separate areas that need to be discussed. They are as "
12995 #: build/C/man7/symlink.7:172
13000 #. type: Plain text
13001 #: build/C/man7/symlink.7:174
13002 msgid "Symbolic links used as filename arguments for system calls."
13006 #: build/C/man7/symlink.7:174
13011 #. type: Plain text
13012 #: build/C/man7/symlink.7:177
13014 "Symbolic links specified as command-line arguments to utilities that are not "
13015 "traversing a file tree."
13019 #: build/C/man7/symlink.7:177
13024 #. type: Plain text
13025 #: build/C/man7/symlink.7:181
13027 "Symbolic links encountered by utilities that are traversing a file tree "
13028 "(either specified on the command line or encountered as part of the file "
13033 #: build/C/man7/symlink.7:181
13035 msgid "System calls"
13038 #. type: Plain text
13039 #: build/C/man7/symlink.7:184
13041 "The first area is symbolic links used as filename arguments for system "
13045 #. type: Plain text
13046 #: build/C/man7/symlink.7:194
13048 "Except as noted below, all system calls follow symbolic links. For example, "
13049 "if there were a symbolic link I<slink> which pointed to a file named "
13050 "I<afile>, the system call I<open(\"slink\" ...\\&)> would return a file "
13051 "descriptor referring to the file I<afile>."
13054 #. type: Plain text
13055 #: build/C/man7/symlink.7:209
13057 "Various system calls do not follow links, and operate on the symbolic link "
13058 "itself. They are: B<lchown>(2), B<lgetxattr>(2), B<llistxattr>(2), "
13059 "B<lremovexattr>(2), B<lsetxattr>(2), B<lstat>(2), B<readlink>(2), "
13060 "B<rename>(2), B<rmdir>(2), and B<unlink>(2)."
13063 #. Maybe one day: .BR fchownat (2)
13064 #. type: Plain text
13065 #: build/C/man7/symlink.7:233
13067 "Certain other system calls optionally follow symbolic links. They are: "
13068 "B<faccessat>(2), B<fchownat>(2), B<fstatat>(2), B<linkat>(2), "
13069 "B<name_to_handle_at>(2), B<open>(2), B<openat>(2), B<open_by_handle_at>(2), "
13070 "and B<utimensat>(2); see their manual pages for details. Because "
13071 "B<remove>(3) is an alias for B<unlink>(2), that library function also does "
13072 "not follow symbolic links. When B<rmdir>(2) is applied to a symbolic link, "
13073 "it fails with the error B<ENOTDIR>."
13076 #. type: Plain text
13077 #: build/C/man7/symlink.7:248
13079 "The B<link>(2) warrants special discussion. POSIX.1-2001 specifies that "
13080 "B<link>(2) should dereference I<oldpath> if it is a symbolic link. "
13081 "However, Linux does not do this. (By default Solaris is the same, but the "
13082 "POSIX.1-2001 specified behavior can be obtained with suitable compiler "
13083 "options.) The upcoming POSIX.1 revision changes the specification to allow "
13084 "either behavior in an implementation."
13088 #: build/C/man7/symlink.7:248
13090 msgid "Commands not traversing a file tree"
13093 #. type: Plain text
13094 #: build/C/man7/symlink.7:251
13096 "The second area is symbolic links, specified as command-line filename "
13097 "arguments, to commands which are not traversing a file tree."
13100 #. type: Plain text
13101 #: build/C/man7/symlink.7:262
13103 "Except as noted below, commands follow symbolic links named as command-line "
13104 "arguments. For example, if there were a symbolic link I<slink> which "
13105 "pointed to a file named I<afile>, the command I<cat slink> would display the "
13106 "contents of the file I<afile>."
13109 #. type: Plain text
13110 #: build/C/man7/symlink.7:270
13112 "It is important to realize that this rule includes commands which may "
13113 "optionally traverse file trees; for example, the command I<chown file> is "
13114 "included in this rule, while the command I<chown\\ -R file>, which performs "
13115 "a tree traversal, is not. (The latter is described in the third area, "
13119 #. type: Plain text
13120 #: build/C/man7/symlink.7:288
13122 "If it is explicitly intended that the command operate on the symbolic link "
13123 "instead of following the symbolic link\\(emfor example, it is desired that "
13124 "I<chown slink> change the ownership of the file that I<slink> is, whether it "
13125 "is a symbolic link or not\\(emthe I<-h> option should be used. In the above "
13126 "example, I<chown root slink> would change the ownership of the file referred "
13127 "to by I<slink>, while I<chown\\ -h root slink> would change the ownership of "
13131 #. type: Plain text
13132 #: build/C/man7/symlink.7:290
13133 msgid "There are some exceptions to this rule:"
13136 #. type: Plain text
13137 #: build/C/man7/symlink.7:300
13139 "The B<mv>(1) and B<rm>(1) commands do not follow symbolic links named as "
13140 "arguments, but respectively attempt to rename and delete them. (Note, if "
13141 "the symbolic link references a file via a relative path, moving it to "
13142 "another directory may very well cause it to stop working, since the path may "
13143 "no longer be correct.)"
13146 #. type: Plain text
13147 #: build/C/man7/symlink.7:330
13149 "The B<ls>(1) command is also an exception to this rule. For compatibility "
13150 "with historic systems (when B<ls>(1) is not doing a tree walk\\(emthat is, "
13151 "I<-R> option is not specified), the B<ls>(1) command follows symbolic links "
13152 "named as arguments if the I<-H> or I<-L> option is specified, or if the "
13153 "I<-F>, I<-d>, or I<-l> options are not specified. (The B<ls>(1) command is "
13154 "the only command where the I<-H> and I<-L> options affect its behavior even "
13155 "though it is not doing a walk of a file tree.)"
13159 #. The 4.4BSD system differs from historical 4BSD systems in that the
13163 #. commands follow symbolic links specified on the command line.
13164 #. type: Plain text
13165 #: build/C/man7/symlink.7:348
13167 "The B<file>(1) command is also an exception to this rule. The B<file>(1) "
13168 "command does not follow symbolic links named as argument by default. The "
13169 "B<file>(1) command does follow symbolic links named as argument if the "
13170 "I<-L> option is specified."
13174 #: build/C/man7/symlink.7:348
13176 msgid "Commands traversing a file tree"
13179 #. type: Plain text
13180 #: build/C/man7/symlink.7:361
13182 "The following commands either optionally or always traverse file trees: "
13183 "B<chgrp>(1), B<chmod>(1), B<chown>(1), B<cp>(1), B<du>(1), B<find>(1), "
13184 "B<ls>(1), B<pax>(1), B<rm>(1), and B<tar>(1)."
13187 #. type: Plain text
13188 #: build/C/man7/symlink.7:365
13190 "It is important to realize that the following rules apply equally to "
13191 "symbolic links encountered during the file tree traversal and symbolic links "
13192 "listed as command-line arguments."
13195 #. type: Plain text
13196 #: build/C/man7/symlink.7:370
13198 "The I<first rule> applies to symbolic links that reference files other than "
13199 "directories. Operations that apply to symbolic links are performed on the "
13200 "links themselves, but otherwise the links are ignored."
13203 #. type: Plain text
13204 #: build/C/man7/symlink.7:382
13206 "The command I<rm\\ -r slink directory> will remove I<slink>, as well as any "
13207 "symbolic links encountered in the tree traversal of I<directory>, because "
13208 "symbolic links may be removed. In no case will B<rm>(1) affect the file "
13209 "referred to by I<slink>."
13212 #. type: Plain text
13213 #: build/C/man7/symlink.7:387
13215 "The I<second rule> applies to symbolic links that refer to directories. "
13216 "Symbolic links that refer to directories are never followed by default. "
13217 "This is often referred to as a \"physical\" walk, as opposed to a "
13218 "\"logical\" walk (where symbolic links the refer to directories are "
13222 #. type: Plain text
13223 #: build/C/man7/symlink.7:390
13225 "Certain conventions are (should be) followed as consistently as possible by "
13226 "commands that perform file tree walks:"
13229 #. type: Plain text
13230 #: build/C/man7/symlink.7:403
13232 "A command can be made to follow any symbolic links named on the command "
13233 "line, regardless of the type of file they reference, by specifying the I<-H> "
13234 "(for \"half-logical\") flag. This flag is intended to make the command-line "
13235 "name space look like the logical name space. (Note, for commands that do "
13236 "not always do file tree traversals, the I<-H> flag will be ignored if the "
13237 "I<-R> flag is not also specified.)"
13240 #. type: Plain text
13241 #: build/C/man7/symlink.7:419
13243 "For example, the command I<chown\\ -HR user slink> will traverse the file "
13244 "hierarchy rooted in the file pointed to by I<slink>. Note, the I<-H> is not "
13245 "the same as the previously discussed I<-h> flag. The I<-H> flag causes "
13246 "symbolic links specified on the command line to be dereferenced for the "
13247 "purposes of both the action to be performed and the tree walk, and it is as "
13248 "if the user had specified the name of the file to which the symbolic link "
13252 #. type: Plain text
13253 #: build/C/man7/symlink.7:433
13255 "A command can be made to follow any symbolic links named on the command "
13256 "line, as well as any symbolic links encountered during the traversal, "
13257 "regardless of the type of file they reference, by specifying the I<-L> (for "
13258 "\"logical\") flag. This flag is intended to make the entire name space look "
13259 "like the logical name space. (Note, for commands that do not always do file "
13260 "tree traversals, the I<-L> flag will be ignored if the I<-R> flag is not "
13264 #. type: Plain text
13265 #: build/C/man7/symlink.7:448
13267 "For example, the command I<chown\\ -LR user slink> will change the owner of "
13268 "the file referred to by I<slink>. If I<slink> refers to a directory, "
13269 "B<chown> will traverse the file hierarchy rooted in the directory that it "
13270 "references. In addition, if any symbolic links are encountered in any file "
13271 "tree that B<chown> traverses, they will be treated in the same fashion as "
13275 #. type: Plain text
13276 #: build/C/man7/symlink.7:455
13278 "A command can be made to provide the default behavior by specifying the "
13279 "I<-P> (for \"physical\") flag. This flag is intended to make the entire "
13280 "name space look like the physical name space."
13283 #. type: Plain text
13284 #: build/C/man7/symlink.7:473
13286 "For commands that do not by default do file tree traversals, the I<-H>, "
13287 "I<-L>, and I<-P> flags are ignored if the I<-R> flag is not also specified. "
13288 "In addition, you may specify the I<-H>, I<-L>, and I<-P> options more than "
13289 "once; the last one specified determines the command's behavior. This is "
13290 "intended to permit you to alias commands to behave one way or the other, and "
13291 "then override that behavior on the command line."
13294 #. type: Plain text
13295 #: build/C/man7/symlink.7:479
13296 msgid "The B<ls>(1) and B<rm>(1) commands have exceptions to these rules:"
13299 #. type: Plain text
13300 #: build/C/man7/symlink.7:492
13302 "The B<rm>(1) command operates on the symbolic link, and not the file it "
13303 "references, and therefore never follows a symbolic link. The B<rm>(1) "
13304 "command does not support the I<-H>, I<-L>, or I<-P> options."
13307 #. type: Plain text
13308 #: build/C/man7/symlink.7:512
13310 "To maintain compatibility with historic systems, the B<ls>(1) command acts "
13311 "a little differently. If you do not specify the I<-F>, I<-d> or I<-l> "
13312 "options, B<ls>(1) will follow symbolic links specified on the command "
13313 "line. If the I<-L> flag is specified, B<ls>(1) follows all symbolic links, "
13314 "regardless of their type, whether specified on the command line or "
13315 "encountered in the tree walk."
13318 #. type: Plain text
13319 #: build/C/man7/symlink.7:530
13321 "B<chgrp>(1), B<chmod>(1), B<find>(1), B<ln>(1), B<ls>(1), B<mv>(1), "
13322 "B<rm>(1), B<lchown>(2), B<link>(2), B<lstat>(2), B<readlink>(2), "
13323 "B<rename>(2), B<symlink>(2), B<unlink>(2), B<utimensat>(2), B<lutimes>(3), "
13324 "B<path_resolution>(7)"
13328 #: build/C/man3/tempnam.3:25
13334 #: build/C/man3/tempnam.3:25 build/C/man3/tmpnam.3:27
13339 #. type: Plain text
13340 #: build/C/man3/tempnam.3:28
13341 msgid "tempnam - create a name for a temporary file"
13344 #. type: Plain text
13345 #: build/C/man3/tempnam.3:33
13347 msgid "B<char *tempnam(const char *>I<dir>B<, const char *>I<pfx>B<);>\n"
13350 #. type: Plain text
13351 #: build/C/man3/tempnam.3:42
13352 msgid "B<tempnam>(): _BSD_SOURCE || _SVID_SOURCE"
13355 #. type: Plain text
13356 #: build/C/man3/tempnam.3:49
13357 msgid "I<Never use this function.> Use B<mkstemp>(3) or B<tmpfile>(3) instead."
13360 #. type: Plain text
13361 #: build/C/man3/tempnam.3:63
13363 "The B<tempnam>() function returns a pointer to a string that is a valid "
13364 "filename, and such that a file with this name did not exist when "
13365 "B<tempnam>() checked. The filename suffix of the pathname generated will "
13366 "start with I<pfx> in case I<pfx> is a non-NULL string of at most five "
13367 "bytes. The directory prefix part of the pathname generated is required to "
13368 "be \"appropriate\" (often that at least implies writable)."
13371 #. type: Plain text
13372 #: build/C/man3/tempnam.3:66
13373 msgid "Attempts to find an appropriate directory go through the following steps:"
13377 #: build/C/man3/tempnam.3:66
13382 #. type: Plain text
13383 #: build/C/man3/tempnam.3:72
13385 "In case the environment variable B<TMPDIR> exists and contains the name of "
13386 "an appropriate directory, that is used."
13390 #: build/C/man3/tempnam.3:72
13395 #. type: Plain text
13396 #: build/C/man3/tempnam.3:77
13397 msgid "Otherwise, if the I<dir> argument is non-NULL and appropriate, it is used."
13401 #: build/C/man3/tempnam.3:77
13406 #. type: Plain text
13407 #: build/C/man3/tempnam.3:84
13409 "Otherwise, I<P_tmpdir> (as defined in I<E<lt>stdio.hE<gt>>) is used when "
13414 #: build/C/man3/tempnam.3:84
13419 #. type: Plain text
13420 #: build/C/man3/tempnam.3:87
13421 msgid "Finally an implementation-defined directory may be used."
13424 #. type: Plain text
13425 #: build/C/man3/tempnam.3:94
13427 "The string returned by B<tempnam>() is allocated using B<malloc>(3) and "
13428 "hence should be freed by B<free>(3)."
13431 #. type: Plain text
13432 #: build/C/man3/tempnam.3:101
13434 "On success, the B<tempnam>() function returns a pointer to a unique "
13435 "temporary filename. It returns NULL if a unique name cannot be generated, "
13436 "with I<errno> set to indicate the cause of the error."
13439 #. type: Plain text
13440 #: build/C/man3/tempnam.3:105
13441 msgid "Allocation of storage failed."
13444 #. type: Plain text
13445 #: build/C/man3/tempnam.3:110
13446 msgid "SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2008 marks B<tempnam>() as obsolete."
13449 #. type: Plain text
13450 #: build/C/man3/tempnam.3:129
13452 "Although B<tempnam>() generates names that are difficult to guess, it is "
13453 "nevertheless possible that between the time that B<tempnam>() returns a "
13454 "pathname, and the time that the program opens it, another program might "
13455 "create that pathname using B<open>(2), or create it as a symbolic link. "
13456 "This can lead to security holes. To avoid such possibilities, use the "
13457 "B<open>(2) B<O_EXCL> flag to open the pathname. Or better yet, use "
13458 "B<mkstemp>(3) or B<tmpfile>(3)."
13461 #. type: Plain text
13462 #: build/C/man3/tempnam.3:137
13464 "SUSv2 does not mention the use of B<TMPDIR>; glibc will use it only when the "
13465 "program is not set-user-ID. On SVr4, the directory used under B<d)> is "
13466 "I</tmp> (and this is what glibc does)."
13469 #. type: Plain text
13470 #: build/C/man3/tempnam.3:142
13472 "Because it dynamically allocates memory used to return the pathname, "
13473 "B<tempnam>() is reentrant, and thus thread safe, unlike B<tmpnam>(3)."
13476 #. type: Plain text
13477 #: build/C/man3/tempnam.3:155
13479 "The B<tempnam>() function generates a different string each time it is "
13480 "called, up to B<TMP_MAX> (defined in I<E<lt>stdio.hE<gt>>) times. If it is "
13481 "called more than B<TMP_MAX> times, the behavior is implementation defined."
13484 #. type: Plain text
13485 #: build/C/man3/tempnam.3:159
13486 msgid "B<tempnam>() uses at most the first five bytes from I<pfx>."
13489 #. type: Plain text
13490 #: build/C/man3/tempnam.3:165
13492 "The glibc implementation of B<tempnam>() will fail with the error B<EEXIST> "
13493 "upon failure to find a unique name."
13496 #. type: Plain text
13497 #: build/C/man3/tempnam.3:168
13499 "The precise meaning of \"appropriate\" is undefined; it is unspecified how "
13500 "accessibility of a directory is determined."
13503 #. type: Plain text
13504 #: build/C/man3/tempnam.3:173
13505 msgid "B<mkstemp>(3), B<mktemp>(3), B<tmpfile>(3), B<tmpnam>(3)"
13509 #: build/C/man3/tmpfile.3:31
13514 #. type: Plain text
13515 #: build/C/man3/tmpfile.3:34
13516 msgid "tmpfile - create a temporary file"
13519 #. type: Plain text
13520 #: build/C/man3/tmpfile.3:39
13522 msgid "B<FILE *tmpfile(void);>\n"
13525 #. type: Plain text
13526 #: build/C/man3/tmpfile.3:47
13528 "The B<tmpfile>() function opens a unique temporary file in binary "
13529 "read/write (w+b) mode. The file will be automatically deleted when it is "
13530 "closed or the program terminates."
13533 #. type: Plain text
13534 #: build/C/man3/tmpfile.3:56
13536 "The B<tmpfile>() function returns a stream descriptor, or NULL if a unique "
13537 "filename cannot be generated or the unique file cannot be opened. In the "
13538 "latter case, I<errno> is set to indicate the error."
13541 #. type: Plain text
13542 #: build/C/man3/tmpfile.3:60
13543 msgid "Search permission denied for directory in file's path prefix."
13546 #. type: Plain text
13547 #: build/C/man3/tmpfile.3:63
13548 msgid "Unable to generate a unique filename."
13551 #. type: Plain text
13552 #: build/C/man3/tmpfile.3:66
13553 msgid "The call was interrupted by a signal."
13556 #. type: Plain text
13557 #: build/C/man3/tmpfile.3:69
13558 msgid "Too many file descriptors in use by the process."
13561 #. type: Plain text
13562 #: build/C/man3/tmpfile.3:72
13563 msgid "Too many files open in the system."
13566 #. type: Plain text
13567 #: build/C/man3/tmpfile.3:75
13568 msgid "There was no room in the directory to add the new filename."
13571 #. type: Plain text
13572 #: build/C/man3/tmpfile.3:78
13573 msgid "Read-only filesystem."
13576 #. type: Plain text
13577 #: build/C/man3/tmpfile.3:80
13578 msgid "SVr4, 4.3BSD, C89, C99, SUSv2, POSIX.1-2001."
13581 #. type: Plain text
13582 #: build/C/man3/tmpfile.3:86
13584 "POSIX.1-2001 specifies: an error message may be written to I<stdout> if the "
13585 "stream cannot be opened."
13588 #. type: Plain text
13589 #: build/C/man3/tmpfile.3:97
13591 "The standard does not specify the directory that B<tmpfile>() will use. "
13592 "Glibc will try the path prefix I<P_tmpdir> defined in I<E<lt>stdio.hE<gt>>, "
13593 "and if that fails the directory I</tmp>."
13596 #. type: Plain text
13597 #: build/C/man3/tmpfile.3:103
13598 msgid "B<exit>(3), B<mkstemp>(3), B<mktemp>(3), B<tempnam>(3), B<tmpnam>(3)"
13602 #: build/C/man3/tmpnam.3:27
13607 #. type: Plain text
13608 #: build/C/man3/tmpnam.3:30
13609 msgid "tmpnam, tmpnam_r - create a name for a temporary file"
13612 #. type: Plain text
13613 #: build/C/man3/tmpnam.3:35
13615 msgid "B<char *tmpnam(char *>I<s>B<);>\n"
13618 #. type: Plain text
13619 #: build/C/man3/tmpnam.3:45
13621 "B<Note:> Avoid use of B<tmpnam>(); use B<mkstemp>(3) or B<tmpfile>(3) "
13625 #. type: Plain text
13626 #: build/C/man3/tmpnam.3:67
13628 "The B<tmpnam>() function returns a pointer to a string that is a valid "
13629 "filename, and such that a file with this name did not exist at some point in "
13630 "time, so that naive programmers may think it a suitable name for a temporary "
13631 "file. If the argument I<s> is NULL, this name is generated in an internal "
13632 "static buffer and may be overwritten by the next call to B<tmpnam>(). If "
13633 "I<s> is not NULL, the name is copied to the character array (of length at "
13634 "least I<L_tmpnam>) pointed to by I<s> and the value I<s> is returned in "
13638 #. type: Plain text
13639 #: build/C/man3/tmpnam.3:79
13641 "The pathname that is created, has a directory prefix I<P_tmpdir>. (Both "
13642 "I<L_tmpnam> and I<P_tmpdir> are defined in I<E<lt>stdio.hE<gt>>, just like "
13643 "the B<TMP_MAX> mentioned below.)"
13646 #. type: Plain text
13647 #: build/C/man3/tmpnam.3:84
13649 "The B<tmpnam>() function returns a pointer to a unique temporary filename, "
13650 "or NULL if a unique name cannot be generated."
13653 #. type: Plain text
13654 #: build/C/man3/tmpnam.3:86
13655 msgid "No errors are defined."
13658 #. type: Plain text
13659 #: build/C/man3/tmpnam.3:92
13661 "The B<tmpnam>() function is thread-safe with exceptions. It is not "
13662 "thread-safe if called with a NULL parameter."
13665 #. type: Plain text
13666 #: build/C/man3/tmpnam.3:96
13667 msgid "The B<tmpnam_r>() function is thread-safe."
13670 #. type: Plain text
13671 #: build/C/man3/tmpnam.3:101
13673 "SVr4, 4.3BSD, C89, C99, POSIX.1-2001. POSIX.1-2008 marks B<tmpnam>() as "
13677 #. type: Plain text
13678 #: build/C/man3/tmpnam.3:112
13680 "The B<tmpnam>() function generates a different string each time it is "
13681 "called, up to B<TMP_MAX> times. If it is called more than B<TMP_MAX> times, "
13682 "the behavior is implementation defined."
13685 #. type: Plain text
13686 #: build/C/man3/tmpnam.3:131
13688 "Although B<tmpnam>() generates names that are difficult to guess, it is "
13689 "nevertheless possible that between the time that B<tmpnam>() returns a "
13690 "pathname, and the time that the program opens it, another program might "
13691 "create that pathname using B<open>(2), or create it as a symbolic link. "
13692 "This can lead to security holes. To avoid such possibilities, use the "
13693 "B<open>(2) B<O_EXCL> flag to open the pathname. Or better yet, use "
13694 "B<mkstemp>(3) or B<tmpfile>(3)."
13697 #. type: Plain text
13698 #: build/C/man3/tmpnam.3:139
13700 "Portable applications that use threads cannot call B<tmpnam>() with a NULL "
13701 "argument if either B<_POSIX_THREADS> or B<_POSIX_THREAD_SAFE_FUNCTIONS> is "
13705 #. type: Plain text
13706 #: build/C/man3/tmpnam.3:143
13707 msgid "A POSIX draft proposed to use a function B<tmpnam_r>() defined by"
13710 #. type: Plain text
13711 #: build/C/man3/tmpnam.3:151
13715 "tmpnam_r(char *s)\n"
13717 " return s ? tmpnam(s) : NULL;\n"
13721 #. type: Plain text
13722 #: build/C/man3/tmpnam.3:165
13724 "apparently as a warning not to use NULL. A few systems implement it. To "
13725 "get a glibc prototype for this function from I<E<lt>stdio.hE<gt>>, define "
13726 "B<_SVID_SOURCE> or B<_BSD_SOURCE> (before including I<any> header file)."
13729 #. type: Plain text
13730 #: build/C/man3/tmpnam.3:172
13731 msgid "Never use this function. Use B<mkstemp>(3) or B<tmpfile>(3) instead."
13734 #. type: Plain text
13735 #: build/C/man3/tmpnam.3:177
13736 msgid "B<mkstemp>(3), B<mktemp>(3), B<tempnam>(3), B<tmpfile>(3)"
13740 #: build/C/man2/unlink.2:33
13745 #. type: Plain text
13746 #: build/C/man2/unlink.2:36
13747 msgid "unlink, unlinkat - delete a name and possibly the file it refers to"
13750 #. type: Plain text
13751 #: build/C/man2/unlink.2:41
13753 msgid "B<int unlink(const char *>I<pathname>B<);>\n"
13756 #. type: Plain text
13757 #: build/C/man2/unlink.2:46
13760 "B<int unlinkat(int >I<dirfd>B<, const char *>I<pathname>B<, int "
13764 #. type: Plain text
13765 #: build/C/man2/unlink.2:54
13766 msgid "B<unlinkat>():"
13769 #. type: Plain text
13770 #: build/C/man2/unlink.2:72
13772 "B<unlink>() deletes a name from the filesystem. If that name was the last "
13773 "link to a file and no processes have the file open, the file is deleted and "
13774 "the space it was using is made available for reuse."
13777 #. type: Plain text
13778 #: build/C/man2/unlink.2:76
13780 "If the name was the last link to a file but any processes still have the "
13781 "file open, the file will remain in existence until the last file descriptor "
13782 "referring to it is closed."
13785 #. type: Plain text
13786 #: build/C/man2/unlink.2:82
13788 "If the name referred to a socket, FIFO, or device, the name for it is "
13789 "removed but processes which have the object open may continue to use it."
13793 #: build/C/man2/unlink.2:82
13798 #. type: Plain text
13799 #: build/C/man2/unlink.2:95
13801 "The B<unlinkat>() system call operates in exactly the same way as either "
13802 "B<unlink>() or B<rmdir>(2) (depending on whether or not I<flags> includes "
13803 "the B<AT_REMOVEDIR> flag) except for the differences described here."
13806 #. type: Plain text
13807 #: build/C/man2/unlink.2:107
13809 "If the pathname given in I<pathname> is relative, then it is interpreted "
13810 "relative to the directory referred to by the file descriptor I<dirfd> "
13811 "(rather than relative to the current working directory of the calling "
13812 "process, as is done by B<unlink>() and B<rmdir>(2) for a relative "
13816 #. type: Plain text
13817 #: build/C/man2/unlink.2:121
13819 "If the pathname given in I<pathname> is relative and I<dirfd> is the special "
13820 "value B<AT_FDCWD>, then I<pathname> is interpreted relative to the current "
13821 "working directory of the calling process (like B<unlink>() and "
13825 #. type: Plain text
13826 #: build/C/man2/unlink.2:127
13827 msgid "If the pathname given in I<pathname> is absolute, then I<dirfd> is ignored."
13830 #. type: Plain text
13831 #: build/C/man2/unlink.2:133
13833 "I<flags> is a bit mask that can either be specified as 0, or by ORing "
13834 "together flag values that control the operation of B<unlinkat>(). Currently "
13835 "only one such flag is defined:"
13839 #: build/C/man2/unlink.2:133
13841 msgid "B<AT_REMOVEDIR>"
13844 #. type: Plain text
13845 #: build/C/man2/unlink.2:148
13847 "By default, B<unlinkat>() performs the equivalent of B<unlink>() on "
13848 "I<pathname>. If the B<AT_REMOVEDIR> flag is specified, then performs the "
13849 "equivalent of B<rmdir>(2) on I<pathname>."
13852 #. type: Plain text
13853 #: build/C/man2/unlink.2:153
13854 msgid "See B<openat>(2) for an explanation of the need for B<unlinkat>()."
13857 #. type: Plain text
13858 #: build/C/man2/unlink.2:169
13860 "Write access to the directory containing I<pathname> is not allowed for the "
13861 "process's effective UID, or one of the directories in I<pathname> did not "
13862 "allow search permission. (See also B<path_resolution>(7).)"
13865 #. type: Plain text
13866 #: build/C/man2/unlink.2:178
13868 "The file I<pathname> cannot be unlinked because it is being used by the "
13869 "system or another process; for example, it is a mount point or the NFS "
13870 "client software created it to represent an active but otherwise nameless "
13871 "inode (\"NFS silly renamed\")."
13874 #. type: Plain text
13875 #: build/C/man2/unlink.2:190
13877 "I<pathname> refers to a directory. (This is the non-POSIX value returned by "
13878 "Linux since 2.1.132.)"
13881 #. type: Plain text
13882 #: build/C/man2/unlink.2:194
13883 msgid "Too many symbolic links were encountered in translating I<pathname>."
13886 #. type: Plain text
13887 #: build/C/man2/unlink.2:204
13889 "A component in I<pathname> does not exist or is a dangling symbolic link, or "
13890 "I<pathname> is empty."
13893 #. type: Plain text
13894 #: build/C/man2/unlink.2:212
13895 msgid "A component used as a directory in I<pathname> is not, in fact, a directory."
13898 #. type: Plain text
13899 #: build/C/man2/unlink.2:221
13901 "The system does not allow unlinking of directories, or unlinking of "
13902 "directories requires privileges that the calling process doesn't have. "
13903 "(This is the POSIX prescribed error return; as noted above, Linux returns "
13904 "B<EISDIR> for this case.)"
13908 #: build/C/man2/unlink.2:221
13910 msgid "B<EPERM> (Linux only)"
13913 #. type: Plain text
13914 #: build/C/man2/unlink.2:224
13915 msgid "The filesystem does not allow unlinking of files."
13918 #. type: Plain text
13919 #: build/C/man2/unlink.2:235
13921 "The directory containing I<pathname> has the sticky bit (B<S_ISVTX>) set "
13922 "and the process's effective UID is neither the UID of the file to be deleted "
13923 "nor that of the directory containing it, and the process is not privileged "
13924 "(Linux: does not have the B<CAP_FOWNER> capability)."
13927 #. type: Plain text
13928 #: build/C/man2/unlink.2:239
13929 msgid "I<pathname> refers to a file on a read-only filesystem."
13932 #. type: Plain text
13933 #: build/C/man2/unlink.2:248
13935 "The same errors that occur for B<unlink>() and B<rmdir>(2) can also occur "
13936 "for B<unlinkat>(). The following additional errors can occur for "
13940 #. type: Plain text
13941 #: build/C/man2/unlink.2:263
13943 "I<pathname> refers to a directory, and B<AT_REMOVEDIR> was not specified in "
13947 #. type: Plain text
13948 #: build/C/man2/unlink.2:273
13950 "B<unlinkat>() was added to Linux in kernel 2.6.16; library support was "
13951 "added to glibc in version 2.4."
13954 #. SVr4 documents additional error
13955 #. conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK.
13956 #. type: Plain text
13957 #: build/C/man2/unlink.2:278
13958 msgid "B<unlink>(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008."
13961 #. type: Plain text
13962 #: build/C/man2/unlink.2:281
13963 msgid "B<unlinkat>(): POSIX.1-2008."
13966 #. type: Plain text
13967 #: build/C/man2/unlink.2:297
13969 "On older kernels where B<unlinkat>() is unavailable, the glibc wrapper "
13970 "function falls back to the use of B<unlink>(2) or B<rmdir>(2). When "
13971 "I<pathname> is a relative pathname, glibc constructs a pathname based on the "
13972 "symbolic link in I</proc/self/fd> that corresponds to the I<dirfd> argument."
13975 #. type: Plain text
13976 #: build/C/man2/unlink.2:312
13978 "B<rm>(1), B<chmod>(2), B<link>(2), B<mknod>(2), B<open>(2), B<rename>(2), "
13979 "B<rmdir>(2), B<mkfifo>(3), B<remove>(3), B<path_resolution>(7), "
13984 #: build/C/man3/unlocked_stdio.3:25
13986 msgid "UNLOCKED_STDIO"
13990 #: build/C/man3/unlocked_stdio.3:25
13995 #. type: Plain text
13996 #: build/C/man3/unlocked_stdio.3:29
13998 "getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked - "
13999 "nonlocking stdio functions"
14002 #. type: Plain text
14003 #: build/C/man3/unlocked_stdio.3:37
14006 "B<int getc_unlocked(FILE *>I<stream>B<);>\n"
14007 "B<int getchar_unlocked(void);>\n"
14008 "B<int putc_unlocked(int >I<c>B<, FILE *>I<stream>B<);>\n"
14009 "B<int putchar_unlocked(int >I<c>B<);>\n"
14012 #. type: Plain text
14013 #: build/C/man3/unlocked_stdio.3:49
14016 "B<void clearerr_unlocked(FILE *>I<stream>B<);>\n"
14017 "B<int feof_unlocked(FILE *>I<stream>B<);>\n"
14018 "B<int ferror_unlocked(FILE *>I<stream>B<);>\n"
14019 "B<int fileno_unlocked(FILE *>I<stream>B<);>\n"
14020 "B<int fflush_unlocked(FILE *>I<stream>B<);>\n"
14021 "B<int fgetc_unlocked(FILE *>I<stream>B<);>\n"
14022 "B<int fputc_unlocked(int >I<c>B<, FILE *>I<stream>B<);>\n"
14023 "B<size_t fread_unlocked(void *>I<ptr>B<, size_t >I<size>B<, size_t "
14025 "B< FILE *>I<stream>B<);>\n"
14026 "B<size_t fwrite_unlocked(const void *>I<ptr>B<, size_t >I<size>B<, size_t "
14028 "B< FILE *>I<stream>B<);>\n"
14031 #. type: Plain text
14032 #: build/C/man3/unlocked_stdio.3:52
14035 "B<char *fgets_unlocked(char *>I<s>B<, int >I<n>B<, FILE *>I<stream>B<);>\n"
14036 "B<int fputs_unlocked(const char *>I<s>B<, FILE *>I<stream>B<);>\n"
14039 #. type: Plain text
14040 #: build/C/man3/unlocked_stdio.3:63
14043 "B<wint_t getwc_unlocked(FILE *>I<stream>B<);>\n"
14044 "B<wint_t getwchar_unlocked(void);>\n"
14045 "B<wint_t fgetwc_unlocked(FILE *>I<stream>B<);>\n"
14046 "B<wint_t fputwc_unlocked(wchar_t >I<wc>B<, FILE *>I<stream>B<);>\n"
14047 "B<wint_t putwc_unlocked(wchar_t >I<wc>B<, FILE *>I<stream>B<);>\n"
14048 "B<wint_t putwchar_unlocked(wchar_t >I<wc>B<);>\n"
14049 "B<wchar_t *fgetws_unlocked(wchar_t *>I<ws>B<, int >I<n>B<, FILE "
14050 "*>I<stream>B<);>\n"
14051 "B<int fputws_unlocked(const wchar_t *>I<ws>B<, FILE *>I<stream>B<);>\n"
14054 #. type: Plain text
14055 #: build/C/man3/unlocked_stdio.3:75
14057 "B<getc_unlocked>(), B<getchar_unlocked>(), B<putc_unlocked>(), "
14058 "B<putchar_unlocked>():"
14061 #. type: Plain text
14062 #: build/C/man3/unlocked_stdio.3:78
14064 "_POSIX_C_SOURCE\\ E<gt>=\\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE || "
14065 "_BSD_SOURCE || _SVID_SOURCE"
14068 #. type: Plain text
14069 #: build/C/man3/unlocked_stdio.3:89
14071 "B<clearerr_unlocked>(), B<feof_unlocked>(), B<ferror_unlocked>(), "
14072 "B<fileno_unlocked>(), B<fflush_unlocked>(), B<fgetc_unlocked>(), "
14073 "B<fputc_unlocked>(), B<fread_unlocked>(), B<fwrite_unlocked>():"
14076 #. type: Plain text
14077 #: build/C/man3/unlocked_stdio.3:91
14078 msgid "_BSD_SOURCE || _SVID_SOURCE"
14081 #. type: Plain text
14082 #: build/C/man3/unlocked_stdio.3:102
14084 "B<fgets_unlocked>(), B<fputs_unlocked>(), B<getwc_unlocked>(), "
14085 "B<getwchar_unlocked>(), B<fgetwc_unlocked>(), B<fputwc_unlocked>(), "
14086 "B<putwchar_unlocked>(), B<fgetws_unlocked>(), B<fputws_unlocked>():"
14089 #. type: Plain text
14090 #: build/C/man3/unlocked_stdio.3:113
14092 "Each of these functions has the same behavior as its counterpart without the "
14093 "\"_unlocked\" suffix, except that they do not use locking (they do not set "
14094 "locks themselves, and do not test for the presence of locks set by others) "
14095 "and hence are thread-unsafe. See B<flockfile>(3)."
14098 #. type: Plain text
14099 #: build/C/man3/unlocked_stdio.3:120
14101 "The four functions B<getc_unlocked>(), B<getchar_unlocked>(), "
14102 "B<putc_unlocked>(), B<putchar_unlocked>() are in POSIX.1-2001."
14105 #. E.g., in HP-UX 10.0. In HP-UX 10.30 they are called obsolescent, and
14106 #. moved to a compatibility library.
14107 #. Available in HP-UX 10.0: clearerr_unlocked, fclose_unlocked,
14108 #. feof_unlocked, ferror_unlocked, fflush_unlocked, fgets_unlocked,
14109 #. fgetwc_unlocked, fgetws_unlocked, fileno_unlocked, fputs_unlocked,
14110 #. fputwc_unlocked, fputws_unlocked, fread_unlocked, fseek_unlocked,
14111 #. ftell_unlocked, fwrite_unlocked, getc_unlocked, getchar_unlocked,
14112 #. getw_unlocked, getwc_unlocked, getwchar_unlocked, putc_unlocked,
14113 #. putchar_unlocked, puts_unlocked, putws_unlocked, putw_unlocked,
14114 #. putwc_unlocked, putwchar_unlocked, rewind_unlocked, setvbuf_unlocked,
14115 #. ungetc_unlocked, ungetwc_unlocked.
14116 #. type: Plain text
14117 #: build/C/man3/unlocked_stdio.3:136
14119 "The nonstandard B<*_unlocked>() variants occur on a few UNIX systems, and "
14120 "are available in recent glibc. They should probably not be used."
14123 #. type: Plain text
14124 #: build/C/man3/unlocked_stdio.3:139
14125 msgid "B<flockfile>(3), B<stdio>(3)"
14129 #: build/C/man3/wprintf.3:16
14135 #: build/C/man3/wprintf.3:16
14140 #. type: Plain text
14141 #: build/C/man3/wprintf.3:20
14143 "wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - formatted "
14144 "wide-character output conversion"
14147 #. type: Plain text
14148 #: build/C/man3/wprintf.3:24
14151 "B<#include E<lt>stdio.hE<gt>>\n"
14152 "B<#include E<lt>wchar.hE<gt>>\n"
14155 #. type: Plain text
14156 #: build/C/man3/wprintf.3:29
14159 "B<int wprintf(const wchar_t *>I<format>B<, ...);>\n"
14160 "B<int fwprintf(FILE *>I<stream>B<, const wchar_t *>I<format>B<, ...);>\n"
14161 "B<int swprintf(wchar_t *>I<wcs>B<, size_t >I<maxlen>B<,>\n"
14162 "B< const wchar_t *>I<format>B<, ...);>\n"
14165 #. type: Plain text
14166 #: build/C/man3/wprintf.3:34
14169 "B<int vwprintf(const wchar_t *>I<format>B<, va_list >I<args>B<);>\n"
14170 "B<int vfwprintf(FILE *>I<stream>B<, const wchar_t *>I<format>B<, va_list "
14172 "B<int vswprintf(wchar_t *>I<wcs>B<, size_t >I<maxlen>B<,>\n"
14173 "B< const wchar_t *>I<format>B<, va_list >I<args>B<);>\n"
14177 #. .BR fwprintf (),
14178 #. .BR swprintf (),
14179 #. .BR vwprintf (),
14180 #. .BR vfwprintf (),
14181 #. .BR vswprintf ():
14182 #. type: Plain text
14183 #: build/C/man3/wprintf.3:51
14184 msgid "_XOPEN_SOURCE\\ E<gt>=\\ 500 || _ISOC99_SOURCE ||"
14187 #. type: Plain text
14188 #: build/C/man3/wprintf.3:53
14189 msgid "_POSIX_C_SOURCE\\ E<gt>=\\ 200112L;"
14192 #. type: Plain text
14193 #: build/C/man3/wprintf.3:56
14194 msgid "or I<cc\\ -std=c99>"
14197 #. type: Plain text
14198 #: build/C/man3/wprintf.3:67
14200 "The B<wprintf>() family of functions is the wide-character equivalent of "
14201 "the B<printf>(3) family of functions. It performs formatted output of wide "
14205 #. type: Plain text
14206 #: build/C/man3/wprintf.3:79
14208 "The B<wprintf>() and B<vwprintf>() functions perform wide-character output "
14209 "to I<stdout>. I<stdout> must not be byte oriented; see B<fwide>(3) for "
14210 "more information."
14213 #. type: Plain text
14214 #: build/C/man3/wprintf.3:91
14216 "The B<fwprintf>() and B<vfwprintf>() functions perform wide-character "
14217 "output to I<stream>. I<stream> must not be byte oriented; see B<fwide>(3) "
14218 "for more information."
14221 #. type: Plain text
14222 #: build/C/man3/wprintf.3:105
14224 "The B<swprintf>() and B<vswprintf>() functions perform wide-character "
14225 "output to an array of wide characters. The programmer must ensure that "
14226 "there is room for at least I<maxlen> wide characters at I<wcs>."
14229 #. type: Plain text
14230 #: build/C/man3/wprintf.3:116
14232 "These functions are like the B<printf>(3), B<vprintf>(3), B<fprintf>(3), "
14233 "B<vfprintf>(3), B<sprintf>(3), B<vsprintf>(3) functions except for the "
14234 "following differences:"
14238 #: build/C/man3/wprintf.3:116 build/C/man3/wprintf.3:121 build/C/man3/wprintf.3:124
14243 #. type: Plain text
14244 #: build/C/man3/wprintf.3:121
14245 msgid "The I<format> string is a wide-character string."
14248 #. type: Plain text
14249 #: build/C/man3/wprintf.3:124
14250 msgid "The output consists of wide characters, not bytes."
14253 #. type: Plain text
14254 #: build/C/man3/wprintf.3:143
14256 "B<swprintf>() and B<vswprintf>() take a I<maxlen> argument, B<sprintf>(3) "
14257 "and B<vsprintf>(3) do not. (B<snprintf>(3) and B<vsnprintf>(3) take a "
14258 "I<maxlen> argument, but these functions do not return -1 upon buffer "
14259 "overflow on Linux.)"
14262 #. type: Plain text
14263 #: build/C/man3/wprintf.3:149
14264 msgid "The treatment of the conversion characters B<c> and B<s> is different:"
14267 #. type: Plain text
14268 #: build/C/man3/wprintf.3:163
14270 "If no B<l> modifier is present, the I<int> argument is converted to a wide "
14271 "character by a call to the B<btowc>(3) function, and the resulting wide "
14272 "character is written. If an B<l> modifier is present, the I<wint_t> (wide "
14273 "character) argument is written."
14276 #. type: Plain text
14277 #: build/C/man3/wprintf.3:203
14279 "If no B<l> modifier is present: The I<const\\ char\\ *> argument is expected "
14280 "to be a pointer to an array of character type (pointer to a string) "
14281 "containing a multibyte character sequence beginning in the initial shift "
14282 "state. Characters from the array are converted to wide characters (each by "
14283 "a call to the B<mbrtowc>(3) function with a conversion state starting in "
14284 "the initial state before the first byte). The resulting wide characters are "
14285 "written up to (but not including) the terminating null wide character "
14286 "(L\\(aq\\e0\\(aq). If a precision is specified, no more wide characters "
14287 "than the number specified are written. Note that the precision determines "
14288 "the number of I<wide characters> written, not the number of I<bytes> or "
14289 "I<screen positions>. The array must contain a terminating null byte "
14290 "(\\(aq\\e0\\(aq), unless a precision is given and it is so small that the "
14291 "number of converted wide characters reaches it before the end of the array "
14292 "is reached. If an B<l> modifier is present: The I<const\\ wchar_t\\ *> "
14293 "argument is expected to be a pointer to an array of wide characters. Wide "
14294 "characters from the array are written up to (but not including) a "
14295 "terminating null wide character. If a precision is specified, no more than "
14296 "the number specified are written. The array must contain a terminating null "
14297 "wide character, unless a precision is given and it is smaller than or equal "
14298 "to the number of wide characters in the array."
14301 #. type: Plain text
14302 #: build/C/man3/wprintf.3:211
14304 "The functions return the number of wide characters written, excluding the "
14305 "terminating null wide character in case of the functions B<swprintf>() and "
14306 "B<vswprintf>(). They return -1 when an error occurs."
14309 #. type: Plain text
14310 #: build/C/man3/wprintf.3:213
14314 #. type: Plain text
14315 #: build/C/man3/wprintf.3:221
14317 "The behavior of B<wprintf>() et al. depends on the B<LC_CTYPE> category of "
14318 "the current locale."
14321 #. type: Plain text
14322 #: build/C/man3/wprintf.3:251
14324 "If the I<format> string contains non-ASCII wide characters, the program will "
14325 "work correctly only if the B<LC_CTYPE> category of the current locale at run "
14326 "time is the same as the B<LC_CTYPE> category of the current locale at "
14327 "compile time. This is because the I<wchar_t> representation is platform- "
14328 "and locale-dependent. (The glibc represents wide characters using their "
14329 "Unicode (ISO-10646) code point, but other platforms don't do this. Also, "
14330 "the use of C99 universal character names of the form \\eunnnn does not solve "
14331 "this problem.) Therefore, in internationalized programs, the I<format> "
14332 "string should consist of ASCII wide characters only, or should be "
14333 "constructed at run time in an internationalized way (e.g., using "
14334 "B<gettext>(3) or B<iconv>(3), followed by B<mbstowcs>(3))."
14338 #. type: Plain text
14339 #: build/C/man3/wprintf.3:258
14340 msgid "B<fprintf>(3), B<fputwc>(3), B<fwide>(3), B<printf>(3), B<snprintf>(3)"
14344 #: build/C/man2/write.2:39
14349 #. type: Plain text
14350 #: build/C/man2/write.2:42
14351 msgid "write - write to a file descriptor"
14354 #. type: Plain text
14355 #: build/C/man2/write.2:46
14356 msgid "B<ssize_t write(int >I<fd>B<, const void *>I<buf>B<, size_t >I<count>B<);>"
14359 #. type: Plain text
14360 #: build/C/man2/write.2:54
14362 "B<write>() writes up to I<count> bytes from the buffer pointed I<buf> to "
14363 "the file referred to by the file descriptor I<fd>."
14366 #. type: Plain text
14367 #: build/C/man2/write.2:68
14369 "The number of bytes written may be less than I<count> if, for example, there "
14370 "is insufficient space on the underlying physical medium, or the "
14371 "B<RLIMIT_FSIZE> resource limit is encountered (see B<setrlimit>(2)), or the "
14372 "call was interrupted by a signal handler after having written less than "
14373 "I<count> bytes. (See also B<pipe>(7).)"
14376 #. type: Plain text
14377 #: build/C/man2/write.2:82
14379 "For a seekable file (i.e., one to which B<lseek>(2) may be applied, for "
14380 "example, a regular file) writing takes place at the current file offset, "
14381 "and the file offset is incremented by the number of bytes actually written. "
14382 "If the file was B<open>(2)ed with B<O_APPEND>, the file offset is first set "
14383 "to the end of the file before writing. The adjustment of the file offset "
14384 "and the write operation are performed as an atomic step."
14387 #. type: Plain text
14388 #: build/C/man2/write.2:89
14390 "POSIX requires that a B<read>(2) which can be proved to occur after a "
14391 "B<write>() has returned returns the new data. Note that not all "
14392 "filesystems are POSIX conforming."
14395 #. type: Plain text
14396 #: build/C/man2/write.2:94
14398 "On success, the number of bytes written is returned (zero indicates nothing "
14399 "was written). On error, -1 is returned, and I<errno> is set appropriately."
14402 #. type: Plain text
14403 #: build/C/man2/write.2:107
14405 "If I<count> is zero and I<fd> refers to a regular file, then B<write>() may "
14406 "return a failure status if one of the errors below is detected. If no "
14407 "errors are detected, 0 will be returned without causing any other effect. "
14408 "If I<count> is zero and I<fd> refers to a file other than a regular file, "
14409 "the results are not specified."
14412 #. type: Plain text
14413 #: build/C/man2/write.2:115
14415 "The file descriptor I<fd> refers to a file other than a socket and has been "
14416 "marked nonblocking (B<O_NONBLOCK>), and the write would block."
14419 #. Actually EAGAIN on Linux
14420 #. type: Plain text
14421 #: build/C/man2/write.2:126
14423 "The file descriptor I<fd> refers to a socket and has been marked nonblocking "
14424 "(B<O_NONBLOCK>), and the write would block. POSIX.1-2001 allows either "
14425 "error to be returned for this case, and does not require these constants to "
14426 "have the same value, so a portable application should check for both "
14430 #. type: Plain text
14431 #: build/C/man2/write.2:130
14432 msgid "I<fd> is not a valid file descriptor or is not open for writing."
14436 #: build/C/man2/write.2:130
14438 msgid "B<EDESTADDRREQ>"
14441 #. type: Plain text
14442 #: build/C/man2/write.2:135
14444 "I<fd> refers to a datagram socket for which a peer address has not been set "
14445 "using B<connect>(2)."
14448 #. type: Plain text
14449 #: build/C/man2/write.2:141
14451 "The user's quota of disk blocks on the filesystem containing the file "
14452 "referred to by I<fd> has been exhausted."
14455 #. type: Plain text
14456 #: build/C/man2/write.2:150
14458 "An attempt was made to write a file that exceeds the implementation-defined "
14459 "maximum file size or the process's file size limit, or to write at a "
14460 "position past the maximum allowed offset."
14463 #. type: Plain text
14464 #: build/C/man2/write.2:154
14466 "The call was interrupted by a signal before any data was written; see "
14470 #. type: Plain text
14471 #: build/C/man2/write.2:165
14473 "I<fd> is attached to an object which is unsuitable for writing; or the file "
14474 "was opened with the B<O_DIRECT> flag, and either the address specified in "
14475 "I<buf>, the value specified in I<count>, or the current file offset is not "
14476 "suitably aligned."
14479 #. type: Plain text
14480 #: build/C/man2/write.2:168
14481 msgid "A low-level I/O error occurred while modifying the inode."
14484 #. type: Plain text
14485 #: build/C/man2/write.2:173
14487 "The device containing the file referred to by I<fd> has no room for the "
14492 #: build/C/man2/write.2:177
14497 #. type: Plain text
14498 #: build/C/man2/write.2:186
14500 "I<fd> is connected to a pipe or socket whose reading end is closed. When "
14501 "this happens the writing process will also receive a B<SIGPIPE> signal. "
14502 "(Thus, the write return value is seen only if the program catches, blocks or "
14503 "ignores this signal.)"
14506 #. type: Plain text
14507 #: build/C/man2/write.2:189
14508 msgid "Other errors may occur, depending on the object connected to I<fd>."
14511 #. type: Plain text
14512 #: build/C/man2/write.2:198
14514 "Under SVr4 a write may be interrupted and return B<EINTR> at any point, not "
14515 "just before any data is written."
14518 #. type: Plain text
14519 #: build/C/man2/write.2:207
14521 "A successful return from B<write>() does not make any guarantee that data "
14522 "has been committed to disk. In fact, on some buggy implementations, it does "
14523 "not even guarantee that space has successfully been reserved for the data. "
14524 "The only way to be sure is to call B<fsync>(2) after you are done writing "
14528 #. type: Plain text
14529 #: build/C/man2/write.2:215
14531 "If a B<write>() is interrupted by a signal handler before any bytes are "
14532 "written, then the call fails with the error B<EINTR>; if it is interrupted "
14533 "after at least one byte has been written, the call succeeds, and returns the "
14534 "number of bytes written."
14537 #. http://thread.gmane.org/gmane.linux.kernel/1649458
14538 #. From: Michael Kerrisk (man-pages <mtk.manpages <at> gmail.com>
14539 #. Subject: Update of file offset on write() etc. is non-atomic with I/O
14540 #. Date: 2014-02-17 15:41:37 GMT
14541 #. Newsgroups: gmane.linux.kernel, gmane.linux.file-systems
14542 #. commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4
14543 #. Author: Linus Torvalds <torvalds@linux-foundation.org>
14544 #. Date: Mon Mar 3 09:36:58 2014 -0800
14546 #. vfs: atomic f_pos accesses as per POSIX
14547 #. type: Plain text
14548 #: build/C/man2/write.2:254
14550 "Among the APIs subsequently listed are B<write>() and B<writev>(2). And "
14551 "among the effects that should be atomic across threads (and processes) are "
14552 "updates of the file offset. However, on Linux before version 3.14, this was "
14553 "not the case: if two processes that share an open file description (see "
14554 "B<open>(2)) perform a B<write>() (or B<writev>(2)) at the same time, then "
14555 "the I/O operations were not atomic with respect updating the file offset, "
14556 "with the result that the blocks of data output by the two processes might "
14557 "(incorrectly) overlap. This problem was fixed in Linux 3.14."
14560 #. type: Plain text
14561 #: build/C/man2/write.2:266
14563 "B<close>(2), B<fcntl>(2), B<fsync>(2), B<ioctl>(2), B<lseek>(2), B<open>(2), "
14564 "B<pwrite>(2), B<read>(2), B<select>(2), B<writev>(2), B<fwrite>(3)"