List the files and directories of a UNIX file path

You can use this operation to list the files and directories in a UNIX file path on a z/OS system.

HTTP method and URI path

GET /zosmf/restfiles/fs?path=<filepath-name>

where:

/zosmf/restfiles specifies the z/OS® data set and file REST interface
/fs identifies a UNIX file path request
?path=<filepath-name> is a query parameter that specifies the directory containing the files and directories to be listed.

Standard headers

None.

Custom headers

You can include the following custom HTTP header with this request:

X-IBM-Max-Items: This header value specifies the maximum number of items to return. To request that all items be returned, set this header to 0. If you omit this header, or specify an incorrect value, up to 1000 items are returned by default.
X-IBM-Lstat: If the value of this header is "true", an lstat() is performed on the path rather than stat() and a list containing one item is returned with the lstat results. For more information regarding lstat() and stat(), please refer to the z/OS XL C/C++ Runtime Library Reference.

Query parameters

Specify the following query parameter on this request:

path

This parameter identifies the UNIX directory that contains the files and directories to be listed. This parameter is required and can consist of one or more directories in the hierarchical file system structure, or a fully qualified file name. A fully qualified file name, which consists of the name of each directory in the path to a file plus the file name itself, can be up to 1023 bytes long. You cannot use wildcard characters for this parameter.

The following list contains sample file path names:

 /
 /bin
 /usr/lib/libSM.a

Required authorizations

See Required authorizations.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

For a successful request, the HTTP response includes an array of matching of UNIX files and directories, each as a JSON list document. For the contents, see File list document.

For errors, the HTTP response includes error information as a JSON error report document. See Error report document.

Example request

In the following example, the GET method is used to list the files and directories in the UNIX path /usr:

GET /zosmf/restfiles/fs?path=/usr HTTP/1.1

Example response

A sample response is shown in Figure 1.

Figure 1. Example: Returned list of UNIX files and directories in path /usr

Response

200 OK
X-Powered-By:  Servlet/3.0
Content-Type:  application/json; charset=UTF-8
Content-Length:  896
Content-Language:  en-US
Date:  Tue, 24 Nov 2015 06:12:16 GMT

Response Body

{"items":[
{"name":".", "mode":"drwxrwxrwx", "size":8192, "uid":0, "user":"WSADMIN", "gid":1, 
"group":"OMVSGRP", "mtime":"2015-11-24T02:12:04"},
{"name":"..", "mode":"drwxr-xr-x", "size":8192, "uid":0, "user":"WSADMIN", "gid":1, 
"group":"OMVSGRP", "mtime":"2015-09-15T02:38:29"},
{"name":".profile", "mode":"-rwxrwxrwx", "size":849, "uid":0, "user":"WSADMIN", "gid":1, 
"group":"OMVSGRP", "mtime":"2013-02-13T12:08:29"},
{"name":".sh_history", "mode":"-rw-------", "size":4662, "uid":0, "user":"WSADMIN", "gid":1, 
"group":"OMVSGRP", "mtime":"2013-06-06T18:09:28"},
{"name":"myFile.txt", "mode":"-rw-r--r--", "size":20, "uid":0, "user":"WSADMIN", "gid":1, 
"group":"OMVSGRP", "mtime":"2015-11-24T02:12:04"},
{"name":"profile.add", "mode":"-rwxrwxrwx", "size":888, "uid":0, "user":"WSADMIN", "gid":1, 
"group":"OMVSGRP", "mtime":"2013-05-07T11:23:08"}
],"returnedRows":6,"totalRows":6,"JSONversion":1}

Example request

In the following example, the GET method is used to list a Unix file

GET /zosmf/restfiles/fs?path=/u/ibmuser/myFile.txt HTTP/1.1

Example response

A sample response is shown in Example: Returned list of UNIX files.

Figure 2. Example: Returned list of UNIX files

Response

200 OK
X-Powered-By:  Servlet/3.0
Content-Type:  application/json; charset=UTF-8
Content-Length:  210
Content-Language:  en-US
Date:  Tue, 24 Nov 2015 09:16:49 GMT

Response Body

{"items":[
{"name":"/u/ibmuser/myFile.txt", "mode":"-rw-r--r--", "size":20, "uid":0, "user":"WSADMIN",
"gid":1, "group":"OMVSGRP", "mtime":"2015-11-24T02:12:04"}
],"totalRows":1,"returnedRows":1},"JSONversion":1}