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_ADD_WATCH 3C "Sep 17, 2014"
  12 .SH NAME
  13 inotify_add_watch \- add a watch to an inotify instance
  14 .SH SYNOPSIS
  15 
  16 .LP
  17 .nf
  18 #include <sys/inotify.h>
  19 
  20 \fBint\fR \fBinotify_add_watch\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpathname\fR, \fBuint32_t\fR \fImask\fR);
  21 .fi
  22 
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBinotify_add_watch()\fR function adds a watch for the file or
  27 directory specified by \fIpathname\fR to the inotify instance 
  28 specified by \fIfd\fR for the events specified by \fImask\fR.  See
  29 \fBinotify\fR(5) for details on the meaning of \fImask\fR, how
  30 it affects the interpretation of \fIpathname\fR, and how 
  31 events for the watched file or directory are subsequently 
  32 retrieved via \fBread\fR(2).
  33 
  34 .SH RETURN VALUES
  35 .sp
  36 .LP
  37 Upon succesful completion, \fBinotify_add_watch()\fR returns the
  38 watch descriptor associated with the new watch.
  39 If an error occurs, -1 is returned and errno is set to indicate
  40 the error.
  41 
  42 .SH ERRORS
  43 .sp
  44 .LP
  45 \fBinotify_add_watch()\fR will fail if:
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fBEACCES\fR\fR
  50 .ad
  51 .RS 10n
  52 \fIpathname\fR could not be opened for reading.
  53 .RE
  54 
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBEBADF\fR\fR
  59 .ad
  60 .RS 10n
  61 The \fIfd\fR argument is not a valid open file descriptor.
  62 .RE
  63 
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBEFAULT\fR\fR
  68 .ad
  69 .RS 10n
  70 The memory associated with \fIpathname\fR was not mapped.
  71 .RE
  72 
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBEINVAL\fR\fR
  77 .ad
  78 .RS 10n
  79 The \fIfd\fR argument does not correspond to an
  80 \fBinotify\fR(5) instance as initialized with 
  81 \fBinotify_init\fR(3C) or \fBinotify_init1\fR(3C).
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBENOSPC\fR\fR
  88 .ad
  89 .RS 10n
  90 The number of watches on the specified instance would exceed the
  91 maximum number of watches per \fBinotify\fR(5) instance.
  92 .RE
  93 
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBENOTDIR\fR\fR
  98 .ad
  99 .RS 10n
 100 \fIpathname\fR does not correspond to a directory and 
 101 \fBIN_ONLYDIR\fR was specified in \fImask\fR.
 102 .RE
 103 
 104 .sp
 105 .SH NOTES
 106 .sp
 107 .LP
 108 
 109 While the \fBinotify\fR(5) facility is implemented for purposes of
 110 offering compatibility for Linux-borne applications, native
 111 applications may opt to use it instead of (or in addition to) the 
 112 \fBPORT_SOURCE_FILE\fR capability of event ports.  See
 113 \fBinotify\fR(5) for details and restrictions.
 114 
 115 .SH SEE ALSO
 116 .sp
 117 .LP
 118 \fBinotify_init\fR(3C), \fBinotify_init1\fR(3C),
 119 \fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C),
 120 \fBinotify\fR(5)