libssh2

1
.\" Copyright (C) The libssh2 project and its contributors.
2
.\" SPDX-License-Identifier: BSD-3-Clause
3
.TH libssh2_sftp_stat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2"
4
.SH NAME
5
libssh2_sftp_stat_ex - get status about an SFTP file
6
.SH SYNOPSIS
7
.nf
8
#include <libssh2.h>
9
#include <libssh2_sftp.h>
10

11
int
12
libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path,
13
                     unsigned int path_len, int stat_type,
14
                     LIBSSH2_SFTP_ATTRIBUTES *attrs);
15
.fi
16
.SH DESCRIPTION
17
\fIsftp\fP - SFTP instance as returned by
18
.BR libssh2_sftp_init(3)
19

20
\fIpath\fP - Remote filesystem object to stat/lstat/setstat.
21

22
\fIpath_len\fP - Length of the name of the remote filesystem object
23
to stat/lstat/setstat.
24

25
\fIstat_type\fP - One of the three constants specifying the type of
26
stat operation to perform:
27

28
.br
29
\fBLIBSSH2_SFTP_STAT\fP: performs stat(2) operation
30
.br
31
\fBLIBSSH2_SFTP_LSTAT\fP: performs lstat(2) operation
32
.br
33
\fBLIBSSH2_SFTP_SETSTAT\fP: performs operation to set stat info on file
34

35
\fIattrs\fP - Pointer to a \fBLIBSSH2_SFTP_ATTRIBUTES\fP structure to set file
36
metadata from or into depending on the value of stat_type.
37

38
Get or Set statbuf type data on a remote filesystem object. When getting
39
statbuf data,
40
.BR libssh2_sftp_stat(3)
41
will follow all symlinks, while
42
.BR libssh2_sftp_lstat(3)
43
will return data about the object encountered, even if that object
44
happens to be a symlink.
45

46
The LIBSSH2_SFTP_ATTRIBUTES struct looks like this:
47

48
.nf
49
struct LIBSSH2_SFTP_ATTRIBUTES {
50
    /* If flags & ATTR_* bit is set, then the value in this struct will be
51
     * meaningful Otherwise it should be ignored
52
     */
53
    unsigned long flags;
54

55
    libssh2_uint64_t filesize;
56
    unsigned long uid;
57
    unsigned long gid;
58
    unsigned long permissions;
59
    unsigned long atime;
60
    unsigned long mtime;
61
};
62
.fi
63
.SH RETURN VALUE
64
Returns 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN
65
when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative
66
number, it is not really a failure per se.
67
.SH ERRORS
68
\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed.
69

70
\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
71

72
\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP -
73

74
\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was
75
received on the socket, or an SFTP operation caused an errorcode to
76
be returned by the server.
77
.SH SEE ALSO
78
.BR libssh2_sftp_init(3)
79