Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIBINOTIFY(3)	       FreeBSD Library Functions Manual		 LIBINOTIFY(3)

NAME
     libinotify, inotify_init, inotify_init1, inotify_add_watch,
     inotify_rm_watch, inotify_set_param, inotify_event, -- monitor file sys-
     tem events

SYNOPSIS
     #include <sys/inotify.h>

     int
     inotify_init();

     int
     inotify_init1(int flags);

     int
     inotify_add_watch(int fd, const char *pathname, uint32_t mask);

     int
     inotify_rm_watch(int fd, int wd);

     int
     inotify_set_param(int fd, int param, intptr_t value);

DESCRIPTION
     The inotify_init()	and inotify_init1() functions create an	inotify	in-
     stance and	returns	a file descriptor referring to the instance.
     inotify_init1() function is similar to inotify_init() except that it
     takes additional flags parameter whose values can be:

     IN_NONBLOCK	Set I_NONBLOCK file status flag	on the inotify file
			descriptor.

     IN_CLOSEXEC	Set FD_CLOEXEC flag on the new file descriptor.	See
			O_CLOEXEC flag in open(2)

     The function returns the file descritor to	the inotify handle if success-
     ful otherwise return -1. Possible errorno values are -

     EINVAL		Invalid	flag value passed.

     EMFILE		System wide limit of inotify instances reached.

     ENFILE		System limit on	total number of	fd's reached.

     ENOMEM		Insufficient kernel memory.

     inotify_add_watch() function adds news watch to the inotify instance.
     List of possible masks are	described below. If the	watch for given	file-
     name already exists, it it	updated	with the new mask value	passed.	The
     function returns an integer called	watch descriptor if successful other-
     wise -1.

     Possible values for errorno are -

     EACCES		Permission for read access is denied for given file.

     EBADF		Invalid	file descriptor.

     EFAULT		Pathname points	outside	process's allocated address
			space.

     EINVAL		Invalid	event mask passed.

     ENOENT		A component of path that must exist does not exist.

     ENOMEM		Insufficient kernel memory available.

     ENOSPC		User limit on total number of inotify watches has
			crossed	or kernel failed to allocate a needed re-
			source.

     inotify_rm_watch()	function removes watch wd from the instance described
     by	file descriptor	fd.  The function returns zero on sucess and -1	on er-
     ror. Possible errorno values are -

     EBADF		Invalid	file descriptor	fd.

     EINVAL		Invalid	watch descriptor wd.

     inotify_set_param() Libinotify specific. Replacement for Linux procfs in-
     terface.  Set inotify instance parameter. Possible	param values are -

     IN_SOCKBUFSIZE	Size of	communication socket buffer in bytes. Should
			match read(2) buffer size for libinotify event con-
			sumers.	 Lower values can cause	partial	event reads.
			Bigger values is just a	wasting	of memory.  Default
			value is arbitrary, has	been acquired from code	sample
			in linux inotify(7) man	page and seems to be very com-
			mon among the inotify clients.	Default	value 4096
			(exported as IN_DEF_SOCKBUFSIZE)

     IN_MAX_QUEUED_EVENTS
			Upper limit on the queue length	per inotify handle.
			linux`s	/proc/sys/fs/inotify/max_queued_events coun-
			terpart.  Default value	16384 (exported	as
			IN_DEF_MAX_QUEUED_EVENTS)

inotify_event structure
     struct inotify_event {
	 int	     wd;       /* Watch	descriptor */
	 uint32_t    mask;     /* Mask of events */
	 uint32_t    cookie;   /* Unique integer associating related events */
	 uint32_t    len;      /* Size of name field */
	 char	     name[];   /* Optional null-terminated name	*/
     };

inotify	events -
     Following are the masks supported by libinotify implementation.
	   IN_OPEN	       File was	opened.
	   IN_ACCESS	       File was	accessed (read).
	   IN_ATTRIB	       Metadata	changed.
	   IN_CREATE	       File/directory was created in watched directory.
	   IN_CLOSE_WRITE      File opened for writing was closed.
	   IN_CLOSE_NOWRITE    File not	opened for writing was closed.
	   IN_DELETE	       File/directory in watched directory was deleted.
	   IN_DELETE_SELF      Watched file/directory was deleted.
	   IN_MODIFY	       File/Directory was modified.
	   IN_MOVE_SELF	       Watched file/directory was moved.
	   IN_MOVED_FROM       A file in watched directory was moved out.
	   IN_MOVED_TO	       A file was moved	into watched directory.
	   IN_ALL_EVENTS       Bit mask	of all the above events.
	   IN_MOVE	       Equal to	IN_MOVED_FROM|IN_MOVED_TO
	   IN_CLOSE	       Equal to	IN_CLOSE_WRITE|IN_CLOSE_NOWRITE

     IN_DELETE_SELF and	IN_MOVE_SELF can occur only for	watched	file/direc-
     tory.  Other events can be	marked for a file/directory in a watched dire-
     cotry. In that case the name of the file for which	event is generated can
     be	read by	'name' field in	inotify_event structure.

     Following are additional bits that	can be set in mask when	calling
     inotify_add_watch() -

     IN_DONT_FOLLOW	Don't derefernce path name if its symlink. (Currently
			not supported).

     IN_EXCL_UNLINK	Do not generate	events for unlinked childrens.

     IN_MASK_ADD	Add event mask for watch for given pathname.

     IN_ONESHOT		Remove watch after retrieving one event.

     IN_ONLYDIR		Only watch the pathname	if it is a directory.

     Following bits may	be set by mask field returned by read(3)

     IN_IGNORED		Watch for removed (explicitely,	revoked	or unmounted).

     IN_ISDIR		Subject	of this	event is a directory.

     IN_Q_OVERFLOW	Event queue has	overflowed.

     IN_UNMOUNT		File system containing watched file/directory was un-
			mounted.

SEE ALSO
     read(3)

HISTORY
     inotify first appeared in Linux 2.6.13

FreeBSD	13.0			April 13, 2017			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | inotify_event structure | inotify events - | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=inotify_init1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help