bpo-31368: Enhance os.preadv() documentation (GH-7254) · python/cpython@02e2a08 (original) (raw)

`` @@ -1082,20 +1082,81 @@ or the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>_ on Windo

1082

` .. versionadded:: 3.3

1083

1084

1085

.. function:: pread(fd, buffersize, offset)

1085

.. function:: pread(fd, n, offset)

1086

1087

Read from a file descriptor, fd, at a position of offset. It will read up

1088

to buffersize number of bytes. The file offset remains unchanged.

1087

Read at most n bytes from file descriptor fd at a position of offset,

1088

leaving the file offset unchanged.

1089

+

1090

Return a bytestring containing the bytes read. If the end of the file

1091

referred to by fd has been reached, an empty bytes object is returned.

1089

1092

1090

1093

` Availability: Unix.

1091

1094

1092

1095

` .. versionadded:: 3.3

1093

1096

1094

1097

1098

.. function:: preadv(fd, buffers, offset, flags=0)

1099

+

1100

Read from a file descriptor fd at a position of offset into mutable

1101

`` +

:term:bytes-like objects <bytes-like object> buffers, leaving the file

1102

offset unchanged. Transfer data into each buffer until it is full and then

1103

move on to the next buffer in the sequence to hold the rest of the data.

1104

+

1105

The flags argument contains a bitwise OR of zero or more of the following

1106

flags:

1107

+

1108

`` +

:data:RWF_HIPRI

1109

`` +

:data:RWF_NOWAIT

1110

+

1111

Return the total number of bytes actually read which can be less than the

1112

total capacity of all the objects.

1113

+

1114

`` +

The operating system may set a limit (:func:sysconf value

1115


 ``'SC_IOV_MAX'``) on the number of buffers that can be used.

1116

+

1117

`` +

Combine the functionality of :func:os.readv and :func:os.pread.

1118

+

1119

Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,

1120

OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.

1121

+

1122

.. versionadded:: 3.7

1123

+

1124

+

1125

.. data:: RWF_NOWAIT

1126

+

1127

Do not wait for data which is not immediately available. If this flag is

1128

specified, the system call will return instantly if it would have to read

1129

data from the backing storage or wait for a lock.

1130

+

1131

If some data was successfully read, it will return the number of bytes read.

1132


 If no bytes were read, it will return ``-1`` and set errno to

1133

`` +

:data:errno.EAGAIN.

1134

+

1135

Availability: Linux 4.14 and newer.

1136

+

1137

.. versionadded:: 3.7

1138

+

1139

+

1140

.. data:: RWF_HIPRI

1141

+

1142

High priority read/write. Allows block-based filesystems to use polling

1143

of the device, which provides lower latency, but may use additional

1144

resources.

1145

+

1146

Currently, on Linux, this feature is usable only on a file descriptor opened

1147

`` +

using the :data:O_DIRECT flag.

1148

+

1149

Availability: Linux 4.6 and newer.

1150

+

1151

.. versionadded:: 3.7

1152

+

1153

+

1095

1154

`.. function:: pwrite(fd, str, offset)

1096

1155

1097

Write bytestring to a file descriptor, fd, from offset,

1098

leaving the file offset unchanged.

1156

Write the bytestring in str to file descriptor fd at position of

1157

offset, leaving the file offset unchanged.

1158

+

1159

Return the number of bytes actually written.

1099

1160

1100

1161

` Availability: Unix.

1101

1162

`` @@ -1104,54 +1165,57 @@ or the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>_ on Windo

1104

1165

1105

1166

`.. function:: pwritev(fd, buffers, offset, flags=0)

1106

1167

1107

`` -

Combines the functionality of :func:os.writev and :func:os.pwrite. It

1108

writes the contents of buffers to file descriptor fd at offset offset.

1109

`` -

buffers must be a sequence of :term:bytes-like objects <bytes-like object>.

1110

Buffers are processed in array order. Entire contents of first buffer is written

1111

before proceeding to second, and so on. The operating system may set a limit

1112

(sysconf() value SC_IOV_MAX) on the number of buffers that can be used.

1113

`` -

:func:~os.pwritev writes the contents of each object to the file descriptor

1114

and returns the total number of bytes written.

1168

Write the buffers contents to file descriptor fd at a offset offset,

1169

leaving the file offset unchanged. buffers must be a sequence of

1170

`` +

:term:bytes-like objects <bytes-like object>. Buffers are processed in

1171

array order. Entire contents of the first buffer is written before

1172

proceeding to the second, and so on.

1115

1173

1116

The flags argument contains a bitwise OR of zero or more of the following

1174

The flags argument contains a bitwise OR of zero or more of the following

1117

1175

` flags:

1118

1176

1119

RWF_DSYNC

1120

RWF_SYNC

1177

`` +

:data:RWF_DSYNC

1178

`` +

:data:RWF_SYNC

1121

1179

1122

Using non-zero flags requires Linux 4.7 or newer.

1180

Return the total number of bytes actually written.

1123

1181

1124

Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,

1125

OpenBSD (version 2.7 and newer).

1182

`` +

The operating system may set a limit (:func:sysconf value

1183


 ``'SC_IOV_MAX'``) on the number of buffers that can be used.

1184

+

1185

`` +

Combine the functionality of :func:os.writev and :func:os.pwrite.

1186

+

1187

Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,

1188

OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.

1126

1189

1127

1190

` .. versionadded:: 3.7

1128

1191

1192

+

1129

1193

`.. data:: RWF_DSYNC

1130

1194

1131

Provide a per-write equivalent of the O_DSYNC open(2) flag. This flag

1132

is meaningful only for pwritev2(), and its effect applies only to the

1133

data range written by the system call.

1195


 Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This

1196

flag effect applies only to the data range written by the system call.

1134

1197

1135

Availability: Linux (version 4.7).

1198

Availability: Linux 4.7 and newer.

1136

1199

1137

1200

` .. versionadded:: 3.7

1138

1201

1202

+

1139

1203

`.. data:: RWF_SYNC

1140

1204

1141

Provide a per-write equivalent of the O_SYNC open(2) flag. This flag is

1142

meaningful only for pwritev2(), and its effect applies only to the data

1143

range written by the system call.

1205


 Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This

1206

flag effect applies only to the data range written by the system call.

1144

1207

1145

Availability: Linux (version 4.7).

1208

Availability: Linux 4.7 and newer.

1146

1209

1147

1210

` .. versionadded:: 3.7

1148

1211

1149

1212

1150

1213

`.. function:: read(fd, n)

1151

1214

1152

Read at most n bytes from file descriptor fd. Return a bytestring containing the

1153

bytes read. If the end of the file referred to by fd has been reached, an

1154

empty bytes object is returned.

1215

Read at most n bytes from file descriptor fd.

1216

+

1217

Return a bytestring containing the bytes read. If the end of the file

1218

referred to by fd has been reached, an empty bytes object is returned.

1155

1219

1156

1220

` .. note::

1157

1221

`` @@ -1230,66 +1294,19 @@ or the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>_ on Windo

1230

1294

`.. function:: readv(fd, buffers)

1231

1295

1232

1296

`` Read from a file descriptor fd into a number of mutable :term:`bytes-like

1233

`` -

objects *buffers*. :func:~os.readv` will transfer data

1234

into each buffer until it is full and then move on to the next buffer in the

1235

`` -

sequence to hold the rest of the data. :func:~os.readv returns the total

1236

number of bytes read (which may be less than the total capacity of all the

1237

objects).

1297

`` +

objects ` buffers. Transfer data into each buffer until

1298

it is full and then move on to the next buffer in the sequence to hold the

1299

rest of the data.

1238

1300

1239

Availability: Unix.

1240

-

1241

.. versionadded:: 3.3

1301

Return the total number of bytes actually read which can be less than the

1302

total capacity of all the objects.

1242

1303

1304

`` +

The operating system may set a limit (:func:sysconf value

1305


 ``'SC_IOV_MAX'``) on the number of buffers that can be used.

1243

1306

1244

.. function:: preadv(fd, buffers, offset, flags=0)

1245

-

1246

`` -

Combines the functionality of :func:os.readv and :func:os.pread. It

1247

`` -

reads from a file descriptor fd into a number of mutable :term:`bytes-like

1248

`` -

objects *buffers*. As :func:os.readv`, it will transfer

1249

data into each buffer until it is full and then move on to the next buffer in

1250

the sequence to hold the rest of the data. Its fourth argument, offset,

1251

specifies the file offset at which the input operation is to be performed.

1252

`` -

:func:~os.preadv return the total number of bytes read (which can be less than

1253

the total capacity of all the objects).

1254

-

1255

The flags argument contains a bitwise OR of zero or more of the following

1256

flags:

1257

-

1258

RWF_HIPRI

1259

RWF_NOWAIT

1260

-

1261

Using non-zero flags requires Linux 4.6 or newer.

1262

-

1263

Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,

1264

OpenBSD (version 2.7 and newer).

1265

-

1266

.. versionadded:: 3.7

1267

-

1268

-

1269

.. data:: RWF_HIPRI

1270

-

1271

High priority read/write. Allows block-based filesystems to use polling

1272

of the device, which provides lower latency, but may use additional

1273

resources. (Currently, this feature is usable only on a file descriptor

1274

opened using the O_DIRECT flag.)

1275

-

1276

Availability: Linux (version 4.6).

1277

-

1278

.. versionadded:: 3.7

1279

-

1280

-

1281

.. data:: RWF_NOWAIT

1282

-

1283

Do not wait for data which is not immediately available. If this flag

1284

is specified, the preadv2() system call will return instantly

1285

if it would have to read data from the backing storage or wait for a lock.

1286

If some data was successfully read, it will return the number of bytes

1287

read. If no bytes were read, it will return -1 and set errno to EAGAIN.

1288

Currently, this flag is meaningful only for preadv2().

1289

-

1290

Availability: Linux (version 4.14).

1307

Availability: Unix.

1291

1308

1292

.. versionadded:: 3.7

1309

.. versionadded:: 3.3

1293

1310

1294

1311

1295

1312

`.. function:: tcgetpgrp(fd)

`` @@ -1319,8 +1336,9 @@ or the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>_ on Windo

1319

1336

1320

1337

`.. function:: write(fd, str)

1321

1338

1322

Write the bytestring in str to file descriptor fd. Return the number of

1323

bytes actually written.

1339

Write the bytestring in str to file descriptor fd.

1340

+

1341

Return the number of bytes actually written.

1324

1342

1325

1343

` .. note::

1326

1344

`` @@ -1338,14 +1356,15 @@ or the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>_ on Windo

1338

1356

1339

1357

`.. function:: writev(fd, buffers)

1340

1358

1341

Write the contents of buffers to file descriptor fd. buffers must be a

1342

`` -

sequence of :term:bytes-like objects <bytes-like object>. Buffers are

1343

processed in array order. Entire contents of first buffer is written before

1344

proceeding to second, and so on. The operating system may set a limit

1345

(sysconf() value SC_IOV_MAX) on the number of buffers that can be used.

1359

Write the contents of buffers to file descriptor fd. buffers must be

1360

`` +

a sequence of :term:bytes-like objects <bytes-like object>. Buffers are

1361

processed in array order. Entire contents of the first buffer is written

1362

before proceeding to the second, and so on.

1363

+

1364

Returns the total number of bytes actually written.

1346

1365

1347

`` -

:func:~os.writev writes the contents of each object to the file descriptor

1348

and returns the total number of bytes written.

1366

`` +

The operating system may set a limit (:func:sysconf value

1367


``'SC_IOV_MAX'``) on the number of buffers that can be used.

1349

1368

1350

1369

` Availability: Unix.

1351

1370