# cPanel API 2 Functions - Fileman::search Warning: The cPanel API 2 system is deprecated. We **strongly** recommend that you use [UAPI](/cpanel/introduction) instead of cPanel API 2. ## Description This function recursively searches for a file within a directory. Warning: We **strongly** recommend that you use [UAPI](/cpanel/introduction/) instead of cPanel API 2. However, no equivalent UAPI function exists. Important: When you disable the [*File Storage* role](https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-use-server-profiles/#roles), the system **disables** this function. ## Examples WHM API (JSON) ```undefined syntaxhighlighter-pre https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Fileman&cpanel_jsonapi_func=search&dir=%2Fhome%2Fexample&attributes=user%7Cgroupusage%7Csize%7Ctype%7Cmode%7Cctime%7Catime%7Cmtime ``` Note: For more information, read our [Calls from the WHM API](/whm/use-whm-api-to-call-cpanel-api-and-uapi) documentation. LiveAPI PHP Class ```undefined syntaxhighlighter-pre $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Search for files that begin with /home/example $search_files = $cpanel->api2( 'Fileman', 'search', array( 'dir' => 'home/example' 'attributes' => 'user|groupusage|size|type|mode|ctime|atime|mtime' ); ``` Note: For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). LiveAPI Perl Module ```undefined syntaxhighlighter-pre my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Search for files that begin with /home/example my $search_files = $cpliveapi->api2( 'Fileman', 'search', { 'dir' => 'home/example' 'attributes' => 'user|groupusage|size|type|mode|ctime|atime|mtime' } ); ``` Note: For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). cPanel Tag System (deprecated) Warnings: - cPanel tags are **deprecated**. We **strongly** recommend that you **only** use the [LiveAPI](/guides/guide-to-the-liveapi-system) system to call the cPanel APIs. Examples are **only** present in order to help developers move from the old cPanel tag system to our [LiveAPI](/guides/guide-to-the-liveapi-system). - cPanel API 2 calls that use cPanel tags vary in code syntax and in their output. - For more information, read our [Deprecated cPanel Tag Usage](/cpanel-api-2/cpanel-api-2-deprecate-cpanel-tag-usage/) documentation. Command Line ```undefined syntaxhighlighter-pre cpapi2 --user=username Fileman search dir=home%2Fexample attributes=user%7Cgroupusage%7Csize%7Ctype%7Cmode%7Cctime%7Catime%7Cmtime ``` div Notes: - You **must** URI-encode values. - `username` represents your account-level username. - You **must** include the `--user=username` option. - For more information and additional output options, read our [Guide to cPanel API 2](/cpanel-api-2/) documentation or run the `cpapi2 --help` command. - If you run CloudLinux™, you **must** use the full path of the `cpapi2` command: ```undefined syntaxhighlighter-pre /usr/local/cpanel/bin/cpapi2 ``` br Output (JSON) ```undefined syntaxhighlighter-pre { "cpanelresult": { "apiversion": 2, "func": "search", "data": [ { "ctime": 1414597689, "mtime": 1414597689, "mode": 457, "file": "/home/example", "size": 4096, "mimeinfo": "homeb", "groupusage": 64768, "user": "example", "type": "dir", "atime": 1412105321 }, { "ctime": 1412105376, "mtime": 1412105376, "mode": 384, "file": "/home/example/.lastlogin", "size": 10, "mimeinfo": "text-x-generic", "groupusage": 64768, "user": "example", "type": "file", "atime": 1412105376 }, { "ctime": 1412233359, "mtime": 1412233359, "mode": 416, "file": "/home/example/cpbackup-exclude.conf", "size": 1, "mimeinfo": "text-plain", "groupusage": 64768, "user": "example", "type": "file", "atime": 1412233359 } ], "event": { "result": 1 }, "module": "Fileman" } } ``` Note: Use cPanel's *[API Shell](https://docs.cpanel.net/cpanel/advanced/api-shell-for-cpanel)* interface (*cPanel >> Home >> Advanced >> API Shell*) to directly test cPanel API calls. ## Parameters table thead tr th Parameter th Type th Description th Possible values th Example tbody tr td p code dir td em string td p The path to search. p This parameter defaults to the home directory. p The function also searches this directory's subdirectories if the code recursive value is code 1 . td Any valid absolute file path. td code /home/user tr td code attributes td em string td p A list of attributes to return for each result. p If you do not use this parameter, the function will strong not return any attributes. td ul li code user — Search for the file's owner's name. li code groupusage — Search for the file's group's name. li code size — Search for the file size. li code type — Search for the file type. li code mode — Search for the file's permissions. li code ctime — Search for the file's creation time. li code atime — Search for the last time that the file was accessed. li code mtime — Search for the last time that the file was modified. p Separate multiple attributes with the pipe character ( code | ). td code user|size|type|mode|ctime tr td code recursive td em Boolean td p Whether to perform the search recursively. p This parameter defaults to code 0 . td ul li code 1 — Search recursively. li code 0 — Do strong not search recursively. td code 1 tr td code mimeinfo td em Boolean td p Whether to return the code mimeinfo return. p This parameter defaults to code 1 . td ul li code 1 — Return the code mimeinfo return for each result. li code 0 — Do strong not return the code mimeinfo return for each result. td code 1 tr td code regex td em string td p A a Perl Compatible Regular Expression (PCRE) that filters the results. p If you do not use this parameter, the function returns information for all of a directory's files. td A valid PCRE. td code user ## Returns table thead tr th strong Return th strong Type th strong Description th strong Possible values th strong Example tbody tr td code atime td em integer td The file's last accessed time. td A a Unix time stamp . td code 1412105376 tr td code ctime td em integer td The file's creation time. td p A a Unix time stamp . td code 1413398577 tr td code file td em string td The file's name. td A valid path and filename. td code /home/example/cpbackup-exclude.conf tr td code groupusage td em integer td span The file owner's system group ID. td A positive integer. td code 64768 tr td code mimeinfo td em string td span The file's MIME type. td A valid MIME type. td code text-plain tr td code mode td em integer td span The file's permissions. td span A set of file permissions, in decimal notation format. td code 493 tr td code mtime td em integer td The file's last modification time. td A a Unix time stamp . td code 1413830456 tr td code size td em integer td The size of the file. td span A positive integer, in bytes. td code 4096 tr td code type td em string td span The item type. td ul li code file li code dir li code char li code block li code fifo li code link li code socket td code file tr td code user td em string td span The file owner's user ID. td span Any valid user ID on the server. td code example tr td code reason td em string td p A reason for failure p This function only returns a code reason value if an error occurred. td A string that describes the error. td code This is an error message. tr td code result td em Boolean td p Whether the function succeeded. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1