logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

fnmatch.3p (5383B)


  1. '\" et
  2. .TH FNMATCH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. fnmatch
  12. \(em match a filename string or a pathname
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <fnmatch.h>
  17. .P
  18. int fnmatch(const char *\fIpattern\fP, const char *\fIstring\fP, int \fIflags\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIfnmatch\fR()
  23. function shall match patterns as described in the Shell and Utilities volume of POSIX.1\(hy2017,
  24. .IR "Section 2.13.1" ", " "Patterns Matching a Single Character"
  25. and
  26. .IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters".
  27. It checks the string specified by the
  28. .IR string
  29. argument to see if it matches the pattern specified by the
  30. .IR pattern
  31. argument.
  32. .P
  33. The
  34. .IR flags
  35. argument shall modify the interpretation of
  36. .IR pattern
  37. and
  38. .IR string .
  39. It is the bitwise-inclusive OR of zero or more of the flags defined in
  40. .IR <fnmatch.h> .
  41. If the FNM_PATHNAME flag is set in
  42. .IR flags ,
  43. then a
  44. <slash>
  45. character (\c
  46. .BR '/' )
  47. in
  48. .IR string
  49. shall be explicitly matched by a
  50. <slash>
  51. in
  52. .IR pattern ;
  53. it shall not be matched by either the
  54. <asterisk>
  55. or
  56. <question-mark>
  57. special characters, nor by a bracket expression. If the FNM_PATHNAME flag
  58. is not set, the
  59. <slash>
  60. character shall be treated as an ordinary character.
  61. .P
  62. If FNM_NOESCAPE is not set in
  63. .IR flags ,
  64. a
  65. <backslash>
  66. character in
  67. .IR pattern
  68. followed by any other character shall match that second character in
  69. .IR string .
  70. In particular,
  71. .BR \(dq\e\e\(dq
  72. shall match a
  73. <backslash>
  74. in
  75. .IR string .
  76. If
  77. .IR pattern
  78. ends with an unescaped
  79. <backslash>,
  80. \fIfnmatch\fR()
  81. shall return a non-zero value (indicating either no match or an error).
  82. If FNM_NOESCAPE is set, a
  83. <backslash>
  84. character shall be treated as an ordinary character.
  85. .P
  86. If FNM_PERIOD is set in
  87. .IR flags ,
  88. then a leading
  89. <period>
  90. (\c
  91. .BR '.' )
  92. in
  93. .IR string
  94. shall match a
  95. <period>
  96. in
  97. .IR pattern ;
  98. as described by rule 2 in the Shell and Utilities volume of POSIX.1\(hy2017,
  99. .IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion"
  100. where the location of ``leading'' is indicated by the value
  101. of FNM_PATHNAME:
  102. .IP " *" 4
  103. If FNM_PATHNAME is set, a
  104. <period>
  105. is ``leading'' if it is the first character in
  106. .IR string
  107. or if it immediately follows a
  108. <slash>.
  109. .IP " *" 4
  110. If FNM_PATHNAME is not set, a
  111. <period>
  112. is ``leading'' only if it is the first character of
  113. .IR string .
  114. .P
  115. If FNM_PERIOD is not set, then no special restrictions are placed on
  116. matching a period.
  117. .SH "RETURN VALUE"
  118. If
  119. .IR string
  120. matches the pattern specified by
  121. .IR pattern ,
  122. then
  123. \fIfnmatch\fR()
  124. shall return 0. If there is no match,
  125. \fIfnmatch\fR()
  126. shall return FNM_NOMATCH, which is defined in
  127. .IR <fnmatch.h> .
  128. If an error occurs,
  129. \fIfnmatch\fR()
  130. shall return another non-zero value.
  131. .SH ERRORS
  132. No errors are defined.
  133. .LP
  134. .IR "The following sections are informative."
  135. .SH EXAMPLES
  136. None.
  137. .SH "APPLICATION USAGE"
  138. The
  139. \fIfnmatch\fR()
  140. function has two major uses. It could be used by an application or
  141. utility that needs to read a directory and apply a pattern against each
  142. entry. The
  143. .IR find
  144. utility is an example of this. It can also be used by the
  145. .IR pax
  146. utility to process its
  147. .IR pattern
  148. operands, or by applications that need to match strings in a similar
  149. manner.
  150. .P
  151. The name
  152. \fIfnmatch\fR()
  153. is intended to imply
  154. .IR "filename"
  155. match, rather than
  156. .IR "pathname"
  157. match. The default action of this function is to match filename strings,
  158. rather than pathnames, since it gives no special significance to the
  159. <slash>
  160. character. With the FNM_PATHNAME flag,
  161. \fIfnmatch\fR()
  162. does match pathnames, but without tilde expansion, parameter
  163. expansion, or special treatment for a
  164. <period>
  165. at the beginning of a filename.
  166. .SH RATIONALE
  167. This function replaced the REG_FILENAME flag of
  168. \fIregcomp\fR()
  169. in early proposals of this volume of POSIX.1\(hy2017. It provides virtually the same functionality
  170. as the
  171. \fIregcomp\fR()
  172. and
  173. \fIregexec\fR()
  174. functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH
  175. flag was proposed for
  176. \fIregcomp\fR(),
  177. and would have had the opposite effect from FNM_PATHNAME), but with a
  178. simpler function and less system overhead.
  179. .SH "FUTURE DIRECTIONS"
  180. None.
  181. .SH "SEE ALSO"
  182. .IR "\fIglob\fR\^(\|)",
  183. .IR "Section 2.6" ", " "Word Expansions"
  184. .P
  185. The Base Definitions volume of POSIX.1\(hy2017,
  186. .IR "\fB<fnmatch.h>\fP"
  187. .\"
  188. .SH COPYRIGHT
  189. Portions of this text are reprinted and reproduced in electronic form
  190. from IEEE Std 1003.1-2017, Standard for Information Technology
  191. -- Portable Operating System Interface (POSIX), The Open Group Base
  192. Specifications Issue 7, 2018 Edition,
  193. Copyright (C) 2018 by the Institute of
  194. Electrical and Electronics Engineers, Inc and The Open Group.
  195. In the event of any discrepancy between this version and the original IEEE and
  196. The Open Group Standard, the original IEEE and The Open Group Standard
  197. is the referee document. The original Standard can be obtained online at
  198. http://www.opengroup.org/unix/online.html .
  199. .PP
  200. Any typographical or formatting errors that appear
  201. in this page are most likely
  202. to have been introduced during the conversion of the source files to
  203. man page format. To report such errors, see
  204. https://www.kernel.org/doc/man-pages/reporting_bugs.html .