1 '\" te
   2 .\"  Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
   3 .\"  This file and its contents are supplied under the terms of the
   4 .\"  Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\"  You may only use this file in accordance with the terms of version
   6 .\"  1.0 of the CDDL.
   7 .\" 
   8 .\"  A full copy of the text of the CDDL should have accompanied this
   9 .\"  source.  A copy of the CDDL is also available via the Internet at
  10 .\"  http://www.illumos.org/license/CDDL.
  11 .TH INOTIFY_INIT 3C "Sep 17, 2014"
  12 .SH NAME
  13 inotify_init, inotify_init1 \- initialize an inotify instance
  14 .SH SYNOPSIS
  15 
  16 .LP
  17 .nf
  18 #include <sys/inotify.h>
  19 
  20 \fBint\fR \fBinotify_init\fR(\fBvoid\fR);
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBint\fR \fBinotify_init1\fR(\fBint\fR \fIflags\fR);
  26 .fi
  27 
  28 .SH DESCRIPTION
  29 .sp
  30 .LP
  31 The \fBinotify_init()\fR and \fBinotify_init1()\fR functions both create an
  32 \fBinotify\fR(5) instance that can be operated upon via
  33 \fBinotify_add_watch\fR(3C), \fBinotify_rm_watch\fR(3C) and \fBread\fR(2).
  34 \fBinotify\fR instances are
  35 represented as file descriptors, and should be closed via \fBclose\fR(2).
  36 
  37 The only difference between the two functions is their signature;
  38 \fBinotify_init()\fR takes no arguments,
  39 while \fBinotify_init1()\fR takes a \fIflags\fR argument that can have
  40 any of the following values:
  41 
  42 .sp
  43 .ne 2
  44 .na
  45 \fBIN_CLOEXEC\fR
  46 .ad
  47 .RS 12n
  48 Instance should be closed upon an
  49 \fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR.
  50 .RE
  51 
  52 .sp
  53 .ne 2
  54 .na
  55 \fBIN_NONBLOCK\fR
  56 .ad
  57 .RS 12n
  58 Instance will be set to be non-blocking.  A \fBread\fR(2) on an
  59 \fBinotify\fR instance that has been initialized with
  60 \fBIN_NONBLOCK\fR will return \fBEAGAIN\fR if there are
  61 no events enqueued in lieu of blocking.
  62 .RE
  63 
  64 .SH RETURN VALUES
  65 .sp
  66 .LP
  67 Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno
  68 is set to indicate the error.
  69 .SH ERRORS
  70 .sp
  71 .LP
  72 The \fBinotify_init()\fR and \fBinotify_init1()\fR functions will fail if:
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBEINVAL\fR\fR
  77 .ad
  78 .RS 10n
  79 The \fIflags\fR are invalid (\fBinotify_init1()\fR).
  80 .RE
  81 
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBEMFILE\fR\fR
  86 .ad
  87 .RS 10n
  88 There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling
  89 process, or the maximum number of \fBinotify\fR instances for the user 
  90 would be exceeded.
  91 .RE
  92 
  93 .sp
  94 .SH NOTES
  95 .sp
  96 .LP
  97 
  98 While the \fBinotify\fR(5) facility is implemented for purposes of
  99 offering compatibility for Linux-borne applications, native
 100 applications may opt to use it instead of (or in addition to) the 
 101 \fBPORT_SOURCE_FILE\fR capability of event ports.  See
 102 \fBinotify\fR(5) for details and restrictions.
 103 
 104 .SH SEE ALSO
 105 .sp
 106 .LP
 107 \fBinotiy_add_watch\fR(3C), \fBinotify_rm_watch\fR(3C), \fBinotify\fR(5)