'\" te
.\"  Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
.\"  This file and its contents are supplied under the terms of the
.\"  Common Development and Distribution License ("CDDL"), version 1.0.
.\"  You may only use this file in accordance with the terms of version
.\"  1.0 of the CDDL.
.\" 
.\"  A full copy of the text of the CDDL should have accompanied this
.\"  source.  A copy of the CDDL is also available via the Internet at
.\"  http://www.illumos.org/license/CDDL.
.TH INOTIFY_ADD_WATCH 3C "Sep 17, 2014"
.SH NAME
inotify_add_watch \- add a watch to an inotify instance
.SH SYNOPSIS

.LP
.nf
#include <sys/inotify.h>

\fBint\fR \fBinotify_add_watch\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpathname\fR, \fBuint32_t\fR \fImask\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBinotify_add_watch()\fR function adds a watch for the file or
directory specified by \fIpathname\fR to the inotify instance 
specified by \fIfd\fR for the events specified by \fImask\fR.  See
\fBinotify\fR(5) for details on the meaning of \fImask\fR, how
it affects the interpretation of \fIpathname\fR, and how 
events for the watched file or directory are subsequently 
retrieved via \fBread\fR(2).

.SH RETURN VALUES
.sp
.LP
Upon succesful completion, \fBinotify_add_watch()\fR returns the
watch descriptor associated with the new watch.
If an error occurs, -1 is returned and errno is set to indicate
the error.

.SH ERRORS
.sp
.LP
\fBinotify_add_watch()\fR will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
\fIpathname\fR could not be opened for reading.
.RE

.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
The \fIfd\fR argument is not a valid open file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The memory associated with \fIpathname\fR was not mapped.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIfd\fR argument does not correspond to an
\fBinotify\fR(5) instance as initialized with 
\fBinotify_init\fR(3C) or \fBinotify_init1\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBENOSPC\fR\fR
.ad
.RS 10n
The number of watches on the specified instance would exceed the
maximum number of watches per \fBinotify\fR(5) instance.
.RE

.sp
.ne 2
.na
\fB\fBENOTDIR\fR\fR
.ad
.RS 10n
\fIpathname\fR does not correspond to a directory and 
\fBIN_ONLYDIR\fR was specified in \fImask\fR.
.RE

.sp
.SH NOTES
.sp
.LP

While the \fBinotify\fR(5) facility is implemented for purposes of
offering compatibility for Linux-borne applications, native
applications may opt to use it instead of (or in addition to) the 
\fBPORT_SOURCE_FILE\fR capability of event ports.  See
\fBinotify\fR(5) for details and restrictions.

.SH SEE ALSO
.sp
.LP
\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C),
\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C),
\fBinotify\fR(5)