/usr.bin/locate/locate/locate.1

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 276 lines · 276 code · 0 blank · 0 comment · 0 complexity · 0ce59d025fa21e3a6a7258d0db318554 MD5 · raw file

  1. .\" Copyright (c) 1995 Wolfram Schneider <wosch@FreeBSD.org>. Berlin.
  2. .\" Copyright (c) 1990, 1993
  3. .\" The Regents of the University of California. All rights reserved.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\" 3. All advertising materials mentioning features or use of this software
  14. .\" must display the following acknowledgement:
  15. .\" This product includes software developed by the University of
  16. .\" California, Berkeley and its contributors.
  17. .\" 4. Neither the name of the University nor the names of its contributors
  18. .\" may be used to endorse or promote products derived from this software
  19. .\" without specific prior written permission.
  20. .\"
  21. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31. .\" SUCH DAMAGE.
  32. .\"
  33. .\" @(#)locate.1 8.1 (Berkeley) 6/6/93
  34. .\" $FreeBSD$
  35. .\"
  36. .Dd August 17, 2006
  37. .Dt LOCATE 1
  38. .Os
  39. .Sh NAME
  40. .Nm locate
  41. .Nd find filenames quickly
  42. .Sh SYNOPSIS
  43. .Nm
  44. .Op Fl 0Scims
  45. .Op Fl l Ar limit
  46. .Op Fl d Ar database
  47. .Ar pattern ...
  48. .Sh DESCRIPTION
  49. The
  50. .Nm
  51. program searches a database for all pathnames which match the specified
  52. .Ar pattern .
  53. The database is recomputed periodically (usually weekly or daily),
  54. and contains the pathnames
  55. of all files which are publicly accessible.
  56. .Pp
  57. Shell globbing and quoting characters
  58. .Dq ( * ,
  59. .Dq \&? ,
  60. .Dq \e ,
  61. .Dq \&[
  62. and
  63. .Dq \&] )
  64. may be used in
  65. .Ar pattern ,
  66. although they will have to be escaped from the shell.
  67. Preceding any character with a backslash
  68. .Pq Dq \e
  69. eliminates any special
  70. meaning which it may have.
  71. The matching differs in that no characters must be matched explicitly,
  72. including slashes
  73. .Pq Dq / .
  74. .Pp
  75. As a special case, a pattern containing no globbing characters
  76. .Pq Dq foo
  77. is matched as though it were
  78. .Dq *foo* .
  79. .Pp
  80. Historically, locate only stored characters between 32 and 127.
  81. The
  82. current implementation store any character except newline
  83. .Pq Sq \en
  84. and
  85. .Dv NUL
  86. .Pq Sq \e0 .
  87. The 8-bit character support does not waste extra space for
  88. plain ASCII file names.
  89. Characters less than 32 or greater than 127
  90. are stored in 2 bytes.
  91. .Pp
  92. The following options are available:
  93. .Bl -tag -width 10n
  94. .It Fl 0
  95. Print pathnames separated by an
  96. .Tn ASCII
  97. .Dv NUL
  98. character (character code 0) instead of default NL
  99. (newline, character code 10).
  100. .It Fl S
  101. Print some statistics about the database and exit.
  102. .It Fl c
  103. Suppress normal output; instead print a count of matching file names.
  104. .It Fl d Ar database
  105. Search in
  106. .Ar database
  107. instead of the default file name database.
  108. Multiple
  109. .Fl d
  110. options are allowed.
  111. Each additional
  112. .Fl d
  113. option adds the specified database to the list
  114. of databases to be searched.
  115. .Pp
  116. The option
  117. .Ar database
  118. may be a colon-separated list of databases.
  119. A single colon is a reference
  120. to the default database.
  121. .Bd -literal
  122. $ locate -d $HOME/lib/mydb: foo
  123. .Ed
  124. .Pp
  125. will first search string
  126. .Dq foo
  127. in
  128. .Pa $HOME/lib/mydb
  129. and then in
  130. .Pa /var/db/locate.database .
  131. .Bd -literal
  132. $ locate -d $HOME/lib/mydb::/cdrom/locate.database foo
  133. .Ed
  134. .Pp
  135. will first search string
  136. .Dq foo
  137. in
  138. .Pa $HOME/lib/mydb
  139. and then in
  140. .Pa /var/db/locate.database
  141. and then in
  142. .Pa /cdrom/locate.database .
  143. .Pp
  144. .Dl "$ locate -d db1 -d db2 -d db3 pattern"
  145. .Pp
  146. is the same as
  147. .Pp
  148. .Dl "$ locate -d db1:db2:db3 pattern"
  149. .Pp
  150. or
  151. .Pp
  152. .Dl "$ locate -d db1:db2 -d db3 pattern"
  153. .Pp
  154. If
  155. .Fl
  156. is given as the database name, standard input will be read instead.
  157. For example, you can compress your database
  158. and use:
  159. .Bd -literal
  160. $ zcat database.gz | locate -d - pattern
  161. .Ed
  162. .Pp
  163. This might be useful on machines with a fast CPU and little RAM and slow
  164. I/O.
  165. Note: you can only use
  166. .Em one
  167. pattern for stdin.
  168. .It Fl i
  169. Ignore case distinctions in both the pattern and the database.
  170. .It Fl l Ar number
  171. Limit output to
  172. .Ar number
  173. of file names and exit.
  174. .It Fl m
  175. Use
  176. .Xr mmap 2
  177. instead of the
  178. .Xr stdio 3
  179. library.
  180. This is the default behavior
  181. and is faster in most cases.
  182. .It Fl s
  183. Use the
  184. .Xr stdio 3
  185. library instead of
  186. .Xr mmap 2 .
  187. .El
  188. .Sh ENVIRONMENT
  189. .Bl -tag -width LOCATE_PATH -compact
  190. .It Pa LOCATE_PATH
  191. path to the locate database if set and not empty, ignored if the
  192. .Fl d
  193. option was specified.
  194. .El
  195. .Sh FILES
  196. .Bl -tag -width /etc/periodic/weekly/310.locate -compact
  197. .It Pa /var/db/locate.database
  198. locate database
  199. .It Pa /usr/libexec/locate.updatedb
  200. Script to update the locate database
  201. .It Pa /etc/periodic/weekly/310.locate
  202. Script that starts the database rebuild
  203. .El
  204. .Sh SEE ALSO
  205. .Xr find 1 ,
  206. .Xr whereis 1 ,
  207. .Xr which 1 ,
  208. .Xr fnmatch 3 ,
  209. .Xr locate.updatedb 8
  210. .Rs
  211. .%A Woods, James A.
  212. .%D 1983
  213. .%T "Finding Files Fast"
  214. .%J ";login"
  215. .%V 8:1
  216. .%P pp. 8-10
  217. .Re
  218. .Sh HISTORY
  219. The
  220. .Nm
  221. command first appeared in
  222. .Bx 4.4 .
  223. Many new features were
  224. added in
  225. .Fx 2.2 .
  226. .Sh BUGS
  227. The
  228. .Nm
  229. program may fail to list some files that are present, or may
  230. list files that have been removed from the system.
  231. This is because
  232. locate only reports files that are present in the database, which is
  233. typically only regenerated once a week by the
  234. .Pa /etc/periodic/weekly/310.locate
  235. script.
  236. Use
  237. .Xr find 1
  238. to locate files that are of a more transitory nature.
  239. .Pp
  240. The
  241. .Nm
  242. database is typically built by user
  243. .Dq nobody
  244. and the
  245. .Xr locate.updatedb 8
  246. utility skips directories
  247. which are not readable for user
  248. .Dq nobody ,
  249. group
  250. .Dq nobody ,
  251. or
  252. world.
  253. For example, if your HOME directory is not world-readable,
  254. .Em none
  255. of your files are
  256. in the database.
  257. .Pp
  258. The
  259. .Nm
  260. database is not byte order independent.
  261. It is not possible
  262. to share the databases between machines with different byte order.
  263. The current
  264. .Nm
  265. implementation understands databases in host byte order or
  266. network byte order if both architectures use the same integer size.
  267. So on a
  268. .Fx Ns /i386
  269. machine
  270. (little endian), you can read
  271. a locate database which was built on SunOS/sparc machine
  272. (big endian, net).
  273. .Pp
  274. The
  275. .Nm
  276. utility does not recognize multibyte characters.