po4a/epoll/po/epoll.pot

   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.
   5 #
   6 #, fuzzy
   7 msgid ""
   8 msgstr ""
   9 "Project-Id-Version: PACKAGE VERSION\n"
  10 "POT-Creation-Date: 2015-01-21 20:35+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"
  14 "Language: \n"
  15 "MIME-Version: 1.0\n"
  16 "Content-Type: text/plain; charset=UTF-8\n"
  17 "Content-Transfer-Encoding: 8bit\n"
  18
  19 #. type: TH
  20 #: build/C/man7/epoll.7:21
  21 #, no-wrap
  22 msgid "EPOLL"
  23 msgstr ""
  24
  25 #. type: TH
  26 #: build/C/man7/epoll.7:21
  27 #, no-wrap
  28 msgid "2015-01-10"
  29 msgstr ""
  30
  31 #. type: TH
  32 #: build/C/man7/epoll.7:21 build/C/man2/epoll_create.2:24 build/C/man2/epoll_ctl.2:20 build/C/man2/epoll_wait.2:22 build/C/man2/poll.2:31
  33 #, no-wrap
  34 msgid "Linux"
  35 msgstr ""
  36
  37 #. type: TH
  38 #: build/C/man7/epoll.7:21 build/C/man2/epoll_create.2:24 build/C/man2/epoll_ctl.2:20 build/C/man2/epoll_wait.2:22 build/C/man2/poll.2:31
  39 #, no-wrap
  40 msgid "Linux Programmer's Manual"
  41 msgstr ""
  42
  43 #. type: SH
  44 #: build/C/man7/epoll.7:22 build/C/man2/epoll_create.2:25 build/C/man2/epoll_ctl.2:21 build/C/man2/epoll_wait.2:23 build/C/man2/poll.2:32
  45 #, no-wrap
  46 msgid "NAME"
  47 msgstr ""
  48
  49 #. type: Plain text
  50 #: build/C/man7/epoll.7:24
  51 msgid "epoll - I/O event notification facility"
  52 msgstr ""
  53
  54 #. type: SH
  55 #: build/C/man7/epoll.7:24 build/C/man2/epoll_create.2:27 build/C/man2/epoll_ctl.2:23 build/C/man2/epoll_wait.2:25 build/C/man2/poll.2:34
  56 #, no-wrap
  57 msgid "SYNOPSIS"
  58 msgstr ""
  59
  60 #. type: Plain text
  61 #: build/C/man7/epoll.7:26 build/C/man2/epoll_ctl.2:25
  62 msgid "B<#include E<lt>sys/epoll.hE<gt>>"
  63 msgstr ""
  64
  65 #. type: SH
  66 #: build/C/man7/epoll.7:26 build/C/man2/epoll_create.2:34 build/C/man2/epoll_ctl.2:28 build/C/man2/epoll_wait.2:35 build/C/man2/poll.2:47
  67 #, no-wrap
  68 msgid "DESCRIPTION"
  69 msgstr ""
  70
  71 #. type: Plain text
  72 #: build/C/man7/epoll.7:40
  73 msgid ""
  74 "The B<epoll> API performs a similar task to B<poll>(2): monitoring multiple "
  75 "file descriptors to see if I/O is possible on any of them.  The B<epoll> API "
  76 "can be used either as an edge-triggered or a level-triggered interface and "
  77 "scales well to large numbers of watched file descriptors.  The following "
  78 "system calls are provided to create and manage an B<epoll> instance:"
  79 msgstr ""
  80
  81 #. type: IP
  82 #: build/C/man7/epoll.7:40 build/C/man7/epoll.7:49 build/C/man7/epoll.7:57 build/C/man2/epoll_wait.2:59 build/C/man2/epoll_wait.2:61 build/C/man2/epoll_wait.2:63 build/C/man2/poll.2:134 build/C/man2/poll.2:136 build/C/man2/poll.2:138
  83 #, no-wrap
  84 msgid "*"
  85 msgstr ""
  86
  87 #. type: Plain text
  88 #: build/C/man7/epoll.7:49
  89 msgid ""
  90 "B<epoll_create>(2)  creates an B<epoll> instance and returns a file "
  91 "descriptor referring to that instance.  (The more recent B<epoll_create1>(2)  "
  92 "extends the functionality of B<epoll_create>(2).)"
  93 msgstr ""
  94
  95 #. type: Plain text
  96 #: build/C/man7/epoll.7:57
  97 msgid ""
  98 "Interest in particular file descriptors is then registered via "
  99 "B<epoll_ctl>(2).  The set of file descriptors currently registered on an "
 100 "B<epoll> instance is sometimes called an I<epoll> set."
 101 msgstr ""
 102
 103 #. type: Plain text
 104 #: build/C/man7/epoll.7:61
 105 msgid ""
 106 "B<epoll_wait>(2)  waits for I/O events, blocking the calling thread if no "
 107 "events are currently available."
 108 msgstr ""
 109
 110 #. type: SS
 111 #: build/C/man7/epoll.7:61
 112 #, no-wrap
 113 msgid "Level-triggered and edge-triggered"
 114 msgstr ""
 115
 116 #. type: Plain text
 117 #: build/C/man7/epoll.7:70
 118 msgid ""
 119 "The B<epoll> event distribution interface is able to behave both as "
 120 "edge-triggered (ET) and as level-triggered (LT).  The difference between the "
 121 "two mechanisms can be described as follows.  Suppose that this scenario "
 122 "happens:"
 123 msgstr ""
 124
 125 #. type: IP
 126 #: build/C/man7/epoll.7:70
 127 #, no-wrap
 128 msgid "1."
 129 msgstr ""
 130
 131 #. type: Plain text
 132 #: build/C/man7/epoll.7:76
 133 msgid ""
 134 "The file descriptor that represents the read side of a pipe (I<rfd>)  is "
 135 "registered on the B<epoll> instance."
 136 msgstr ""
 137
 138 #. type: IP
 139 #: build/C/man7/epoll.7:76
 140 #, no-wrap
 141 msgid "2."
 142 msgstr ""
 143
 144 #. type: Plain text
 145 #: build/C/man7/epoll.7:78
 146 msgid "A pipe writer writes 2 kB of data on the write side of the pipe."
 147 msgstr ""
 148
 149 #. type: IP
 150 #: build/C/man7/epoll.7:78
 151 #, no-wrap
 152 msgid "3."
 153 msgstr ""
 154
 155 #. type: Plain text
 156 #: build/C/man7/epoll.7:84
 157 msgid ""
 158 "A call to B<epoll_wait>(2)  is done that will return I<rfd> as a ready file "
 159 "descriptor."
 160 msgstr ""
 161
 162 #. type: IP
 163 #: build/C/man7/epoll.7:84
 164 #, no-wrap
 165 msgid "4."
 166 msgstr ""
 167
 168 #. type: Plain text
 169 #: build/C/man7/epoll.7:87
 170 msgid "The pipe reader reads 1 kB of data from I<rfd>."
 171 msgstr ""
 172
 173 #. type: IP
 174 #: build/C/man7/epoll.7:87
 175 #, no-wrap
 176 msgid "5."
 177 msgstr ""
 178
 179 #. type: Plain text
 180 #: build/C/man7/epoll.7:91
 181 msgid "A call to B<epoll_wait>(2)  is done."
 182 msgstr ""
 183
 184 #. type: Plain text
 185 #: build/C/man7/epoll.7:126
 186 msgid ""
 187 "If the I<rfd> file descriptor has been added to the B<epoll> interface using "
 188 "the B<EPOLLET> (edge-triggered)  flag, the call to B<epoll_wait>(2)  done in "
 189 "step B<5> will probably hang despite the available data still present in the "
 190 "file input buffer; meanwhile the remote peer might be expecting a response "
 191 "based on the data it already sent.  The reason for this is that "
 192 "edge-triggered mode delivers events only when changes occur on the monitored "
 193 "file descriptor.  So, in step B<5> the caller might end up waiting for some "
 194 "data that is already present inside the input buffer.  In the above example, "
 195 "an event on I<rfd> will be generated because of the write done in B<2> and "
 196 "the event is consumed in B<3>.  Since the read operation done in B<4> does "
 197 "not consume the whole buffer data, the call to B<epoll_wait>(2)  done in "
 198 "step B<5> might block indefinitely."
 199 msgstr ""
 200
 201 #. type: Plain text
 202 #: build/C/man7/epoll.7:136
 203 msgid ""
 204 "An application that employs the B<EPOLLET> flag should use nonblocking file "
 205 "descriptors to avoid having a blocking read or write starve a task that is "
 206 "handling multiple file descriptors.  The suggested way to use B<epoll> as an "
 207 "edge-triggered (B<EPOLLET>)  interface is as follows:"
 208 msgstr ""
 209
 210 #. type: TP
 211 #: build/C/man7/epoll.7:137
 212 #, no-wrap
 213 msgid "B<i>"
 214 msgstr ""
 215
 216 #. type: Plain text
 217 #: build/C/man7/epoll.7:140
 218 msgid "with nonblocking file descriptors; and"
 219 msgstr ""
 220
 221 #. type: TP
 222 #: build/C/man7/epoll.7:140
 223 #, no-wrap
 224 msgid "B<ii>"
 225 msgstr ""
 226
 227 #. type: Plain text
 228 #: build/C/man7/epoll.7:148
 229 msgid ""
 230 "by waiting for an event only after B<read>(2)  or B<write>(2)  return "
 231 "B<EAGAIN>."
 232 msgstr ""
 233
 234 #. type: Plain text
 235 #: build/C/man7/epoll.7:159
 236 msgid ""
 237 "By contrast, when used as a level-triggered interface (the default, when "
 238 "B<EPOLLET> is not specified), B<epoll> is simply a faster B<poll>(2), and "
 239 "can be used wherever the latter is used since it shares the same semantics."
 240 msgstr ""
 241
 242 #. type: Plain text
 243 #: build/C/man7/epoll.7:176
 244 msgid ""
 245 "Since even with edge-triggered B<epoll>, multiple events can be generated "
 246 "upon receipt of multiple chunks of data, the caller has the option to "
 247 "specify the B<EPOLLONESHOT> flag, to tell B<epoll> to disable the associated "
 248 "file descriptor after the receipt of an event with B<epoll_wait>(2).  When "
 249 "the B<EPOLLONESHOT> flag is specified, it is the caller's responsibility to "
 250 "rearm the file descriptor using B<epoll_ctl>(2)  with B<EPOLL_CTL_MOD>."
 251 msgstr ""
 252
 253 #. type: SS
 254 #: build/C/man7/epoll.7:176
 255 #, no-wrap
 256 msgid "Interaction with autosleep"
 257 msgstr ""
 258
 259 #. type: Plain text
 260 #: build/C/man7/epoll.7:188
 261 msgid ""
 262 "If the system is in B<autosleep> mode via I</sys/power/autosleep> and an "
 263 "event happens which wakes the device from sleep, the device driver will only "
 264 "keep the device awake until that event is queued.  To keep the device awake "
 265 "until the event has been processed, it is necessary to use the B<epoll>(7)  "
 266 "B<EPOLLWAKEUP> flag."
 267 msgstr ""
 268
 269 #. type: Plain text
 270 #: build/C/man7/epoll.7:207
 271 msgid ""
 272 "When the B<EPOLLWAKEUP> flag is set in the B<events> field for a I<struct "
 273 "epoll_event>, the system will be kept awake from the moment the event is "
 274 "queued, through the B<epoll_wait>(2)  call which returns the event until the "
 275 "subsequent B<epoll_wait>(2)  call.  If the event should keep the system "
 276 "awake beyond that time, then a separate I<wake_lock> should be taken before "
 277 "the second B<epoll_wait>(2)  call."
 278 msgstr ""
 279
 280 #. type: SS
 281 #: build/C/man7/epoll.7:207
 282 #, no-wrap
 283 msgid "/proc interfaces"
 284 msgstr ""
 285
 286 #.  Following was added in 2.6.28, but them removed in 2.6.29
 287 #.  .TP
 288 #.  .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)"
 289 #.  This specifies an upper limit on the number of epoll instances
 290 #.  that can be created per real user ID.
 291 #. type: Plain text
 292 #: build/C/man7/epoll.7:215
 293 msgid ""
 294 "The following interfaces can be used to limit the amount of kernel memory "
 295 "consumed by epoll:"
 296 msgstr ""
 297
 298 #. type: TP
 299 #: build/C/man7/epoll.7:215
 300 #, no-wrap
 301 msgid "I</proc/sys/fs/epoll/max_user_watches> (since Linux 2.6.28)"
 302 msgstr ""
 303
 304 #.  2.6.29 (in 2.6.28, the default was 1/32 of lowmem)
 305 #. type: Plain text
 306 #: build/C/man7/epoll.7:229
 307 msgid ""
 308 "This specifies a limit on the total number of file descriptors that a user "
 309 "can register across all epoll instances on the system.  The limit is per "
 310 "real user ID.  Each registered file descriptor costs roughly 90 bytes on a "
 311 "32-bit kernel, and roughly 160 bytes on a 64-bit kernel.  Currently, the "
 312 "default value for I<max_user_watches> is 1/25 (4%) of the available low "
 313 "memory, divided by the registration cost in bytes."
 314 msgstr ""
 315
 316 #. type: SS
 317 #: build/C/man7/epoll.7:229
 318 #, no-wrap
 319 msgid "Example for suggested usage"
 320 msgstr ""
 321
 322 #. type: Plain text
 323 #: build/C/man7/epoll.7:258
 324 msgid ""
 325 "While the usage of B<epoll> when employed as a level-triggered interface "
 326 "does have the same semantics as B<poll>(2), the edge-triggered usage "
 327 "requires more clarification to avoid stalls in the application event loop.  "
 328 "In this example, listener is a nonblocking socket on which B<listen>(2)  has "
 329 "been called.  The function I<do_use_fd()> uses the new ready file descriptor "
 330 "until B<EAGAIN> is returned by either B<read>(2)  or B<write>(2).  An "
 331 "event-driven state machine application should, after having received "
 332 "B<EAGAIN>, record its current state so that at the next call to "
 333 "I<do_use_fd()> it will continue to B<read>(2)  or B<write>(2)  from where it "
 334 "stopped before."
 335 msgstr ""
 336
 337 #. type: Plain text
 338 #: build/C/man7/epoll.7:264
 339 #, no-wrap
 340 msgid ""
 341 "#define MAX_EVENTS 10\n"
 342 "struct epoll_event ev, events[MAX_EVENTS];\n"
 343 "int listen_sock, conn_sock, nfds, epollfd;\n"
 344 msgstr ""
 345
 346 #. type: Plain text
 347 #: build/C/man7/epoll.7:267
 348 #, no-wrap
 349 msgid ""
 350 "/* Code to set up listening socket, \\(aqlisten_sock\\(aq,\n"
 351 "   (socket(), bind(), listen()) omitted */\n"
 352 msgstr ""
 353
 354 #. type: Plain text
 355 #: build/C/man7/epoll.7:273
 356 #, no-wrap
 357 msgid ""
 358 "epollfd = epoll_create1(0);\n"
 359 "if (epollfd == -1) {\n"
 360 "    perror(\"epoll_create1\");\n"
 361 "    exit(EXIT_FAILURE);\n"
 362 "}\n"
 363 msgstr ""
 364
 365 #. type: Plain text
 366 #: build/C/man7/epoll.7:280
 367 #, no-wrap
 368 msgid ""
 369 "ev.events = EPOLLIN;\n"
 370 "ev.data.fd = listen_sock;\n"
 371 "if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {\n"
 372 "    perror(\"epoll_ctl: listen_sock\");\n"
 373 "    exit(EXIT_FAILURE);\n"
 374 "}\n"
 375 msgstr ""
 376
 377 #. type: Plain text
 378 #: build/C/man7/epoll.7:287
 379 #, no-wrap
 380 msgid ""
 381 "for (;;) {\n"
 382 "    nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);\n"
 383 "    if (nfds == -1) {\n"
 384 "        perror(\"epoll_pwait\");\n"
 385 "        exit(EXIT_FAILURE);\n"
 386 "    }\n"
 387 msgstr ""
 388
 389 #. type: Plain text
 390 #: build/C/man7/epoll.7:309
 391 #, no-wrap
 392 msgid ""
 393 "    for (n = 0; n E<lt> nfds; ++n) {\n"
 394 "        if (events[n].data.fd == listen_sock) {\n"
 395 "            conn_sock = accept(listen_sock,\n"
 396 "                            (struct sockaddr *) &local, &addrlen);\n"
 397 "            if (conn_sock == -1) {\n"
 398 "                perror(\"accept\");\n"
 399 "                exit(EXIT_FAILURE);\n"
 400 "            }\n"
 401 "            setnonblocking(conn_sock);\n"
 402 "            ev.events = EPOLLIN | EPOLLET;\n"
 403 "            ev.data.fd = conn_sock;\n"
 404 "            if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,\n"
 405 "                        &ev) == -1) {\n"
 406 "                perror(\"epoll_ctl: conn_sock\");\n"
 407 "                exit(EXIT_FAILURE);\n"
 408 "            }\n"
 409 "        } else {\n"
 410 "            do_use_fd(events[n].data.fd);\n"
 411 "        }\n"
 412 "    }\n"
 413 "}\n"
 414 msgstr ""
 415
 416 #. type: Plain text
 417 #: build/C/man7/epoll.7:328
 418 msgid ""
 419 "When used as an edge-triggered interface, for performance reasons, it is "
 420 "possible to add the file descriptor inside the B<epoll> interface "
 421 "(B<EPOLL_CTL_ADD>)  once by specifying (B<EPOLLIN>|B<EPOLLOUT>).  This "
 422 "allows you to avoid continuously switching between B<EPOLLIN> and "
 423 "B<EPOLLOUT> calling B<epoll_ctl>(2)  with B<EPOLL_CTL_MOD>."
 424 msgstr ""
 425
 426 #. type: SS
 427 #: build/C/man7/epoll.7:328
 428 #, no-wrap
 429 msgid "Questions and answers"
 430 msgstr ""
 431
 432 #. type: TP
 433 #: build/C/man7/epoll.7:329
 434 #, no-wrap
 435 msgid "B<Q0>"
 436 msgstr ""
 437
 438 #. type: Plain text
 439 #: build/C/man7/epoll.7:334
 440 msgid ""
 441 "What is the key used to distinguish the file descriptors registered in an "
 442 "B<epoll> set?"
 443 msgstr ""
 444
 445 #. type: TP
 446 #: build/C/man7/epoll.7:334
 447 #, no-wrap
 448 msgid "B<A0>"
 449 msgstr ""
 450
 451 #. type: Plain text
 452 #: build/C/man7/epoll.7:340
 453 msgid ""
 454 "The key is the combination of the file descriptor number and the open file "
 455 "description (also known as an \"open file handle\", the kernel's internal "
 456 "representation of an open file)."
 457 msgstr ""
 458
 459 #. type: TP
 460 #: build/C/man7/epoll.7:340
 461 #, no-wrap
 462 msgid "B<Q1>"
 463 msgstr ""
 464
 465 #. type: Plain text
 466 #: build/C/man7/epoll.7:345
 467 msgid ""
 468 "What happens if you register the same file descriptor on an B<epoll> "
 469 "instance twice?"
 470 msgstr ""
 471
 472 #. type: TP
 473 #: build/C/man7/epoll.7:345
 474 #, no-wrap
 475 msgid "B<A1>"
 476 msgstr ""
 477
 478 #.  But a descriptor duplicated by fork(2) can't be added to the
 479 #.  set, because the [file *, fd] pair is already in the epoll set.
 480 #.  That is a somewhat ugly inconsistency.  On the one hand, a child process
 481 #.  cannot add the duplicate file descriptor to the epoll set.  (In every
 482 #.  other case that I can think of, descriptors duplicated by fork have
 483 #.  similar semantics to descriptors duplicated by dup() and friends.)  On
 484 #.  the other hand, the very fact that the child has a duplicate of the
 485 #.  descriptor means that even if the parent closes its descriptor, then
 486 #.  epoll_wait() in the parent will continue to receive notifications for
 487 #.  that descriptor because of the duplicated descriptor in the child.
 488 #
 489 #.  See http://thread.gmane.org/gmane.linux.kernel/596462/
 490 #.  "epoll design problems with common fork/exec patterns"
 491 #
 492 #.  mtk, Feb 2008
 493 #. type: Plain text
 494 #: build/C/man7/epoll.7:376
 495 msgid ""
 496 "You will probably get B<EEXIST>.  However, it is possible to add a duplicate "
 497 "(B<dup>(2), B<dup2>(2), B<fcntl>(2)  B<F_DUPFD>)  descriptor to the same "
 498 "B<epoll> instance.  This can be a useful technique for filtering events, if "
 499 "the duplicate file descriptors are registered with different I<events> "
 500 "masks."
 501 msgstr ""
 502
 503 #. type: TP
 504 #: build/C/man7/epoll.7:376
 505 #, no-wrap
 506 msgid "B<Q2>"
 507 msgstr ""
 508
 509 #. type: Plain text
 510 #: build/C/man7/epoll.7:384
 511 msgid ""
 512 "Can two B<epoll> instances wait for the same file descriptor? If so, are "
 513 "events reported to both B<epoll> file descriptors?"
 514 msgstr ""
 515
 516 #. type: TP
 517 #: build/C/man7/epoll.7:384
 518 #, no-wrap
 519 msgid "B<A2>"
 520 msgstr ""
 521
 522 #. type: Plain text
 523 #: build/C/man7/epoll.7:388
 524 msgid ""
 525 "Yes, and events would be reported to both.  However, careful programming may "
 526 "be needed to do this correctly."
 527 msgstr ""
 528
 529 #. type: TP
 530 #: build/C/man7/epoll.7:388
 531 #, no-wrap
 532 msgid "B<Q3>"
 533 msgstr ""
 534
 535 #. type: Plain text
 536 #: build/C/man7/epoll.7:393
 537 msgid "Is the B<epoll> file descriptor itself poll/epoll/selectable?"
 538 msgstr ""
 539
 540 #. type: TP
 541 #: build/C/man7/epoll.7:393
 542 #, no-wrap
 543 msgid "B<A3>"
 544 msgstr ""
 545
 546 #. type: Plain text
 547 #: build/C/man7/epoll.7:400
 548 msgid ""
 549 "Yes.  If an B<epoll> file descriptor has events waiting, then it will "
 550 "indicate as being readable."
 551 msgstr ""
 552
 553 #. type: TP
 554 #: build/C/man7/epoll.7:400
 555 #, no-wrap
 556 msgid "B<Q4>"
 557 msgstr ""
 558
 559 #. type: Plain text
 560 #: build/C/man7/epoll.7:405
 561 msgid ""
 562 "What happens if one attempts to put an B<epoll> file descriptor into its own "
 563 "file descriptor set?"
 564 msgstr ""
 565
 566 #. type: TP
 567 #: build/C/man7/epoll.7:405
 568 #, no-wrap
 569 msgid "B<A4>"
 570 msgstr ""
 571
 572 #. type: Plain text
 573 #: build/C/man7/epoll.7:416
 574 msgid ""
 575 "The B<epoll_ctl>(2)  call will fail (B<EINVAL>).  However, you can add an "
 576 "B<epoll> file descriptor inside another B<epoll> file descriptor set."
 577 msgstr ""
 578
 579 #. type: TP
 580 #: build/C/man7/epoll.7:416
 581 #, no-wrap
 582 msgid "B<Q5>"
 583 msgstr ""
 584
 585 #. type: Plain text
 586 #: build/C/man7/epoll.7:421
 587 msgid ""
 588 "Can I send an B<epoll> file descriptor over a UNIX domain socket to another "
 589 "process?"
 590 msgstr ""
 591
 592 #. type: TP
 593 #: build/C/man7/epoll.7:421
 594 #, no-wrap
 595 msgid "B<A5>"
 596 msgstr ""
 597
 598 #. type: Plain text
 599 #: build/C/man7/epoll.7:427
 600 msgid ""
 601 "Yes, but it does not make sense to do this, since the receiving process "
 602 "would not have copies of the file descriptors in the B<epoll> set."
 603 msgstr ""
 604
 605 #. type: TP
 606 #: build/C/man7/epoll.7:427
 607 #, no-wrap
 608 msgid "B<Q6>"
 609 msgstr ""
 610
 611 #. type: Plain text
 612 #: build/C/man7/epoll.7:432
 613 msgid ""
 614 "Will closing a file descriptor cause it to be removed from all B<epoll> sets "
 615 "automatically?"
 616 msgstr ""
 617
 618 #. type: TP
 619 #: build/C/man7/epoll.7:432
 620 #, no-wrap
 621 msgid "B<A6>"
 622 msgstr ""
 623
 624 #. type: Plain text
 625 #: build/C/man7/epoll.7:460
 626 msgid ""
 627 "Yes, but be aware of the following point.  A file descriptor is a reference "
 628 "to an open file description (see B<open>(2)).  Whenever a descriptor is "
 629 "duplicated via B<dup>(2), B<dup2>(2), B<fcntl>(2)  B<F_DUPFD>, or "
 630 "B<fork>(2), a new file descriptor referring to the same open file "
 631 "description is created.  An open file description continues to exist until "
 632 "all file descriptors referring to it have been closed.  A file descriptor is "
 633 "removed from an B<epoll> set only after all the file descriptors referring "
 634 "to the underlying open file description have been closed (or before if the "
 635 "descriptor is explicitly removed using B<epoll_ctl>(2)  B<EPOLL_CTL_DEL>).  "
 636 "This means that even after a file descriptor that is part of an B<epoll> set "
 637 "has been closed, events may be reported for that file descriptor if other "
 638 "file descriptors referring to the same underlying file description remain "
 639 "open."
 640 msgstr ""
 641
 642 #. type: TP
 643 #: build/C/man7/epoll.7:460
 644 #, no-wrap
 645 msgid "B<Q7>"
 646 msgstr ""
 647
 648 #. type: Plain text
 649 #: build/C/man7/epoll.7:465
 650 msgid ""
 651 "If more than one event occurs between B<epoll_wait>(2)  calls, are they "
 652 "combined or reported separately?"
 653 msgstr ""
 654
 655 #. type: TP
 656 #: build/C/man7/epoll.7:465
 657 #, no-wrap
 658 msgid "B<A7>"
 659 msgstr ""
 660
 661 #. type: Plain text
 662 #: build/C/man7/epoll.7:468
 663 msgid "They will be combined."
 664 msgstr ""
 665
 666 #. type: TP
 667 #: build/C/man7/epoll.7:468
 668 #, no-wrap
 669 msgid "B<Q8>"
 670 msgstr ""
 671
 672 #. type: Plain text
 673 #: build/C/man7/epoll.7:472
 674 msgid ""
 675 "Does an operation on a file descriptor affect the already collected but not "
 676 "yet reported events?"
 677 msgstr ""
 678
 679 #. type: TP
 680 #: build/C/man7/epoll.7:472
 681 #, no-wrap
 682 msgid "B<A8>"
 683 msgstr ""
 684
 685 #. type: Plain text
 686 #: build/C/man7/epoll.7:478
 687 msgid ""
 688 "You can do two operations on an existing file descriptor.  Remove would be "
 689 "meaningless for this case.  Modify will reread available I/O."
 690 msgstr ""
 691
 692 #. type: TP
 693 #: build/C/man7/epoll.7:478
 694 #, no-wrap
 695 msgid "B<Q9>"
 696 msgstr ""
 697
 698 #. type: Plain text
 699 #: build/C/man7/epoll.7:486
 700 msgid ""
 701 "Do I need to continuously read/write a file descriptor until B<EAGAIN> when "
 702 "using the B<EPOLLET> flag (edge-triggered behavior) ?"
 703 msgstr ""
 704
 705 #. type: TP
 706 #: build/C/man7/epoll.7:486
 707 #, no-wrap
 708 msgid "B<A9>"
 709 msgstr ""
 710
 711 #. type: Plain text
 712 #: build/C/man7/epoll.7:496
 713 msgid ""
 714 "Receiving an event from B<epoll_wait>(2)  should suggest to you that such "
 715 "file descriptor is ready for the requested I/O operation.  You must consider "
 716 "it ready until the next (nonblocking)  read/write yields B<EAGAIN>.  When "
 717 "and how you will use the file descriptor is entirely up to you."
 718 msgstr ""
 719
 720 #. type: Plain text
 721 #: build/C/man7/epoll.7:502
 722 msgid ""
 723 "For packet/token-oriented files (e.g., datagram socket, terminal in "
 724 "canonical mode), the only way to detect the end of the read/write I/O space "
 725 "is to continue to read/write until B<EAGAIN>."
 726 msgstr ""
 727
 728 #. type: Plain text
 729 #: build/C/man7/epoll.7:518
 730 msgid ""
 731 "For stream-oriented files (e.g., pipe, FIFO, stream socket), the condition "
 732 "that the read/write I/O space is exhausted can also be detected by checking "
 733 "the amount of data read from / written to the target file descriptor.  For "
 734 "example, if you call B<read>(2)  by asking to read a certain amount of data "
 735 "and B<read>(2)  returns a lower number of bytes, you can be sure of having "
 736 "exhausted the read I/O space for the file descriptor.  The same is true when "
 737 "writing using B<write>(2).  (Avoid this latter technique if you cannot "
 738 "guarantee that the monitored file descriptor always refers to a "
 739 "stream-oriented file.)"
 740 msgstr ""
 741
 742 #. type: SS
 743 #: build/C/man7/epoll.7:518
 744 #, no-wrap
 745 msgid "Possible pitfalls and ways to avoid them"
 746 msgstr ""
 747
 748 #. type: TP
 749 #: build/C/man7/epoll.7:519
 750 #, no-wrap
 751 msgid "B<o Starvation (edge-triggered)>"
 752 msgstr ""
 753
 754 #. type: Plain text
 755 #: build/C/man7/epoll.7:527
 756 msgid ""
 757 "If there is a large amount of I/O space, it is possible that by trying to "
 758 "drain it the other files will not get processed causing starvation.  (This "
 759 "problem is not specific to B<epoll>.)"
 760 msgstr ""
 761
 762 #. type: Plain text
 763 #: build/C/man7/epoll.7:535
 764 msgid ""
 765 "The solution is to maintain a ready list and mark the file descriptor as "
 766 "ready in its associated data structure, thereby allowing the application to "
 767 "remember which files need to be processed but still round robin amongst all "
 768 "the ready files.  This also supports ignoring subsequent events you receive "
 769 "for file descriptors that are already ready."
 770 msgstr ""
 771
 772 #. type: TP
 773 #: build/C/man7/epoll.7:535
 774 #, no-wrap
 775 msgid "B<o If using an event cache...>"
 776 msgstr ""
 777
 778 #. type: Plain text
 779 #: build/C/man7/epoll.7:551
 780 msgid ""
 781 "If you use an event cache or store all the file descriptors returned from "
 782 "B<epoll_wait>(2), then make sure to provide a way to mark its closure "
 783 "dynamically (i.e., caused by a previous event's processing).  Suppose you "
 784 "receive 100 events from B<epoll_wait>(2), and in event #47 a condition "
 785 "causes event #13 to be closed.  If you remove the structure and B<close>(2)  "
 786 "the file descriptor for event #13, then your event cache might still say "
 787 "there are events waiting for that file descriptor causing confusion."
 788 msgstr ""
 789
 790 #. type: Plain text
 791 #: build/C/man7/epoll.7:562
 792 msgid ""
 793 "One solution for this is to call, during the processing of event 47, "
 794 "B<epoll_ctl>(B<EPOLL_CTL_DEL>)  to delete file descriptor 13 and "
 795 "B<close>(2), then mark its associated data structure as removed and link it "
 796 "to a cleanup list.  If you find another event for file descriptor 13 in your "
 797 "batch processing, you will discover the file descriptor had been previously "
 798 "removed and there will be no confusion."
 799 msgstr ""
 800
 801 #. type: SH
 802 #: build/C/man7/epoll.7:562 build/C/man2/epoll_create.2:108 build/C/man2/epoll_ctl.2:256 build/C/man2/epoll_wait.2:187 build/C/man2/poll.2:330
 803 #, no-wrap
 804 msgid "VERSIONS"
 805 msgstr ""
 806
 807 #.  Its interface should be finalized in Linux kernel 2.5.66.
 808 #. type: Plain text
 809 #: build/C/man7/epoll.7:568
 810 msgid ""
 811 "The B<epoll> API was introduced in Linux kernel 2.5.44.  Support was added "
 812 "to glibc in version 2.3.2."
 813 msgstr ""
 814
 815 #. type: SH
 816 #: build/C/man7/epoll.7:568 build/C/man2/epoll_create.2:118 build/C/man2/epoll_ctl.2:261 build/C/man2/epoll_wait.2:197 build/C/man2/poll.2:347
 817 #, no-wrap
 818 msgid "CONFORMING TO"
 819 msgstr ""
 820
 821 #. type: Plain text
 822 #: build/C/man7/epoll.7:577
 823 msgid ""
 824 "The B<epoll> API is Linux-specific.  Some other systems provide similar "
 825 "mechanisms, for example, FreeBSD has I<kqueue>, and Solaris has "
 826 "I</dev/poll>."
 827 msgstr ""
 828
 829 #. type: SH
 830 #: build/C/man7/epoll.7:577 build/C/man2/epoll_create.2:144 build/C/man2/epoll_ctl.2:311 build/C/man2/epoll_wait.2:242 build/C/man2/poll.2:397
 831 #, no-wrap
 832 msgid "SEE ALSO"
 833 msgstr ""
 834
 835 #. type: Plain text
 836 #: build/C/man7/epoll.7:581
 837 msgid "B<epoll_create>(2), B<epoll_create1>(2), B<epoll_ctl>(2), B<epoll_wait>(2)"
 838 msgstr ""
 839
 840 #. type: TH
 841 #: build/C/man2/epoll_create.2:24
 842 #, no-wrap
 843 msgid "EPOLL_CREATE"
 844 msgstr ""
 845
 846 #. type: TH
 847 #: build/C/man2/epoll_create.2:24
 848 #, no-wrap
 849 msgid "2012-04-15"
 850 msgstr ""
 851
 852 #. type: Plain text
 853 #: build/C/man2/epoll_create.2:27
 854 msgid "epoll_create, epoll_create1 - open an epoll file descriptor"
 855 msgstr ""
 856
 857 #. type: Plain text
 858 #: build/C/man2/epoll_create.2:30 build/C/man2/epoll_wait.2:28
 859 #, no-wrap
 860 msgid "B<#include E<lt>sys/epoll.hE<gt>>\n"
 861 msgstr ""
 862
 863 #. type: Plain text
 864 #: build/C/man2/epoll_create.2:33
 865 #, no-wrap
 866 msgid ""
 867 "B<int epoll_create(int >I<size>B<);>\n"
 868 "B<int epoll_create1(int >I<flags>B<);>\n"
 869 msgstr ""
 870
 871 #. type: Plain text
 872 #: build/C/man2/epoll_create.2:42
 873 msgid ""
 874 "B<epoll_create>()  creates an B<epoll>(7)  instance.  Since Linux 2.6.8, the "
 875 "I<size> argument is ignored, but must be greater than zero; see NOTES below."
 876 msgstr ""
 877
 878 #. type: Plain text
 879 #: build/C/man2/epoll_create.2:55
 880 msgid ""
 881 "B<epoll_create>()  returns a file descriptor referring to the new epoll "
 882 "instance.  This file descriptor is used for all the subsequent calls to the "
 883 "B<epoll> interface.  When no longer required, the file descriptor returned "
 884 "by B<epoll_create>()  should be closed by using B<close>(2).  When all file "
 885 "descriptors referring to an epoll instance have been closed, the kernel "
 886 "destroys the instance and releases the associated resources for reuse."
 887 msgstr ""
 888
 889 #. type: SS
 890 #: build/C/man2/epoll_create.2:55
 891 #, no-wrap
 892 msgid "epoll_create1()"
 893 msgstr ""
 894
 895 #. type: Plain text
 896 #: build/C/man2/epoll_create.2:67
 897 msgid ""
 898 "If I<flags> is 0, then, other than the fact that the obsolete I<size> "
 899 "argument is dropped, B<epoll_create1>()  is the same as B<epoll_create>().  "
 900 "The following value can be included in I<flags> to obtain different "
 901 "behavior:"
 902 msgstr ""
 903
 904 #. type: TP
 905 #: build/C/man2/epoll_create.2:67
 906 #, no-wrap
 907 msgid "B<EPOLL_CLOEXEC>"
 908 msgstr ""
 909
 910 #. type: Plain text
 911 #: build/C/man2/epoll_create.2:77
 912 msgid ""
 913 "Set the close-on-exec (B<FD_CLOEXEC>)  flag on the new file descriptor.  See "
 914 "the description of the B<O_CLOEXEC> flag in B<open>(2)  for reasons why this "
 915 "may be useful."
 916 msgstr ""
 917
 918 #. type: SH
 919 #: build/C/man2/epoll_create.2:77 build/C/man2/epoll_ctl.2:185 build/C/man2/epoll_wait.2:150 build/C/man2/poll.2:301
 920 #, no-wrap
 921 msgid "RETURN VALUE"
 922 msgstr ""
 923
 924 #. type: Plain text
 925 #: build/C/man2/epoll_create.2:84
 926 msgid ""
 927 "On success, these system calls return a nonnegative file descriptor.  On "
 928 "error, -1 is returned, and I<errno> is set to indicate the error."
 929 msgstr ""
 930
 931 #. type: SH
 932 #: build/C/man2/epoll_create.2:84 build/C/man2/epoll_ctl.2:194 build/C/man2/epoll_wait.2:162 build/C/man2/poll.2:311
 933 #, no-wrap
 934 msgid "ERRORS"
 935 msgstr ""
 936
 937 #. type: TP
 938 #: build/C/man2/epoll_create.2:85 build/C/man2/epoll_create.2:89 build/C/man2/epoll_ctl.2:209 build/C/man2/epoll_wait.2:179 build/C/man2/poll.2:320
 939 #, no-wrap
 940 msgid "B<EINVAL>"
 941 msgstr ""
 942
 943 #. type: Plain text
 944 #: build/C/man2/epoll_create.2:89
 945 msgid "I<size> is not positive."
 946 msgstr ""
 947
 948 #. type: Plain text
 949 #: build/C/man2/epoll_create.2:94
 950 msgid "(B<epoll_create1>())  Invalid value specified in I<flags>."
 951 msgstr ""
 952
 953 #. type: TP
 954 #: build/C/man2/epoll_create.2:94
 955 #, no-wrap
 956 msgid "B<EMFILE>"
 957 msgstr ""
 958
 959 #. type: Plain text
 960 #: build/C/man2/epoll_create.2:102
 961 msgid ""
 962 "The per-user limit on the number of epoll instances imposed by "
 963 "I</proc/sys/fs/epoll/max_user_instances> was encountered.  See B<epoll>(7)  "
 964 "for further details."
 965 msgstr ""
 966
 967 #. type: TP
 968 #: build/C/man2/epoll_create.2:102
 969 #, no-wrap
 970 msgid "B<ENFILE>"
 971 msgstr ""
 972
 973 #. type: Plain text
 974 #: build/C/man2/epoll_create.2:105
 975 msgid "The system limit on the total number of open files has been reached."
 976 msgstr ""
 977
 978 #. type: TP
 979 #: build/C/man2/epoll_create.2:105 build/C/man2/epoll_ctl.2:232 build/C/man2/poll.2:327
 980 #, no-wrap
 981 msgid "B<ENOMEM>"
 982 msgstr ""
 983
 984 #. type: Plain text
 985 #: build/C/man2/epoll_create.2:108
 986 msgid "There was insufficient memory to create the kernel object."
 987 msgstr ""
 988
 989 #. type: Plain text
 990 #: build/C/man2/epoll_create.2:112
 991 msgid ""
 992 "B<epoll_create>()  was added to the kernel in version 2.6.  Library support "
 993 "is provided in glibc starting with version 2.3.2."
 994 msgstr ""
 995
 996 #.  To be precise: kernel 2.5.44.
 997 #.  The interface should be finalized by Linux kernel 2.5.66.
 998 #. type: Plain text
 999 #: build/C/man2/epoll_create.2:118
1000 msgid ""
1001 "B<epoll_create1>()  was added to the kernel in version 2.6.27.  Library "
1002 "support is provided in glibc starting with version 2.9."
1003 msgstr ""
1004
1005 #. type: Plain text
1006 #: build/C/man2/epoll_create.2:121
1007 msgid "B<epoll_create>()  is Linux-specific."
1008 msgstr ""
1009
1010 #. type: SH
1011 #: build/C/man2/epoll_create.2:121 build/C/man2/epoll_ctl.2:265 build/C/man2/epoll_wait.2:200 build/C/man2/poll.2:353
1012 #, no-wrap
1013 msgid "NOTES"
1014 msgstr ""
1015
1016 #. type: Plain text
1017 #: build/C/man2/epoll_create.2:144
1018 msgid ""
1019 "In the initial B<epoll_create>()  implementation, the I<size> argument "
1020 "informed the kernel of the number of file descriptors that the caller "
1021 "expected to add to the B<epoll> instance.  The kernel used this information "
1022 "as a hint for the amount of space to initially allocate in internal data "
1023 "structures describing events.  (If necessary, the kernel would allocate more "
1024 "space if the caller's usage exceeded the hint given in I<size>.)  Nowadays, "
1025 "this hint is no longer required (the kernel dynamically sizes the required "
1026 "data structures without needing the hint), but I<size> must still be greater "
1027 "than zero, in order to ensure backward compatibility when new B<epoll> "
1028 "applications are run on older kernels."
1029 msgstr ""
1030
1031 #. type: Plain text
1032 #: build/C/man2/epoll_create.2:148
1033 msgid "B<close>(2), B<epoll_ctl>(2), B<epoll_wait>(2), B<epoll>(7)"
1034 msgstr ""
1035
1036 #. type: TH
1037 #: build/C/man2/epoll_ctl.2:20
1038 #, no-wrap
1039 msgid "EPOLL_CTL"
1040 msgstr ""
1041
1042 #. type: TH
1043 #: build/C/man2/epoll_ctl.2:20
1044 #, no-wrap
1045 msgid "2014-12-31"
1046 msgstr ""
1047
1048 #. type: Plain text
1049 #: build/C/man2/epoll_ctl.2:23
1050 msgid "epoll_ctl - control interface for an epoll descriptor"
1051 msgstr ""
1052
1053 #. type: Plain text
1054 #: build/C/man2/epoll_ctl.2:28
1055 msgid ""
1056 "B<int epoll_ctl(int >I<epfd>B<, int >I<op>B<, int >I<fd>B<, struct "
1057 "epoll_event *>I<event>B<);>"
1058 msgstr ""
1059
1060 #. type: Plain text
1061 #: build/C/man2/epoll_ctl.2:38
1062 msgid ""
1063 "This system call performs control operations on the B<epoll>(7)  instance "
1064 "referred to by the file descriptor I<epfd>.  It requests that the operation "
1065 "I<op> be performed for the target file descriptor, I<fd>."
1066 msgstr ""
1067
1068 #. type: Plain text
1069 #: build/C/man2/epoll_ctl.2:42
1070 msgid "Valid values for the I<op> argument are:"
1071 msgstr ""
1072
1073 #. type: TP
1074 #: build/C/man2/epoll_ctl.2:42
1075 #, no-wrap
1076 msgid "B<EPOLL_CTL_ADD>"
1077 msgstr ""
1078
1079 #. type: Plain text
1080 #: build/C/man2/epoll_ctl.2:54
1081 msgid ""
1082 "Register the target file descriptor I<fd> on the B<epoll> instance referred "
1083 "to by the file descriptor I<epfd> and associate the event I<event> with the "
1084 "internal file linked to I<fd>."
1085 msgstr ""
1086
1087 #. type: TP
1088 #: build/C/man2/epoll_ctl.2:54
1089 #, no-wrap
1090 msgid "B<EPOLL_CTL_MOD>"
1091 msgstr ""
1092
1093 #. type: Plain text
1094 #: build/C/man2/epoll_ctl.2:60
1095 msgid "Change the event I<event> associated with the target file descriptor I<fd>."
1096 msgstr ""
1097
1098 #. type: TP
1099 #: build/C/man2/epoll_ctl.2:60
1100 #, no-wrap
1101 msgid "B<EPOLL_CTL_DEL>"
1102 msgstr ""
1103
1104 #. type: Plain text
1105 #: build/C/man2/epoll_ctl.2:71
1106 msgid ""
1107 "Remove (deregister) the target file descriptor I<fd> from the B<epoll> "
1108 "instance referred to by I<epfd>.  The I<event> is ignored and can be NULL "
1109 "(but see BUGS below)."
1110 msgstr ""
1111
1112 #. type: Plain text
1113 #: build/C/man2/epoll_ctl.2:79
1114 msgid ""
1115 "The I<event> argument describes the object linked to the file descriptor "
1116 "I<fd>.  The I<struct epoll_event> is defined as:"
1117 msgstr ""
1118
1119 #. type: Plain text
1120 #: build/C/man2/epoll_ctl.2:88
1121 #, no-wrap
1122 msgid ""
1123 "typedef union epoll_data {\n"
1124 "    void        *ptr;\n"
1125 "    int          fd;\n"
1126 "    uint32_t     u32;\n"
1127 "    uint64_t     u64;\n"
1128 "} epoll_data_t;\n"
1129 msgstr ""
1130
1131 #. type: Plain text
1132 #: build/C/man2/epoll_ctl.2:93
1133 #, no-wrap
1134 msgid ""
1135 "struct epoll_event {\n"
1136 "    uint32_t     events;      /* Epoll events */\n"
1137 "    epoll_data_t data;        /* User data variable */\n"
1138 "};\n"
1139 msgstr ""
1140
1141 #. type: Plain text
1142 #: build/C/man2/epoll_ctl.2:100
1143 msgid ""
1144 "The I<events> member is a bit set composed using the following available "
1145 "event types:"
1146 msgstr ""
1147
1148 #. type: TP
1149 #: build/C/man2/epoll_ctl.2:100
1150 #, no-wrap
1151 msgid "B<EPOLLIN>"
1152 msgstr ""
1153
1154 #. type: Plain text
1155 #: build/C/man2/epoll_ctl.2:105
1156 msgid "The associated file is available for B<read>(2)  operations."
1157 msgstr ""
1158
1159 #. type: TP
1160 #: build/C/man2/epoll_ctl.2:105
1161 #, no-wrap
1162 msgid "B<EPOLLOUT>"
1163 msgstr ""
1164
1165 #. type: Plain text
1166 #: build/C/man2/epoll_ctl.2:110
1167 msgid "The associated file is available for B<write>(2)  operations."
1168 msgstr ""
1169
1170 #. type: TP
1171 #: build/C/man2/epoll_ctl.2:110
1172 #, no-wrap
1173 msgid "B<EPOLLRDHUP> (since Linux 2.6.17)"
1174 msgstr ""
1175
1176 #. type: Plain text
1177 #: build/C/man2/epoll_ctl.2:116
1178 msgid ""
1179 "Stream socket peer closed connection, or shut down writing half of "
1180 "connection.  (This flag is especially useful for writing simple code to "
1181 "detect peer shutdown when using Edge Triggered monitoring.)"
1182 msgstr ""
1183
1184 #. type: TP
1185 #: build/C/man2/epoll_ctl.2:116
1186 #, no-wrap
1187 msgid "B<EPOLLPRI>"
1188 msgstr ""
1189
1190 #. type: Plain text
1191 #: build/C/man2/epoll_ctl.2:121
1192 msgid "There is urgent data available for B<read>(2)  operations."
1193 msgstr ""
1194
1195 #. type: TP
1196 #: build/C/man2/epoll_ctl.2:121
1197 #, no-wrap
1198 msgid "B<EPOLLERR>"
1199 msgstr ""
1200
1201 #. type: Plain text
1202 #: build/C/man2/epoll_ctl.2:127
1203 msgid ""
1204 "Error condition happened on the associated file descriptor.  "
1205 "B<epoll_wait>(2)  will always wait for this event; it is not necessary to "
1206 "set it in I<events>."
1207 msgstr ""
1208
1209 #. type: TP
1210 #: build/C/man2/epoll_ctl.2:127
1211 #, no-wrap
1212 msgid "B<EPOLLHUP>"
1213 msgstr ""
1214
1215 #. type: Plain text
1216 #: build/C/man2/epoll_ctl.2:133
1217 msgid ""
1218 "Hang up happened on the associated file descriptor.  B<epoll_wait>(2)  will "
1219 "always wait for this event; it is not necessary to set it in I<events>."
1220 msgstr ""
1221
1222 #. type: TP
1223 #: build/C/man2/epoll_ctl.2:133
1224 #, no-wrap
1225 msgid "B<EPOLLET>"
1226 msgstr ""
1227
1228 #. type: Plain text
1229 #: build/C/man2/epoll_ctl.2:143
1230 msgid ""
1231 "Sets the Edge Triggered behavior for the associated file descriptor.  The "
1232 "default behavior for B<epoll> is Level Triggered.  See B<epoll>(7)  for more "
1233 "detailed information about Edge and Level Triggered event distribution "
1234 "architectures."
1235 msgstr ""
1236
1237 #. type: TP
1238 #: build/C/man2/epoll_ctl.2:143
1239 #, no-wrap
1240 msgid "B<EPOLLONESHOT> (since Linux 2.6.2)"
1241 msgstr ""
1242
1243 #. type: Plain text
1244 #: build/C/man2/epoll_ctl.2:157
1245 msgid ""
1246 "Sets the one-shot behavior for the associated file descriptor.  This means "
1247 "that after an event is pulled out with B<epoll_wait>(2)  the associated file "
1248 "descriptor is internally disabled and no other events will be reported by "
1249 "the B<epoll> interface.  The user must call B<epoll_ctl>()  with "
1250 "B<EPOLL_CTL_MOD> to rearm the file descriptor with a new event mask."
1251 msgstr ""
1252
1253 #. type: TP
1254 #: build/C/man2/epoll_ctl.2:157
1255 #, no-wrap
1256 msgid "B<EPOLLWAKEUP> (since Linux 3.5)"
1257 msgstr ""
1258
1259 #.  commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
1260 #. type: Plain text
1261 #: build/C/man2/epoll_ctl.2:185
1262 msgid ""
1263 "If B<EPOLLONESHOT> and B<EPOLLET> are clear and the process has the "
1264 "B<CAP_BLOCK_SUSPEND> capability, ensure that the system does not enter "
1265 "\"suspend\" or \"hibernate\" while this event is pending or being "
1266 "processed.  The event is considered as being \"processed\" from the time "
1267 "when it is returned by a call to B<epoll_wait>(2)  until the next call to "
1268 "B<epoll_wait>(2)  on the same B<epoll>(7)  file descriptor, the closure of "
1269 "that file descriptor, the removal of the event file descriptor with "
1270 "B<EPOLL_CTL_DEL>, or the clearing of B<EPOLLWAKEUP> for the event file "
1271 "descriptor with B<EPOLL_CTL_MOD>.  See also BUGS."
1272 msgstr ""
1273
1274 #. type: Plain text
1275 #: build/C/man2/epoll_ctl.2:194
1276 msgid ""
1277 "When successful, B<epoll_ctl>()  returns zero.  When an error occurs, "
1278 "B<epoll_ctl>()  returns -1 and I<errno> is set appropriately."
1279 msgstr ""
1280
1281 #. type: TP
1282 #: build/C/man2/epoll_ctl.2:195 build/C/man2/epoll_wait.2:163
1283 #, no-wrap
1284 msgid "B<EBADF>"
1285 msgstr ""
1286
1287 #. type: Plain text
1288 #: build/C/man2/epoll_ctl.2:201
1289 msgid "I<epfd> or I<fd> is not a valid file descriptor."
1290 msgstr ""
1291
1292 #. type: TP
1293 #: build/C/man2/epoll_ctl.2:201
1294 #, no-wrap
1295 msgid "B<EEXIST>"
1296 msgstr ""
1297
1298 #. type: Plain text
1299 #: build/C/man2/epoll_ctl.2:209
1300 msgid ""
1301 "I<op> was B<EPOLL_CTL_ADD>, and the supplied file descriptor I<fd> is "
1302 "already registered with this epoll instance."
1303 msgstr ""
1304
1305 #. type: Plain text
1306 #: build/C/man2/epoll_ctl.2:222
1307 msgid ""
1308 "I<epfd> is not an B<epoll> file descriptor, or I<fd> is the same as I<epfd>, "
1309 "or the requested operation I<op> is not supported by this interface."
1310 msgstr ""
1311
1312 #. type: TP
1313 #: build/C/man2/epoll_ctl.2:222
1314 #, no-wrap
1315 msgid "B<ENOENT>"
1316 msgstr ""
1317
1318 #. type: Plain text
1319 #: build/C/man2/epoll_ctl.2:232
1320 msgid ""
1321 "I<op> was B<EPOLL_CTL_MOD> or B<EPOLL_CTL_DEL>, and I<fd> is not registered "
1322 "with this epoll instance."
1323 msgstr ""
1324
1325 #. type: Plain text
1326 #: build/C/man2/epoll_ctl.2:237
1327 msgid ""
1328 "There was insufficient memory to handle the requested I<op> control "
1329 "operation."
1330 msgstr ""
1331
1332 #. type: TP
1333 #: build/C/man2/epoll_ctl.2:237
1334 #, no-wrap
1335 msgid "B<ENOSPC>"
1336 msgstr ""
1337
1338 #. type: Plain text
1339 #: build/C/man2/epoll_ctl.2:247
1340 msgid ""
1341 "The limit imposed by I</proc/sys/fs/epoll/max_user_watches> was encountered "
1342 "while trying to register (B<EPOLL_CTL_ADD>)  a new file descriptor on an "
1343 "epoll instance.  See B<epoll>(7)  for further details."
1344 msgstr ""
1345
1346 #. type: TP
1347 #: build/C/man2/epoll_ctl.2:247
1348 #, no-wrap
1349 msgid "B<EPERM>"
1350 msgstr ""
1351
1352 #. type: Plain text
1353 #: build/C/man2/epoll_ctl.2:256
1354 msgid ""
1355 "The target file I<fd> does not support B<epoll>.  This error can occur if "
1356 "I<fd> refers to, for example, a regular file or a directory."
1357 msgstr ""
1358
1359 #.  To be precise: kernel 2.5.44.
1360 #.  The interface should be finalized by Linux kernel 2.5.66.
1361 #. type: Plain text
1362 #: build/C/man2/epoll_ctl.2:261
1363 msgid "B<epoll_ctl>()  was added to the kernel in version 2.6."
1364 msgstr ""
1365
1366 #. type: Plain text
1367 #: build/C/man2/epoll_ctl.2:265
1368 msgid ""
1369 "B<epoll_ctl>()  is Linux-specific.  Library support is provided in glibc "
1370 "starting with version 2.3.2."
1371 msgstr ""
1372
1373 #. type: Plain text
1374 #: build/C/man2/epoll_ctl.2:270
1375 msgid ""
1376 "The B<epoll> interface supports all file descriptors that support "
1377 "B<poll>(2)."
1378 msgstr ""
1379
1380 #. type: SH
1381 #: build/C/man2/epoll_ctl.2:270 build/C/man2/epoll_wait.2:217 build/C/man2/poll.2:393
1382 #, no-wrap
1383 msgid "BUGS"
1384 msgstr ""
1385
1386 #. type: Plain text
1387 #: build/C/man2/epoll_ctl.2:284
1388 msgid ""
1389 "In kernel versions before 2.6.9, the B<EPOLL_CTL_DEL> operation required a "
1390 "non-null pointer in I<event>, even though this argument is ignored.  Since "
1391 "Linux 2.6.9, I<event> can be specified as NULL when using B<EPOLL_CTL_DEL>.  "
1392 "Applications that need to be portable to kernels before 2.6.9 should specify "
1393 "a non-null pointer in I<event>."
1394 msgstr ""
1395
1396 #.  commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
1397 #.  https://lwn.net/Articles/520198/
1398 #. type: Plain text
1399 #: build/C/man2/epoll_ctl.2:311
1400 msgid ""
1401 "If B<EPOLLWAKEUP> is specified in I<flags>, but the caller does not have the "
1402 "B<CAP_BLOCK_SUSPEND> capability, then the B<EPOLLWAKEUP> flag is I<silently "
1403 "ignored>.  This unfortunate behavior is necessary because no validity checks "
1404 "were performed on the I<flags> argument in the original implementation, and "
1405 "the addition of the B<EPOLLWAKEUP> with a check that caused the call to fail "
1406 "if the caller did not have the B<CAP_BLOCK_SUSPEND> capability caused a "
1407 "breakage in at least one existing user-space application that happened to "
1408 "randomly (and uselessly) specify this bit.  A robust application should "
1409 "therefore double check that it has the B<CAP_BLOCK_SUSPEND> capability if "
1410 "attempting to use the B<EPOLLWAKEUP> flag."
1411 msgstr ""
1412
1413 #. type: Plain text
1414 #: build/C/man2/epoll_ctl.2:315
1415 msgid "B<epoll_create>(2), B<epoll_wait>(2), B<poll>(2), B<epoll>(7)"
1416 msgstr ""
1417
1418 #. type: TH
1419 #: build/C/man2/epoll_wait.2:22
1420 #, no-wrap
1421 msgid "EPOLL_WAIT"
1422 msgstr ""
1423
1424 #. type: TH
1425 #: build/C/man2/epoll_wait.2:22
1426 #, no-wrap
1427 msgid "2014-08-19"
1428 msgstr ""
1429
1430 #. type: Plain text
1431 #: build/C/man2/epoll_wait.2:25
1432 msgid "epoll_wait, epoll_pwait - wait for an I/O event on an epoll file descriptor"
1433 msgstr ""
1434
1435 #. type: Plain text
1436 #: build/C/man2/epoll_wait.2:34
1437 #, no-wrap
1438 msgid ""
1439 "B<int epoll_wait(int >I<epfd>B<, struct epoll_event *>I<events>B<,>\n"
1440 "B<               int >I<maxevents>B<, int >I<timeout>B<);>\n"
1441 "B<int epoll_pwait(int >I<epfd>B<, struct epoll_event *>I<events>B<,>\n"
1442 "B<               int >I<maxevents>B<, int >I<timeout>B<,>\n"
1443 "B<               const sigset_t *>I<sigmask>B<);>\n"
1444 msgstr ""
1445
1446 #. type: Plain text
1447 #: build/C/man2/epoll_wait.2:52
1448 msgid ""
1449 "The B<epoll_wait>()  system call waits for events on the B<epoll>(7)  "
1450 "instance referred to by the file descriptor I<epfd>.  The memory area "
1451 "pointed to by I<events> will contain the events that will be available for "
1452 "the caller.  Up to I<maxevents> are returned by B<epoll_wait>().  The "
1453 "I<maxevents> argument must be greater than zero."
1454 msgstr ""
1455
1456 #. type: Plain text
1457 #: build/C/man2/epoll_wait.2:59
1458 msgid ""
1459 "The I<timeout> argument specifies the number of milliseconds that "
1460 "B<epoll_wait>()  will block.  The call will block until either:"
1461 msgstr ""
1462
1463 #. type: Plain text
1464 #: build/C/man2/epoll_wait.2:61
1465 msgid "a file descriptor delivers an event;"
1466 msgstr ""
1467
1468 #. type: Plain text
1469 #: build/C/man2/epoll_wait.2:63 build/C/man2/poll.2:138
1470 msgid "the call is interrupted by a signal handler; or"
1471 msgstr ""
1472
1473 #. type: Plain text
1474 #: build/C/man2/epoll_wait.2:65 build/C/man2/poll.2:140
1475 msgid "the timeout expires."
1476 msgstr ""
1477
1478 #. type: Plain text
1479 #: build/C/man2/epoll_wait.2:80
1480 msgid ""
1481 "Note that the I<timeout> interval will be rounded up to the system clock "
1482 "granularity, and kernel scheduling delays mean that the blocking interval "
1483 "may overrun by a small amount.  Specifying a I<timeout> of -1 causes "
1484 "B<epoll_wait>()  to block indefinitely, while specifying a I<timeout> equal "
1485 "to zero cause B<epoll_wait>()  to return immediately, even if no events are "
1486 "available."
1487 msgstr ""
1488
1489 #. type: Plain text
1490 #: build/C/man2/epoll_wait.2:84
1491 msgid "The I<struct epoll_event> is defined as:"
1492 msgstr ""
1493
1494 #. type: Plain text
1495 #: build/C/man2/epoll_wait.2:93
1496 #, no-wrap
1497 msgid ""
1498 "typedef union epoll_data {\n"
1499 "    void    *ptr;\n"
1500 "    int      fd;\n"
1501 "    uint32_t u32;\n"
1502 "    uint64_t u64;\n"
1503 "} epoll_data_t;\n"
1504 msgstr ""
1505
1506 #. type: Plain text
1507 #: build/C/man2/epoll_wait.2:98
1508 #, no-wrap
1509 msgid ""
1510 "struct epoll_event {\n"
1511 "    uint32_t     events;    /* Epoll events */\n"
1512 "    epoll_data_t data;      /* User data variable */\n"
1513 "};\n"
1514 msgstr ""
1515
1516 #. type: Plain text
1517 #: build/C/man2/epoll_wait.2:109
1518 msgid ""
1519 "The I<data> of each returned structure will contain the same data the user "
1520 "set with an B<epoll_ctl>(2)  (B<EPOLL_CTL_ADD>, B<EPOLL_CTL_MOD>)  while the "
1521 "I<events> member will contain the returned event bit field."
1522 msgstr ""
1523
1524 #. type: SS
1525 #: build/C/man2/epoll_wait.2:109
1526 #, no-wrap
1527 msgid "epoll_pwait()"
1528 msgstr ""
1529
1530 #. type: Plain text
1531 #: build/C/man2/epoll_wait.2:123
1532 msgid ""
1533 "The relationship between B<epoll_wait>()  and B<epoll_pwait>()  is analogous "
1534 "to the relationship between B<select>(2)  and B<pselect>(2): like "
1535 "B<pselect>(2), B<epoll_pwait>()  allows an application to safely wait until "
1536 "either a file descriptor becomes ready or until a signal is caught."
1537 msgstr ""
1538
1539 #. type: Plain text
1540 #: build/C/man2/epoll_wait.2:127
1541 msgid "The following B<epoll_pwait>()  call:"
1542 msgstr ""
1543
1544 #. type: Plain text
1545 #: build/C/man2/epoll_wait.2:130
1546 #, no-wrap
1547 msgid "    ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);\n"
1548 msgstr ""
1549
1550 #. type: Plain text
1551 #: build/C/man2/epoll_wait.2:135 build/C/man2/poll.2:250
1552 msgid "is equivalent to I<atomically> executing the following calls:"
1553 msgstr ""
1554
1555 #. type: Plain text
1556 #: build/C/man2/epoll_wait.2:138
1557 #, no-wrap
1558 msgid "    sigset_t origmask;\n"
1559 msgstr ""
1560
1561 #. type: Plain text
1562 #: build/C/man2/epoll_wait.2:142
1563 #, no-wrap
1564 msgid ""
1565 "    sigprocmask(SIG_SETMASK, &sigmask, &origmask);\n"
1566 "    ready = epoll_wait(epfd, &events, maxevents, timeout);\n"
1567 "    sigprocmask(SIG_SETMASK, &origmask, NULL);\n"
1568 msgstr ""
1569
1570 #. type: Plain text
1571 #: build/C/man2/epoll_wait.2:150
1572 msgid ""
1573 "The I<sigmask> argument may be specified as NULL, in which case "
1574 "B<epoll_pwait>()  is equivalent to B<epoll_wait>()."
1575 msgstr ""
1576
1577 #. type: Plain text
1578 #: build/C/man2/epoll_wait.2:162
1579 msgid ""
1580 "When successful, B<epoll_wait>()  returns the number of file descriptors "
1581 "ready for the requested I/O, or zero if no file descriptor became ready "
1582 "during the requested I<timeout> milliseconds.  When an error occurs, "
1583 "B<epoll_wait>()  returns -1 and I<errno> is set appropriately."
1584 msgstr ""
1585
1586 #. type: Plain text
1587 #: build/C/man2/epoll_wait.2:167
1588 msgid "I<epfd> is not a valid file descriptor."
1589 msgstr ""
1590
1591 #. type: TP
1592 #: build/C/man2/epoll_wait.2:167 build/C/man2/poll.2:312
1593 #, no-wrap
1594 msgid "B<EFAULT>"
1595 msgstr ""
1596
1597 #. type: Plain text
1598 #: build/C/man2/epoll_wait.2:172
1599 msgid ""
1600 "The memory area pointed to by I<events> is not accessible with write "
1601 "permissions."
1602 msgstr ""
1603
1604 #. type: TP
1605 #: build/C/man2/epoll_wait.2:172 build/C/man2/poll.2:316
1606 #, no-wrap
1607 msgid "B<EINTR>"
1608 msgstr ""
1609
1610 #. type: Plain text
1611 #: build/C/man2/epoll_wait.2:179
1612 msgid ""
1613 "The call was interrupted by a signal handler before either (1) any of the "
1614 "requested events occurred or (2) the I<timeout> expired; see B<signal>(7)."
1615 msgstr ""
1616
1617 #. type: Plain text
1618 #: build/C/man2/epoll_wait.2:187
1619 msgid ""
1620 "I<epfd> is not an B<epoll> file descriptor, or I<maxevents> is less than or "
1621 "equal to zero."
1622 msgstr ""
1623
1624 #.  To be precise: kernel 2.5.44.
1625 #.  The interface should be finalized by Linux kernel 2.5.66.
1626 #. type: Plain text
1627 #: build/C/man2/epoll_wait.2:193
1628 msgid ""
1629 "B<epoll_wait>()  was added to the kernel in version 2.6.  Library support is "
1630 "provided in glibc starting with version 2.3.2."
1631 msgstr ""
1632
1633 #. type: Plain text
1634 #: build/C/man2/epoll_wait.2:197
1635 msgid ""
1636 "B<epoll_pwait>()  was added to Linux in kernel 2.6.19.  Library support is "
1637 "provided in glibc starting with version 2.6."
1638 msgstr ""
1639
1640 #. type: Plain text
1641 #: build/C/man2/epoll_wait.2:200
1642 msgid "B<epoll_wait>()  is Linux-specific."
1643 msgstr ""
1644
1645 #. type: Plain text
1646 #: build/C/man2/epoll_wait.2:210
1647 msgid ""
1648 "While one thread is blocked in a call to B<epoll_pwait>(), it is possible "
1649 "for another thread to add a file descriptor to the waited-upon B<epoll> "
1650 "instance.  If the new file descriptor becomes ready, it will cause the "
1651 "B<epoll_wait>()  call to unblock."
1652 msgstr ""
1653
1654 #. type: Plain text
1655 #: build/C/man2/epoll_wait.2:217
1656 msgid ""
1657 "For a discussion of what may happen if a file descriptor in an B<epoll> "
1658 "instance being monitored by B<epoll_wait>()  is closed in another thread, "
1659 "see B<select>(2)."
1660 msgstr ""
1661
1662 #. type: Plain text
1663 #: build/C/man2/epoll_wait.2:229
1664 msgid ""
1665 "In kernels before 2.6.37, a I<timeout> value larger than approximately "
1666 "I<LONG_MAX / HZ> milliseconds is treated as -1 (i.e., infinity).  Thus, for "
1667 "example, on a system where the I<sizeof(long)> is 4 and the kernel I<HZ> "
1668 "value is 1000, this means that timeouts greater than 35.79 minutes are "
1669 "treated as infinity."
1670 msgstr ""
1671
1672 #. type: SS
1673 #: build/C/man2/epoll_wait.2:229 build/C/man2/poll.2:366
1674 #, no-wrap
1675 msgid "C library/kernel ABI differences"
1676 msgstr ""
1677
1678 #. type: Plain text
1679 #: build/C/man2/epoll_wait.2:242
1680 msgid ""
1681 "The raw B<epoll_pwait>()  system call has a sixth argument, I<size_t "
1682 "sigsetsize>, which specifies the size in bytes of the I<sigmask> argument.  "
1683 "The glibc B<epoll_pwait>()  wrapper function specifies this argument as a "
1684 "fixed value (equal to I<sizeof(sigset_t)>)."
1685 msgstr ""
1686
1687 #. type: Plain text
1688 #: build/C/man2/epoll_wait.2:245
1689 msgid "B<epoll_create>(2), B<epoll_ctl>(2), B<epoll>(7)"
1690 msgstr ""
1691
1692 #. type: TH
1693 #: build/C/man2/poll.2:31
1694 #, no-wrap
1695 msgid "POLL"
1696 msgstr ""
1697
1698 #. type: TH
1699 #: build/C/man2/poll.2:31
1700 #, no-wrap
1701 msgid "2014-09-06"
1702 msgstr ""
1703
1704 #. type: Plain text
1705 #: build/C/man2/poll.2:34
1706 msgid "poll, ppoll - wait for some event on a file descriptor"
1707 msgstr ""
1708
1709 #. type: Plain text
1710 #: build/C/man2/poll.2:37
1711 #, no-wrap
1712 msgid "B<#include E<lt>poll.hE<gt>>\n"
1713 msgstr ""
1714
1715 #. type: Plain text
1716 #: build/C/man2/poll.2:39
1717 #, no-wrap
1718 msgid ""
1719 "B<int poll(struct pollfd *>I<fds>B<, nfds_t >I<nfds>B<, int "
1720 ">I<timeout>B<);>\n"
1721 msgstr ""
1722
1723 #. type: Plain text
1724 #: build/C/man2/poll.2:43
1725 #, no-wrap
1726 msgid ""
1727 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
1728 "B<#include E<lt>signal.hE<gt>>\n"
1729 "B<#include E<lt>poll.hE<gt>>\n"
1730 msgstr ""
1731
1732 #. type: Plain text
1733 #: build/C/man2/poll.2:46
1734 #, no-wrap
1735 msgid ""
1736 "B<int ppoll(struct pollfd *>I<fds>B<, nfds_t >I<nfds>B<, >\n"
1737 "B<        const struct timespec *>I<timeout_ts>B<, const sigset_t "
1738 "*>I<sigmask>B<);>\n"
1739 msgstr ""
1740
1741 #. type: Plain text
1742 #: build/C/man2/poll.2:53
1743 msgid ""
1744 "B<poll>()  performs a similar task to B<select>(2): it waits for one of a "
1745 "set of file descriptors to become ready to perform I/O."
1746 msgstr ""
1747
1748 #. type: Plain text
1749 #: build/C/man2/poll.2:57
1750 msgid ""
1751 "The set of file descriptors to be monitored is specified in the I<fds> "
1752 "argument, which is an array of structures of the following form:"
1753 msgstr ""
1754
1755 #. type: Plain text
1756 #: build/C/man2/poll.2:65
1757 #, no-wrap
1758 msgid ""
1759 "struct pollfd {\n"
1760 "    int   fd;         /* file descriptor */\n"
1761 "    short events;     /* requested events */\n"
1762 "    short revents;    /* returned events */\n"
1763 "};\n"
1764 msgstr ""
1765
1766 #. type: Plain text
1767 #: build/C/man2/poll.2:72
1768 msgid ""
1769 "The caller should specify the number of items in the I<fds> array in "
1770 "I<nfds>."
1771 msgstr ""
1772
1773 #. type: Plain text
1774 #: build/C/man2/poll.2:88
1775 msgid ""
1776 "The field I<fd> contains a file descriptor for an open file.  If this field "
1777 "is negative, then the corresponding I<events> field is ignored and the "
1778 "I<revents> field returns zero.  (This provides an easy way of ignoring a "
1779 "file descriptor for a single B<poll>()  call: simply negate the I<fd> "
1780 "field.  Note, however, that this technique can't be used to ignore file "
1781 "descriptor 0.)"
1782 msgstr ""
1783
1784 #. type: Plain text
1785 #: build/C/man2/poll.2:103
1786 msgid ""
1787 "The field I<events> is an input parameter, a bit mask specifying the events "
1788 "the application is interested in for the file descriptor I<fd>.  This field "
1789 "may be specified as zero, in which case the only events that can be returned "
1790 "in I<revents> are B<POLLHUP>, B<POLLERR>, and B<POLLNVAL> (see below)."
1791 msgstr ""
1792
1793 #. type: Plain text
1794 #: build/C/man2/poll.2:122
1795 msgid ""
1796 "The field I<revents> is an output parameter, filled by the kernel with the "
1797 "events that actually occurred.  The bits returned in I<revents> can include "
1798 "any of those specified in I<events>, or one of the values B<POLLERR>, "
1799 "B<POLLHUP>, or B<POLLNVAL>.  (These three bits are meaningless in the "
1800 "I<events> field, and will be set in the I<revents> field whenever the "
1801 "corresponding condition is true.)"
1802 msgstr ""
1803
1804 #. type: Plain text
1805 #: build/C/man2/poll.2:127
1806 msgid ""
1807 "If none of the events requested (and no error) has occurred for any of the "
1808 "file descriptors, then B<poll>()  blocks until one of the events occurs."
1809 msgstr ""
1810
1811 #. type: Plain text
1812 #: build/C/man2/poll.2:134
1813 msgid ""
1814 "The I<timeout> argument specifies the number of milliseconds that B<poll>()  "
1815 "should block waiting for a file descriptor to become ready.  The call will "
1816 "block until either:"
1817 msgstr ""
1818
1819 #. type: Plain text
1820 #: build/C/man2/poll.2:136
1821 msgid "a file descriptor becomes ready;"
1822 msgstr ""
1823
1824 #. type: Plain text
1825 #: build/C/man2/poll.2:154
1826 msgid ""
1827 "Note that the I<timeout> interval will be rounded up to the system clock "
1828 "granularity, and kernel scheduling delays mean that the blocking interval "
1829 "may overrun by a small amount.  Specifying a negative value in I<timeout> "
1830 "means an infinite timeout.  Specifying a I<timeout> of zero causes B<poll>()  "
1831 "to return immediately, even if no file descriptors are ready."
1832 msgstr ""
1833
1834 #. type: Plain text
1835 #: build/C/man2/poll.2:160
1836 msgid ""
1837 "The bits that may be set/returned in I<events> and I<revents> are defined in "
1838 "I<E<lt>poll.hE<gt>>:"
1839 msgstr ""
1840
1841 #. type: TP
1842 #: build/C/man2/poll.2:161
1843 #, no-wrap
1844 msgid "B<POLLIN>"
1845 msgstr ""
1846
1847 #. type: Plain text
1848 #: build/C/man2/poll.2:164
1849 msgid "There is data to read."
1850 msgstr ""
1851
1852 #. type: TP
1853 #: build/C/man2/poll.2:164
1854 #, no-wrap
1855 msgid "B<POLLPRI>"
1856 msgstr ""
1857
1858 #. type: Plain text
1859 #: build/C/man2/poll.2:168
1860 msgid ""
1861 "There is urgent data to read (e.g., out-of-band data on TCP socket; "
1862 "pseudoterminal master in packet mode has seen state change in slave)."
1863 msgstr ""
1864
1865 #. type: TP
1866 #: build/C/man2/poll.2:168
1867 #, no-wrap
1868 msgid "B<POLLOUT>"
1869 msgstr ""
1870
1871 #. type: Plain text
1872 #: build/C/man2/poll.2:174
1873 msgid ""
1874 "Writing is now possible, though a write larger that the available space in a "
1875 "socket or pipe will still block (unless B<O_NONBLOCK> is set)."
1876 msgstr ""
1877
1878 #. type: TP
1879 #: build/C/man2/poll.2:174
1880 #, no-wrap
1881 msgid "B<POLLRDHUP> (since Linux 2.6.17)"
1882 msgstr ""
1883
1884 #. type: Plain text
1885 #: build/C/man2/poll.2:185
1886 msgid ""
1887 "Stream socket peer closed connection, or shut down writing half of "
1888 "connection.  The B<_GNU_SOURCE> feature test macro must be defined (before "
1889 "including I<any> header files)  in order to obtain this definition."
1890 msgstr ""
1891
1892 #. type: TP
1893 #: build/C/man2/poll.2:185
1894 #, no-wrap
1895 msgid "B<POLLERR>"
1896 msgstr ""
1897
1898 #. type: Plain text
1899 #: build/C/man2/poll.2:188
1900 msgid "Error condition (output only)."
1901 msgstr ""
1902
1903 #. type: TP
1904 #: build/C/man2/poll.2:188
1905 #, no-wrap
1906 msgid "B<POLLHUP>"
1907 msgstr ""
1908
1909 #. type: Plain text
1910 #: build/C/man2/poll.2:191
1911 msgid "Hang up (output only)."
1912 msgstr ""
1913
1914 #. type: TP
1915 #: build/C/man2/poll.2:191
1916 #, no-wrap
1917 msgid "B<POLLNVAL>"
1918 msgstr ""
1919
1920 #. type: Plain text
1921 #: build/C/man2/poll.2:196
1922 msgid "Invalid request: I<fd> not open (output only)."
1923 msgstr ""
1924
1925 #. type: Plain text
1926 #: build/C/man2/poll.2:202
1927 msgid ""
1928 "When compiling with B<_XOPEN_SOURCE> defined, one also has the following, "
1929 "which convey no further information beyond the bits listed above:"
1930 msgstr ""
1931
1932 #. type: TP
1933 #: build/C/man2/poll.2:203
1934 #, no-wrap
1935 msgid "B<POLLRDNORM>"
1936 msgstr ""
1937
1938 #. type: Plain text
1939 #: build/C/man2/poll.2:207
1940 msgid "Equivalent to B<POLLIN>."
1941 msgstr ""
1942
1943 #. type: TP
1944 #: build/C/man2/poll.2:207
1945 #, no-wrap
1946 msgid "B<POLLRDBAND>"
1947 msgstr ""
1948
1949 #.  POLLRDBAND is used in the DECnet protocol.
1950 #. type: Plain text
1951 #: build/C/man2/poll.2:211
1952 msgid "Priority band data can be read (generally unused on Linux)."
1953 msgstr ""
1954
1955 #. type: TP
1956 #: build/C/man2/poll.2:211
1957 #, no-wrap
1958 msgid "B<POLLWRNORM>"
1959 msgstr ""
1960
1961 #. type: Plain text
1962 #: build/C/man2/poll.2:215
1963 msgid "Equivalent to B<POLLOUT>."
1964 msgstr ""
1965
1966 #. type: TP
1967 #: build/C/man2/poll.2:215
1968 #, no-wrap
1969 msgid "B<POLLWRBAND>"
1970 msgstr ""
1971
1972 #. type: Plain text
1973 #: build/C/man2/poll.2:218
1974 msgid "Priority data may be written."
1975 msgstr ""
1976
1977 #. type: Plain text
1978 #: build/C/man2/poll.2:222
1979 msgid "Linux also knows about, but does not use B<POLLMSG>."
1980 msgstr ""
1981
1982 #. type: SS
1983 #: build/C/man2/poll.2:222
1984 #, no-wrap
1985 msgid "ppoll()"
1986 msgstr ""
1987
1988 #. type: Plain text
1989 #: build/C/man2/poll.2:236
1990 msgid ""
1991 "The relationship between B<poll>()  and B<ppoll>()  is analogous to the "
1992 "relationship between B<select>(2)  and B<pselect>(2): like B<pselect>(2), "
1993 "B<ppoll>()  allows an application to safely wait until either a file "
1994 "descriptor becomes ready or until a signal is caught."
1995 msgstr ""
1996
1997 #. type: Plain text
1998 #: build/C/man2/poll.2:242
1999 msgid ""
2000 "Other than the difference in the precision of the I<timeout> argument, the "
2001 "following B<ppoll>()  call:"
2002 msgstr ""
2003
2004 #. type: Plain text
2005 #: build/C/man2/poll.2:245
2006 #, no-wrap
2007 msgid "    ready = ppoll(&fds, nfds, timeout_ts, &sigmask);\n"
2008 msgstr ""
2009
2010 #. type: Plain text
2011 #: build/C/man2/poll.2:254
2012 #, no-wrap
2013 msgid ""
2014 "    sigset_t origmask;\n"
2015 "    int timeout;\n"
2016 msgstr ""
2017
2018 #. type: Plain text
2019 #: build/C/man2/poll.2:260
2020 #, no-wrap
2021 msgid ""
2022 "    timeout = (timeout_ts == NULL) ? -1 :\n"
2023 "              (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);\n"
2024 "    sigprocmask(SIG_SETMASK, &sigmask, &origmask);\n"
2025 "    ready = poll(&fds, nfds, timeout);\n"
2026 "    sigprocmask(SIG_SETMASK, &origmask, NULL);\n"
2027 msgstr ""
2028
2029 #. type: Plain text
2030 #: build/C/man2/poll.2:267
2031 msgid ""
2032 "See the description of B<pselect>(2)  for an explanation of why B<ppoll>()  "
2033 "is necessary."
2034 msgstr ""
2035
2036 #. type: Plain text
2037 #: build/C/man2/poll.2:279
2038 msgid ""
2039 "If the I<sigmask> argument is specified as NULL, then no signal mask "
2040 "manipulation is performed (and thus B<ppoll>()  differs from B<poll>()  only "
2041 "in the precision of the I<timeout> argument)."
2042 msgstr ""
2043
2044 #. type: Plain text
2045 #: build/C/man2/poll.2:286
2046 msgid ""
2047 "The I<timeout_ts> argument specifies an upper limit on the amount of time "
2048 "that B<ppoll>()  will block.  This argument is a pointer to a structure of "
2049 "the following form:"
2050 msgstr ""
2051
2052 #. type: Plain text
2053 #: build/C/man2/poll.2:293
2054 #, no-wrap
2055 msgid ""
2056 "struct timespec {\n"
2057 "    long    tv_sec;         /* seconds */\n"
2058 "    long    tv_nsec;        /* nanoseconds */\n"
2059 "};\n"
2060 msgstr ""
2061
2062 #. type: Plain text
2063 #: build/C/man2/poll.2:301
2064 msgid ""
2065 "If I<timeout_ts> is specified as NULL, then B<ppoll>()  can block "
2066 "indefinitely."
2067 msgstr ""
2068
2069 #. type: Plain text
2070 #: build/C/man2/poll.2:311
2071 msgid ""
2072 "On success, a positive number is returned; this is the number of structures "
2073 "which have nonzero I<revents> fields (in other words, those descriptors with "
2074 "events or errors reported).  A value of 0 indicates that the call timed out "
2075 "and no file descriptors were ready.  On error, -1 is returned, and I<errno> "
2076 "is set appropriately."
2077 msgstr ""
2078
2079 #. type: Plain text
2080 #: build/C/man2/poll.2:316
2081 msgid ""
2082 "The array given as argument was not contained in the calling program's "
2083 "address space."
2084 msgstr ""
2085
2086 #. type: Plain text
2087 #: build/C/man2/poll.2:320
2088 msgid "A signal occurred before any requested event; see B<signal>(7)."
2089 msgstr ""
2090
2091 #. type: Plain text
2092 #: build/C/man2/poll.2:327
2093 msgid "The I<nfds> value exceeds the B<RLIMIT_NOFILE> value."
2094 msgstr ""
2095
2096 #. type: Plain text
2097 #: build/C/man2/poll.2:330
2098 msgid "There was no space to allocate file descriptor tables."
2099 msgstr ""
2100
2101 #.  library call was introduced in libc 5.4.28
2102 #. type: Plain text
2103 #: build/C/man2/poll.2:340
2104 msgid ""
2105 "The B<poll>()  system call was introduced in Linux 2.1.23.  On older kernels "
2106 "that lack this system call, the glibc (and the old Linux libc)  B<poll>()  "
2107 "wrapper function provides emulation using B<select>(2)."
2108 msgstr ""
2109
2110 #. type: Plain text
2111 #: build/C/man2/poll.2:347
2112 msgid ""
2113 "The B<ppoll>()  system call was added to Linux in kernel 2.6.16.  The "
2114 "B<ppoll>()  library call was added in glibc 2.4."
2115 msgstr ""
2116
2117 #.  NetBSD 3.0 has a pollts() which is like Linux ppoll().
2118 #. type: Plain text
2119 #: build/C/man2/poll.2:353
2120 msgid "B<poll>()  conforms to POSIX.1-2001.  B<ppoll>()  is Linux-specific."
2121 msgstr ""
2122
2123 #. type: Plain text
2124 #: build/C/man2/poll.2:361
2125 msgid ""
2126 "Some implementations define the nonstandard constant B<INFTIM> with the "
2127 "value -1 for use as a I<timeout> for B<poll>().  This constant is not "
2128 "provided in glibc."
2129 msgstr ""
2130
2131 #. type: Plain text
2132 #: build/C/man2/poll.2:366
2133 msgid ""
2134 "For a discussion of what may happen if a file descriptor being monitored by "
2135 "B<poll>()  is closed in another thread, see B<select>(2)."
2136 msgstr ""
2137
2138 #. type: Plain text
2139 #: build/C/man2/poll.2:380
2140 msgid ""
2141 "The Linux B<ppoll>()  system call modifies its I<timeout_ts> argument.  "
2142 "However, the glibc wrapper function hides this behavior by using a local "
2143 "variable for the timeout argument that is passed to the system call.  Thus, "
2144 "the glibc B<ppoll>()  function does not modify its I<timeout_ts> argument."
2145 msgstr ""
2146
2147 #. type: Plain text
2148 #: build/C/man2/poll.2:393
2149 msgid ""
2150 "The raw B<ppoll>()  system call has a fifth argument, I<size_t sigsetsize>, "
2151 "which specifies the size in bytes of the I<sigmask> argument.  The glibc "
2152 "B<ppoll>()  wrapper function specifies this argument as a fixed value (equal "
2153 "to I<sizeof(sigset_t)>)."
2154 msgstr ""
2155
2156 #. type: Plain text
2157 #: build/C/man2/poll.2:397
2158 msgid ""
2159 "See the discussion of spurious readiness notifications under the BUGS "
2160 "section of B<select>(2)."
2161 msgstr ""
2162
2163 #. type: Plain text
2164 #: build/C/man2/poll.2:401
2165 msgid "B<restart_syscall>(2), B<select>(2), B<select_tut>(2), B<time>(7)"
2166 msgstr ""